Report metered agent usage per account and category

GET /api/v1/agent-usage.json · operationId getAgentUsage

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open Charge › Usage (Usage) in the dashboard.

Retained tool executions and agent session-minutes for the requested period (default seven days, at most the Site usage retention). Totals and categories cover the whole period; accounts are paginated. Use for billing reconciliation; signed agent_usage.recorded webhooks carry the same units as they are ingested. No charges are created.

#Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

#Parameters

• from (query, string, optional): Period start: Unix epoch ms or ISO 8601 date. Defaults to the last 7 days: 7 whole UTC days ending today; clamped to the Site usage retention (90 days by default, up to 400 in Settings › Data).
• to (query, string, optional): Period end; defaults to now and never passes it.
• accountId (query, string, optional)
• limit (query, integer, optional): Account rows per page.
• cursor (query, string, optional): page.nextCursor from the previous response; it keeps that response period and account.
• series (query, "day" | "week", optional): Adds series: UTC-day or ISO-week buckets of the period that add up to totals.
• compare (query, "previous", optional): Adds previous (the period of the same length before since) and change.

#Responses

• 200: Agent usage report · body AgentUsage
• 400: bad_request: the request is invalid; message says what to fix and field names the request field · body Error
• 401: unauthorized (missing or invalid server key, missing Bearer scheme) · body Error
• 403: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body Error
• 404: not_found: nothing with this ID on this Site (or it is past retention), or an unknown path · body Error
• 429: rate_limited: wait for Retry-After · body Error · headers Retry-After
• 500: internal_error: fail the protected action; do not retry automatically · body Error
• 503: service_unavailable: temporarily unavailable; only verify retries · body Error

#Success body fields

Retained seven-day agent usage. Category and account are snapshots taken at ingestion; metered and included follow the current billing mode of each category (mode), for every retained chargeable unit; behaviour-only AI agent units are counted in the unit totals and behaviourOnly, never in metered or included. Unattributed means agent evidence without a named controller. Not an invoice.

• siteId (string, required)
• since (number, required): Unix epoch milliseconds.
• until (number, optional): Unix epoch milliseconds.
• asOf (number, required): Unix epoch milliseconds.
• window (string, optional): The period in words, for example "Oct 21 – Oct 27 UTC (last 7 days)".
• windowDays (number, optional): Length of the requested period in days.
• accountId (string, optional): Present when filtered to one account.
• clampedToRetention (boolean, optional): true when from was earlier than the Site usage retention (90 days by default, up to 400) and was moved forward.
• periodBounds ("[since, until)", optional): The period is half-open: a unit exactly at until belongs to the next period.
• coverageStart (number, optional): Earliest instant this report can cover: the later of since and the Site usage retention floor. Chargeable units are never removed by count caps.
• oldestRetainedAt (integer | null, optional): Timestamp of the oldest agent unit this Site still retains, in any period; null when none.
• page (object, optional)
• page.limit (integer, required)
• page.total (integer, required): Account rows in the whole period.
• page.nextCursor (string | null, required): Continues the same period and account in stable (accountId, source, category) order. Sending it with a different from, to or accountId is rejected with 400.
• totals (object, optional): toolExecutions and sessionMinutes count every agent unit shown; metered and included count chargeable units only; billable and behaviourOnly split the units by whether they count toward billing.
• categoriesUsed (integer, optional)
• categories (object[], required)
• categories[].category ("computer_use" | "browser_use" | "coding_agent" | "crawler" | "unattributed", required)
• categories[].label (string, required)
• categories[].mode ("metered" | "included", required)
• categories[].toolExecutions (integer, required)
• categories[].sessionMinutes (integer, required)
• categories[].metered (AgentUsageUnits, required)
• categories[].included (AgentUsageUnits, required)
• categories[].billable (AgentUsageUnits, required): Units that count toward billing: metered plus included.
• categories[].behaviourOnly (AgentUsageUnits, required): AI agent units whose verdict rests on behaviour alone (no verified identity or automation trace): shown, never charged. billable plus behaviourOnly equals the unit totals.
• categories[].tools (integer, required)
• categories[].accounts (integer, required)
• accounts (object[], required)
• accounts[].accountId (string | null, required)
• accounts[].source ("server-associated" | "browser-supplied" | "unattributed" | "not-recorded", required)
• accounts[].category ("computer_use" | "browser_use" | "coding_agent" | "crawler" | "unattributed", required)
• accounts[].currentResponse ("default" | "flagged" | "agent_seat", optional): Current per-account response setting.
• accounts[].toolExecutions (integer, required)
• accounts[].sessionMinutes (integer, required)
• accounts[].metered (AgentUsageUnits, required)
• accounts[].included (AgentUsageUnits, required)
• accounts[].billable (AgentUsageUnits, optional)
• accounts[].behaviourOnly (AgentUsageUnits, optional)
• accounts[].byResponse (object, optional): Units by the account response snapshotted at ingestion (default, flagged, agent_seat); older units without a snapshot are not counted here.
• agentsUsed (integer, required) · minimum 0: Distinct named controllers in the period.
• agents (object[], required): One row per controller and attribution strength. A controller is named only from signed or weak-marker attribution, or a crawler verified against the operator IP-range list (ip-verified), captured at ingestion; all other agent usage is one row with controller null and strength unattributed.
• agents[].controller (string | null, required)
• agents[].strength ("signed" | "weak-marker" | "ip-verified" | "unattributed", required)
• agents[].category ("computer_use" | "browser_use" | "coding_agent" | "crawler" | "unattributed", required)
• agents[].toolExecutions (integer, required)
• agents[].sessionMinutes (integer, required)
• agents[].metered (AgentUsageUnits, required)
• agents[].included (AgentUsageUnits, required)
• agents[].billable (AgentUsageUnits, required)
• agents[].behaviourOnly (AgentUsageUnits, required)
• agents[].lastAt (number | null, required)
• coverage (string, optional)
• seriesBucket (string, optional): Present with series: UTC day or ISO week (Monday 00:00 UTC).
• series (object[], optional): Present with series=day|week: half-open buckets [start, end) that partition the period and add up to totals.
• series[].start (number, required): Unix epoch milliseconds.
• series[].end (number, required): Unix epoch milliseconds.
• series[].toolExecutions (integer, required) · minimum 0
• series[].sessionMinutes (integer, required) · minimum 0
• series[].metered (AgentUsageUnits, required)
• series[].included (AgentUsageUnits, required)
• previous (object | null, optional): Present with compare=previous: the period of the same length ending at since (clamped to retention), or null when it lies entirely outside retention.
• previous.since (number, optional): Unix epoch milliseconds.
• previous.until (number, optional): Unix epoch milliseconds.
• previous.clampedToRetention (boolean, optional)
• previous.totals (object, optional)
• change (object, optional): Present with compare=previous when a previous period exists: unit count differences.
• change.toolExecutions (integer, optional)
• change.sessionMinutes (integer, optional)

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

#Example

curl -sS -X GET 'https://app.trytelltale.dev/api/v1/agent-usage.json' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY"

const response = await fetch("https://app.trytelltale.dev/api/v1/agent-usage.json", {
  method: "GET",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY
  },
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.