Yapper API
Api reference
GET
/usage/breakdown

Credit spend over time by model and by source, net of refunds, with runs and gross spent/refunded totals. Matches the Credit Spend card on the account usage page. week, month, and quarter return one bucket per UTC day (the last 7, 30, or 90 days including today); year returns the last 12 calendar months and all returns every month since the first with spend. Omit memberIds for the whole workspace. Summing other members' spend requires the key's member to be a team owner or admin; your own user id is always allowed. source limits the figures to one source and splits it by model when modelsAvailable is true. sessionId limits them to one session (any key may read a session's total); it cannot be combined with memberIds. Returns usage_breakdown_unavailable (409) until the workspace's usage history has been indexed.

Authorization

bearerAuth usage:read
AuthorizationBearer <token>

In: header

Scope: usage:read

Query Parameters

range?string
Default"month"

Value in

  • "week"
  • "month"
  • "quarter"
  • "year"
  • "all"
memberIds?string

Comma-separated user ids (up to 30) whose spend to sum. Former members' history remains readable.

source?string

Only this source's spend.

Value in

  • "web"
  • "ios"
  • "agent"
  • "agent-chat"
  • "api"
  • "mcp"
sessionId?string

Only this session's spend, bucketed from its newest 5,000 credit log entries in the range (truncated reports when there were more).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/usage/breakdown"
{  "range": "week",  "granularity": "day",  "start": "string",  "end": "string",  "memberIds": [    "string"  ],  "source": "web",  "sessionId": "string",  "modelsAvailable": true,  "truncated": true,  "totals": {    "credits": 0,    "creditsSpent": 0,    "creditsRefunded": 0,    "runs": 0,    "refunds": 0  },  "buckets": [    {      "date": "string",      "credits": 0,      "byModel": {        "property1": 0,        "property2": 0      },      "bySource": {        "property1": 0,        "property2": 0      }    }  ],  "models": [    {      "id": "string",      "label": "string",      "credits": 0,      "runs": 0    }  ],  "sources": [    {      "source": "web",      "credits": 0,      "runs": 0    }  ]}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}
{  "error": {    "code": "string",    "message": "string",    "requestId": "string"  }}

Get usage state GET

Returns team credits plus member-limit state for the acting user bound to the API key. Credits are wallet-aware, like GET /credits: teams paying from a linked external wallet report its spendable balance in credit equivalents.

Get billing cycle credits GET

This billing cycle's credits and the next plan refill. Matches the Workspace Credits card on the account usage page. The period is the plan's monthly renewal window (yearly plans are divided into monthly windows), or the UTC calendar month for a workspace without an active plan. credits.available is the workspace's Yapper credit balance; GET /usage reports a linked external wallet.