API REFERENCE

Get account usage

On this page

GET/api/accounts/{id}/usage

List the charges that consumed an account's credits: one line item per deduction from usage_events, newest first, over a period. Each item carries the amount as the raw ledger integer (credits_deducted, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (usd), and the response carries the total for the whole period, not just the page. Access is the same as GET /api/accounts/{id}/credits: the authenticated account itself, or another account reachable through organization membership.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/usage' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

idpath · stringrequired

limitquery · integer

sortquery · string

cursorquery · string

fromquery · string

toquery · string

cURL for this request

curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/{id}/usage'

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Query parameters

limitinteger

Maximum number of line items to return per page.

Default: 20

sortstring · enum

Both orders are descending: created_at uses timestamp then row ID; cost uses credits_deducted then row ID. Cost ties are ordered by ID, not timestamp.

Values: "created_at", "cost"

Default: "created_at"

cursorstring

Opaque paging token: pass next_cursor unchanged with the same sort, from and to. New time cursors retain both the last timestamp and row ID, so tied timestamps are not skipped. Cost cursors retain amount and row ID. Legacy timestamp-only cursors remain accepted as strict time boundaries; start a fresh traversal to obtain complete tie coverage.

fromstring

Start of the period (inclusive), ISO 8601. Defaults to the start of the current UTC month.

tostring

End of the period (exclusive), ISO 8601. Defaults to now.

Responses

200Usage line items retrieved successfully

application/json

account_idstringrequired

The account whose charges are listed.

Example: "550e8400-e29b-41d4-a716-446655440000"

format: uuid

periodobjectrequired

The period the totals cover.

Properties

fromstringrequired

Example: "2026-08-01T00:00:00.000Z"

format: date-time

tostringrequired

Example: "2026-08-27T12:00:00.000Z"

format: date-time

total_credits_deductedintegerrequired

Sum of credits_deducted over every charge in the period, in micro-dollars. Covers the whole period, not only this page.

Example: 70000

total_usdstringrequired

total_credits_deducted formatted as US dollars.

Example: "$0.07"

eventsarray<AccountUsageEvent>required

Charges in the period in the requested sort order (newest first by default).

Item properties

idstringrequired

Identifier of the usage_events row.

Example: "3AANn3Ij9uF-zZIlW_zlP"

created_atstringrequired

When the charge was recorded, normalized to UTC at database microsecond precision.

Example: "2026-08-27T11:56:58.000000Z"

format: date-time

sourcestringrequirednullable

Which surface originated the charge: api for a request to the API, web for the chat app. Null when this field was not recorded.

Example: "api"

agent_typestringrequirednullable

main for a top-level request or any non-agent charge; subagent for a nested task step. Null when this field was not recorded.

Example: "main"

providerstringrequirednullable

Provider slug when the charge is a model or generation call (for example anthropic, fal). Null for research and other fixed-price endpoints.

Example: "fal"

model_idstringrequirednullable

The model for LLM-backed charges (a chat turn, a song generation), otherwise the API endpoint that was billed, as METHOD /route/pattern (for example POST /api/artist/socials/scrape). Null on rows written before 2026-08-27.

Example: "POST /api/artist/socials/scrape"

input_tokensintegerrequirednullable

Input tokens for the call, including cached. 0 for non-LLM charges. Null when this field was not recorded.

Example: 0

cached_input_tokensintegerrequirednullable

Subset of input_tokens served from the provider cache. Null when this field was not recorded.

Example: 0

output_tokensintegerrequirednullable

Output tokens for the call. 0 for non-LLM charges. Null when this field was not recorded.

Example: 0

tool_call_countintegerrequirednullable

Recorded tool count for this event. For the main agent workflow, this counts tool entries in the accumulated assistant reply, including pending and failed requests and entries retained when that reply resumes. Nested subagent entries are excluded. The value describes the reply snapshot, rather than successful executions or only new work after a resume. A writer can default an omitted count to zero, so zero alone does not establish that no tools were requested. Older events retain their previously recorded counts. Null when this field was not recorded.

Example: 0

credits_deductedintegerrequired

Amount charged, as the raw ledger integer in micro-dollars (1,000,000 = $1.00). Divide by 1,000,000 for dollars.

Example: 20000

usdstringrequired

credits_deducted formatted as US dollars with two decimals.

Example: "$0.02"

resource_urlstringrequirednullable

App-relative path of what produced the charge, when there is something to open: /chat?roomId=<roomId> for a chat turn, /music/<generationId> for a song, /tasks/<taskId>/runs/<runId> for a scheduled task run. Null for plain API calls and for rows written before the field existed.

Example: "/music/0c35429f-deb8-48f0-b0f2-fd5145de2583"

next_cursorstringrequirednullable

Opaque; pass unchanged as cursor with the same sort, from and to. A full page may return a cursor followed by an empty final page; null means this traversal has ended. Time cursors retain timestamp and ID; cost cursors retain amount and ID.

Example: "v1:WyIyMDI2LTA4LTI3VDExOjU2OjU4LjAwMDAwMFoiLCIzQUFObjNJajl1Ri16WklsV196bFAiXQ"

series_bucketstring · enum

Granularity of series, derived from the span of the period: hour up to 2 days, day up to 90 days, week up to 12 months, month beyond. Present only on a first page (no cursor).

Values: "hour", "day", "week", "month"

Example: "day"

seriesarray<object>

Spend over the period, one entry per series_bucket that had at least one charge, ascending by start, in UTC. The sum of credits_deducted across the entries equals total_credits_deducted. Present only on a first page (no cursor); omitted on cursor pages so paging never recomputes it.

Example: [{"start":"2026-08-11T00:00:00.000Z","credits_deducted":56080000,"usd":"$56.08","events":727},{"start":"2026-08-12T00:00:00.000Z","credits_deducted":221090000,"usd":"$221.09","events":2462},{"start":"2026-08-13T00:00:00.000Z","credits_deducted":440930000,"usd":"$440.93","events":5479}]

Item properties

startstringrequired

Start of the bucket, UTC.

Example: "2026-08-12T00:00:00.000Z"

format: date-time

credits_deductedintegerrequired

Charges in the bucket, in micro-dollars.

Example: 221090000

usdstringrequired

credits_deducted formatted as US dollars.

Example: "$221.09"

eventsintegerrequired

Number of charges in the bucket.

Example: 2462

400Bad request: invalid query parameter, limit above 100, malformed cursor, or a non-positive period after database timestamp normalization.

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

400 example

{
  "error": "limit must be between 1 and 100"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

401 example

{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "operationId": "getAccountsByIdUsage",
  "description": "List the charges that consumed an account's credits: one line item per deduction from `usage_events`, newest first, over a period. Each item carries the amount as the raw ledger integer (`credits_deducted`, micro-dollars: 1,000,000 = $1.00) and the same amount formatted as a dollar string (`usd`), and the response carries the total for the whole period, not just the page. Access is the same as [`GET /api/accounts/{id}/credits`](/api-reference/accounts/credits-get): the authenticated account itself, or another account reachable through organization membership.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Maximum number of line items to return per page.",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      }
    },
    {
      "name": "sort",
      "in": "query",
      "required": false,
      "description": "Both orders are descending: created_at uses timestamp then row ID; cost uses credits_deducted then row ID. Cost ties are ordered by ID, not timestamp.",
      "schema": {
        "type": "string",
        "enum": [
          "created_at",
          "cost"
        ],
        "default": "created_at"
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "Opaque paging token: pass next_cursor unchanged with the same sort, from and to. New time cursors retain both the last timestamp and row ID, so tied timestamps are not skipped. Cost cursors retain amount and row ID. Legacy timestamp-only cursors remain accepted as strict time boundaries; start a fresh traversal to obtain complete tie coverage.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "from",
      "in": "query",
      "required": false,
      "description": "Start of the period (inclusive), ISO 8601. Defaults to the start of the current UTC month.",
      "schema": {
        "type": "string",
        "format": "date-time"
      }
    },
    {
      "name": "to",
      "in": "query",
      "required": false,
      "description": "End of the period (exclusive), ISO 8601. Defaults to now.",
      "schema": {
        "type": "string",
        "format": "date-time"
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Usage line items retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountUsageResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request: invalid query parameter, limit above 100, malformed cursor, or a non-positive period after database timestamp normalization.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsErrorResponse"
          },
          "example": {
            "error": "limit must be between 1 and 100"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - account not accessible to the authenticated account",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountCreditsErrorResponse"
          }
        }
      }
    }
  }
}

Get started with Recoup.

Try Our Platform

Build Your Platform

Get account usage

Authentication

Request

Try it

Parameters

Path parameters

Query parameters

Responses

Full specification