Jump toUsage and budgets

Usage and budgets

What your organization spent and the budgets that cap it.

get/v1/budgets

Get budgets

Needs usage.view

Response200

objectstring
budgets
ancestorsAncestorBudget[]
6 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- ownerstring
- scopestring
  ancestor
organizationOrgBudget
12 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- editableboolean
- min_allowed_microsmap<string, integer>
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- ownerstring
- scopestring
  organization
- set_bystring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
platform_keysPlatformQuota or null
5 fields
- objectstring
  budget
- amount_microsinteger
- resets_atstring
- scopestring
  platform_keys
- spent_microsinteger
workspacesWorkspaceBudget[]
13 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- row_versioninteger
- scopestring
  workspace
- workspace_idstring
- workspace_namestring
- created_atstring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null

Status codes

200Successful Response
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/budgets" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "budgets",
  "ancestors": [
    {
      "object": "budget",
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "owner": "owner",
      "scope": "ancestor"
    }
  ],
  "organization": {
    "object": "budget",
    "daily": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "editable": true,
    "min_allowed_micros": {
      "key": 2
    },
    "mode": "soft",
    "monthly": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "notify_at": [
      2
    ],
    "owner": "owner",
    "scope": "organization",
    "set_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "updated_at": "2026-11-10T09:30:00.000Z",
    "updated_by": {
      "kind": "user",
      "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  },
  "platform_keys": {
    "object": "budget",
    "amount_micros": 1250000,
    "resets_at": "2026-11-10T09:30:00.000Z",
    "scope": "platform_keys",
    "spent_micros": 1250000
  },
  "workspaces": [
    {
      "object": "budget",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "notify_at": [
        2
      ],
      "row_version": 4,
      "scope": "workspace",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h",
      "workspace_name": "workspace name"
    }
  ]
}

put/v1/budgets/organization

Put org budget

Needs budget.manage

Request bodyBudgetWrite

daily_usd_microsinteger or null
at most 100000000000000more than 0
modestring
One ofsofthardDefault"hard"
monthly_usd_microsinteger or null
at most 100000000000000more than 0
notify_atinteger[]
at most 5 items

Response200

objectstring
budgets
ancestorsAncestorBudget[]
6 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- ownerstring
- scopestring
  ancestor
organizationOrgBudget
12 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- editableboolean
- min_allowed_microsmap<string, integer>
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- ownerstring
- scopestring
  organization
- set_bystring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
platform_keysPlatformQuota or null
5 fields
- objectstring
  budget
- amount_microsinteger
- resets_atstring
- scopestring
  platform_keys
- spent_microsinteger
workspacesWorkspaceBudget[]
13 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- row_versioninteger
- scopestring
  workspace
- workspace_idstring
- workspace_namestring
- created_atstring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/budgets/organization" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_usd_micros": 1250000,
    "mode": "soft",
    "monthly_usd_micros": 1250000,
    "notify_at": [
      2
    ]
  }'

Response · 200

JSON

{
  "object": "budgets",
  "ancestors": [
    {
      "object": "budget",
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "owner": "owner",
      "scope": "ancestor"
    }
  ],
  "organization": {
    "object": "budget",
    "daily": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "editable": true,
    "min_allowed_micros": {
      "key": 2
    },
    "mode": "soft",
    "monthly": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "notify_at": [
      2
    ],
    "owner": "owner",
    "scope": "organization",
    "set_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "updated_at": "2026-11-10T09:30:00.000Z",
    "updated_by": {
      "kind": "user",
      "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  },
  "platform_keys": {
    "object": "budget",
    "amount_micros": 1250000,
    "resets_at": "2026-11-10T09:30:00.000Z",
    "scope": "platform_keys",
    "spent_micros": 1250000
  },
  "workspaces": [
    {
      "object": "budget",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "notify_at": [
        2
      ],
      "row_version": 4,
      "scope": "workspace",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h",
      "workspace_name": "workspace name"
    }
  ]
}

get/v1/usage

Get usage

Needs usage.view

Totals per group over whole UTC days, from and to included (default: this month so far). Quantities only add up within one meter: group by meter (or filter to one) to read them; money adds up across meters.

Query parameters

fromstring
date
tostring
date
group_bystring[]
One ofdaymetermodelproviderworkspaceagentkey_ownertestat most 3 items
meterstring[]
at most 20 items
workspace_idstring
agent_idstring

Response200

objectstring
list
as_ofstring or null
dataUsageRow[]
13 fields
- objectstring
  usage
- cost_microsinteger
- list_cost_microsinteger
- quantityinteger
- agent_idstring or null
- daystring or null
- is_testboolean or null
- key_ownerstring or null
- meterstring or null
- modelstring or null
- providerstring or null
- unitstring or null
- workspace_idstring or null
endstring
has_moreboolean
next_cursorstring or null
startstring

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl "https://api.mydeepagents.com/v1/usage" \
  -H "Authorization: Bearer $MDA_API_KEY"

Response · 200

JSON

{
  "object": "list",
  "as_of": "as of",
  "data": [
    {
      "object": "usage",
      "agent_id": "agt_01jctdbahw9btk5p831xs974yq",
      "cost_micros": 1250000,
      "day": "2026-11-10",
      "is_test": false,
      "key_owner": "key owner",
      "list_cost_micros": 1250000,
      "meter": "meter",
      "model": "claude-sonnet-5-5",
      "provider": "anthropic",
      "quantity": 2,
      "unit": "unit",
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h"
    }
  ],
  "end": "end",
  "has_more": false,
  "next_cursor": null,
  "start": "start"
}

put/v1/budgets/workspaces/{workspace_id}

Put workspace budget

Needs budget.manage

Path parameters

workspace_idstringRequired

Request bodyBudgetWrite

daily_usd_microsinteger or null
at most 100000000000000more than 0
modestring
One ofsofthardDefault"hard"
monthly_usd_microsinteger or null
at most 100000000000000more than 0
notify_atinteger[]
at most 5 items

Response200

objectstring
budgets
ancestorsAncestorBudget[]
6 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- ownerstring
- scopestring
  ancestor
organizationOrgBudget
12 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- editableboolean
- min_allowed_microsmap<string, integer>
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- ownerstring
- scopestring
  organization
- set_bystring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
platform_keysPlatformQuota or null
5 fields
- objectstring
  budget
- amount_microsinteger
- resets_atstring
- scopestring
  platform_keys
- spent_microsinteger
workspacesWorkspaceBudget[]
13 fields
- objectstring
  budget
- dailyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- modestring
  One ofsofthard
- monthlyBudgetPeriodOut
  3 fields
  amount_microsinteger or null
  resets_atstring
  spent_microsinteger
- notify_atinteger[]
- row_versioninteger
- scopestring
  workspace
- workspace_idstring
- workspace_namestring
- created_atstring or null
- created_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null
- updated_atstring or null
- updated_byActorRef or null
  Who created or last changed something, resolved to a name for display. system, workload (an automation) and end_user (a widget visitor) have no ID or name: the console words them. name is null for someone the directory no longer knows. id is what the lists' created_by/updated_by filters take. avatar_version is set for a person with a photo: it is at GET /v1/members/{id}/avatar?v=<avatar_version> while they are a member.
  5 fields
  idstring or null
  kindstring
  One ofuserapi_keyservice_accountworkloadend_usersystem
  namestring or null
  avatar_versionstring or null
  emailstring or null

Status codes

200Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X PUT "https://api.mydeepagents.com/v1/budgets/workspaces/ws_01jccj30nr8ad7mx1yc5v9zx3h" \
  -H "Authorization: Bearer $MDA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_usd_micros": 1250000,
    "mode": "soft",
    "monthly_usd_micros": 1250000,
    "notify_at": [
      2
    ]
  }'

Response · 200

JSON

{
  "object": "budgets",
  "ancestors": [
    {
      "object": "budget",
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "owner": "owner",
      "scope": "ancestor"
    }
  ],
  "organization": {
    "object": "budget",
    "daily": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "editable": true,
    "min_allowed_micros": {
      "key": 2
    },
    "mode": "soft",
    "monthly": {
      "amount_micros": 1250000,
      "resets_at": "2026-11-10T09:30:00.000Z",
      "spent_micros": 1250000
    },
    "notify_at": [
      2
    ],
    "owner": "owner",
    "scope": "organization",
    "set_by": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
    "updated_at": "2026-11-10T09:30:00.000Z",
    "updated_by": {
      "kind": "user",
      "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  },
  "platform_keys": {
    "object": "budget",
    "amount_micros": 1250000,
    "resets_at": "2026-11-10T09:30:00.000Z",
    "scope": "platform_keys",
    "spent_micros": 1250000
  },
  "workspaces": [
    {
      "object": "budget",
      "created_at": "2026-11-10T09:30:00.000Z",
      "created_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "daily": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "mode": "soft",
      "monthly": {
        "amount_micros": 1250000,
        "resets_at": "2026-11-10T09:30:00.000Z",
        "spent_micros": 1250000
      },
      "notify_at": [
        2
      ],
      "row_version": 4,
      "scope": "workspace",
      "updated_at": "2026-11-10T09:30:00.000Z",
      "updated_by": {
        "kind": "user",
        "id": "usr_01jcf1j9wjxfrnhqda3mq7ejxn",
        "name": "Ada Lovelace",
        "email": "ada@example.com"
      },
      "workspace_id": "ws_01jccj30nr8ad7mx1yc5v9zx3h",
      "workspace_name": "workspace name"
    }
  ]
}

delete/v1/budgets/workspaces/{workspace_id}

Delete workspace budget

Needs budget.manage

Path parameters

workspace_idstringRequired

Response204

Answers 204 with no body.

Status codes

204Successful Response
422The request is not valid: errors[] names each field.
4XXThe request was refused: the problem says why.
5XXThe API could not answer: the problem says why.

Request

curl -X DELETE "https://api.mydeepagents.com/v1/budgets/workspaces/ws_01jccj30nr8ad7mx1yc5v9zx3h" \
  -H "Authorization: Bearer $MDA_API_KEY"

Build with us

Ready for your first call?

Early access is open. Tell us what you want your agents to do, and we will help you get your first key.

Talk to us Read the API guide