Track usage and cost

Every session has one cost: what your credit balance is charged for its whole session tree. It covers the session and every subagent and teammate it started, and all of their model calls, provider tools such as a provider’s web search, and sandbox compute. Read it in the console or as costUsd on the session, and use costState to tell a final cost from one that can still grow.

Any organization role that can read sessions can read their cost: user, developer, or admin. The billing role cannot see sessions. See Organizations and roles and API keys. Credits are bought separately on the Billing screen; see Billing.

To estimate cost before a session, open an agent in the console. Its Estimated cost per session hour section shows what one session hour typically costs, priced on the compute you choose. Pick a model first to see an estimate. Pricing explains what that price covers.

Question	Operation
What did this session cost, and is that final?	`getSession`
What did each run in a list cost?	`listSessions` with `root_only=true`
How many events and tokens did each session in a list use?	`listSessionUsage`

Read one session’s cost

getSession returns costUsd and costState with the rest of the session, in both the full and summary views.

Console
cURL

The console shows one figure for the whole session tree: the session and every subagent and teammate under it.

In Sessions, read the Cost column.
Open the session. The session header and the Session tab of its details show the same Cost.
While the figure can still change, it reads so far. Session costs can take up to an hour to settle.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38?view=summary' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

Some fields are omitted from this response.

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "root_session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "session_path": "/",
  "status": "completed",
  "execution_state": "idle",
  "stop_reason": "end_turn",
  "costUsd": "1.234567",
  "costState": "final"
}

Record costUsd once costState is final (see Know when a figure is final).

Cost fields

Field	Description
`costUsd`	The billed cost of the whole session tree in US dollars: model calls, tools, and sandbox compute. This is what your balance is charged. Compute that is still running is included as an estimate.
`costState`	`final` or `so_far`. Present exactly when `costUsd` is.

A subagent or teammate session returns the cost of its whole tree, the same figure as its root. The cost is one total; it is not split by session, model call, or kind of charge.Both fields are absent when the cost can’t be read right now. An absent cost is not zero; read the session again later.

Compare many sessions

Rows from listSessions carry costUsd and costState too. Send root_only=true to get one row per run. A child session repeats its tree’s cost, so adding child rows counts the same cost twice.

cURL

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions?root_only=true&limit=50' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

For token counts, listSessionUsage takes session_ids, a comma-separated list of up to 1000 ids.

cURL

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/usage?session_ids=b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38,0c6f2b9e-4d17-4a38-b5e2-9f1a3c7d8e06' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "session_usage": [
    {
      "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
      "event_count": 214,
      "input_tokens": 182340,
      "output_tokens": 9215,
      "cache_read_tokens": 140112,
      "cache_write_tokens": 21480,
      "cost_micros": 420000
    }
  ]
}

Usage rows

listSessionUsage returns session_usage: the event count and token counts for each session’s own events. Children are not included. Unknown ids and sessions with no events are left out, so compare the number of rows with the number of ids you sent.
cost_micros is the cost the session’s own model events reported, in millionths of a US dollar. It is for diagnostics, not what your balance is charged: it leaves out child sessions and sandbox compute. Use costUsd on the session for what you are charged.

Know when a figure is final

`costState`	Meaning
`so_far`	The cost can still grow.
`final`	The session has ended, its sandbox has stopped, and every charge has settled. `costUsd` won’t change unless you resume the session.

Why a cost can still grow

The session is still running. The session or one of its subagents or teammates is working or waiting for you.
The sandbox is still running. A sandbox can keep running after the session ends, until the environment’s idle stop. Its compute is included as an estimate until it stops.
Charges are still settling. Session costs can take up to an hour to settle.
You resumed the session. A message that starts a new turn makes a final cost so_far again.

costUsd is an exact decimal string, such as "1.234567". Add costs with a decimal type, such as Decimal in Python or a decimal library in TypeScript. Floating-point sums drift.

Amount format

All amounts are in US dollars. No other currency is used.
costUsd has up to nine decimal places and no trailing zeros. A zero cost is "0".
cost_micros in usage rows is an integer in millionths of a dollar.

What can go wrong

The most common problems:

The cost changed after you recorded it. costState was so_far. Record the cost once it is final.
A list adds up to more than the runs cost. Child rows repeat their tree’s cost. Send root_only=true.
Usage cost_micros and costUsd differ. cost_micros covers only the session’s own model events and is for diagnostics. Use costUsd.

Every usage and cost error

Symptom or code	Cause	Fix
`costUsd` and `costState` are missing	The cost can’t be read right now.	Read the session again later. Don’t treat it as zero.
The cost changed after you recorded it	`costState` was `so_far`: the session, its sandbox, or its charges hadn’t settled, or it was resumed.	Record the cost once `costState` is `final`. See Know when a figure is final.
A list adds up to more than the runs cost	Child rows repeat their tree’s cost.	Send `root_only=true` and add root rows only.
Usage `cost_micros` and `costUsd` differ	`cost_micros` covers only the session’s own model events and is for diagnostics.	Use `costUsd`.
`400 invalid_request` on `session_ids`	The list is missing or has more than 1000 ids.	Split the list into batches of 1000.
`listSessionUsage` returns fewer rows than ids	Unknown ids and sessions with no events are left out.	Match rows by `session_id`.
`404 not_found`	The session does not exist or is outside your organization.	Check the id and your API key’s organization.
`429 rate_limit_exceeded`	Too many requests.	Wait for the time in `Retry-After`, then retry.

The full list of codes is in Errors.

Limits

Limit	Value
Ids in one `listSessionUsage` request	1000
Time for a session’s cost to settle	Up to an hour

Every other limit is on Limits.

Next steps

Billing

Buy the credits that session costs are charged to.

Teams

See why a team costs more than one agent.

Multi-agent

Understand the session trees behind one session cost.

Limits

Check quotas and request limits.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Track usage and cost

Read one session’s cost

Compare many sessions

Know when a figure is final

What can go wrong

Limits

Next steps

Billing

Teams

Multi-agent

Limits

​Read one session’s cost

​Compare many sessions

​Know when a figure is final

​What can go wrong

​Limits

​Next steps

Billing

Teams

Multi-agent

Limits

Read one session’s cost

Compare many sessions

Know when a figure is final

What can go wrong

Limits

Next steps