Get what a task used and what it cost
GET /tasks/{id}/usage
Requires: tasks.read
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Resource ULID.
Header Parameters
Section titled “Header Parameters ”Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.
Responses
Section titled “ Responses ”Successful response.
object
The task’s AI usage, over every agent turn recorded.
object
The engine CLI’s estimate at API list prices: separate from Managed Engine credit debits. A subscription may cost less. Summed over the turns that reported a cost (pricedTurns); 0 when none did.
Turns that reported a cost estimate. When fewer than turns, costUsd is partial.
Turns that ran on a custom connection. Their cost is unknown unless OpenRouter’s public list price covered every part of the turn (catalogTurns).
Connection turns priced from OpenRouter’s public list prices: an estimate, not OpenRouter’s charge.
The task’s AI usage grouped by persona when known, with a conservative handle-family fallback for legacy rows.
object
Historical persona provenance when known; null for ad-hoc or legacy handles.
The persona/task label, or a readable legacy-handle fallback.
The grouped task-local handles, with a base handle before its numbered successors.
True when any grouped handle is still on the crew.
Per-handle engine, model, account and ungrouped usage figures.
object
One task-local agent handle.
The handle’s engine.
The handle’s selected or last-reported model.
Whether this handle is still on the crew.
The engine CLI’s estimate at API list prices: separate from Managed Engine credit debits. A subscription may cost less. Summed over the turns that reported a cost (pricedTurns); 0 when none did.
Turns that reported a cost estimate. When fewer than turns, costUsd is partial.
Turns that ran on a custom connection. Their cost is unknown unless OpenRouter’s public list price covered every part of the turn (catalogTurns).
Connection turns priced from OpenRouter’s public list prices: an estimate, not OpenRouter’s charge.
The engine CLI’s estimate at API list prices: separate from Managed Engine credit debits. A subscription may cost less. Summed over the turns that reported a cost (pricedTurns); 0 when none did.
Turns that reported a cost estimate. When fewer than turns, costUsd is partial.
Turns that ran on a custom connection. Their cost is unknown unless OpenRouter’s public list price covered every part of the turn (catalogTurns).
Connection turns priced from OpenRouter’s public list prices: an estimate, not OpenRouter’s charge.
The AI accounts the agents are on, and the Moondeck Managed Engine’s credit when an agent runs on it.
object
object
The AI account’s id (Connections → AI Accounts).
How it is paid for. unknown: a Claude token, which may be a subscription sign-in or an API key; Moondeck does not record which. unverified: a billing class a runner hinted, or one whose writer was not recorded.
The account’s latest usage, as an engine CLI reported it while an agent ran on it. Moondeck never asks the provider itself.
object
As the engine last reported it.
As it reads now: a warning or limit whose reset time has passed is probably_reset. Without a top-level resetsAt, the windows at or above 75% used decide (every window, when none is at or above 75%): probably_reset once all of them are past their reset.
Whether the engine says it is billing past the plan; null when it did not say.
object
The engine’s name for the window: Claude’s five_hour, seven_day, …; Codex’s primary, secondary; Cursor’s included, api.
Its reset time has passed, so the share is probably spent.
When the engine said it, epoch ms.
How long before this response the reading was taken.
The reading is more than a day old.
A custom connection: billed as a provider key, its account limits not reported.
Why usage is null when the provider does not report account limits.
Handles of the agents on it: as their runner last reported, else as pinned.
Agents running on it while pinned to another account (that one was benched).
object
The label of the account it is pinned to.
object
Agents whose account Moondeck has not heard of yet.
Whether this task’s runner leases the cloud AI-account list. False means it uses its own signed-in accounts: subscriptions only then refuses the Managed Engine and does not control those logins.
object
Why no AI account can run on this task’s runner.
The whole notice as plain text.
Set when the workspace’s Managed Engine credit is spent too, so not even it can run here: add credit in Billing.
object
Update: the runner predates cloud AI accounts. waiting: it reports where its switch stands and what stops it. unreported: it has not switched and is too old to say why.
A command to run on the runner that clears what stops it, or shows why.
object
Credits debited while the task’s machine ran, in minor units.
Credits debited while it was parked, in minor units.
Token-meter ledger attribution, approximate due to workspace-wide cent carry; retained for older clients.
Web-search ledger attribution, approximate due to workspace-wide cent carry; retained for older clients.
Search count from cent-crossing ledger rows; approximate and retained for older clients.
Only ledger debits without a per-call record: approximate attribution before the recording cutover or from an old gateway.
object
Exact per-call task costs and search count since recording began, including fractional-cent calls without ledger rows.
object
UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan
SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.
object
object
Stable, machine-readable error code
Human-readable explanation
Present on 403 — the permission the caller lacked
Present on 402 — gated feature
Present on 402 — the plan’s cap
Present on 402 — the current plan