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.

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

Order of the line items, both descending: created_at (newest first, the default) or cost (largest credits_deducted first, ties by newest).

Values: "created_at", "cost"

Default: "created_at"

cursorstring

Opaque paging token: pass the next_cursor value from the previous page, with the same sort, from and to. With sort=created_at it is the last item's created_at; with sort=cost it encodes the last item's amount and id. Returns the items that follow it.

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.

format: uuid

periodobjectrequired

The period the totals cover.

Properties

fromstringrequired

format: date-time

tostringrequired

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.

total_usdstringrequired

total_credits_deducted formatted as US dollars.

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.

created_atstringrequired

When the charge was recorded.

format: date-time

sourcestringrequired

Which surface originated the charge: api for a request to the API, web for the chat app.

agent_typestringrequired

main for a top-level request or any non-agent charge; subagent for a nested task step.

providerstringrequirednullable

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

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.

input_tokensintegerrequired

Input tokens for the call, including cached. 0 for non-LLM charges.

cached_input_tokensintegerrequired

Subset of input_tokens served from the provider cache.

output_tokensintegerrequired

Output tokens for the call. 0 for non-LLM charges.

tool_call_countintegerrequired

Number of tool calls in this step.

credits_deductedintegerrequired

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

usdstringrequired

credits_deducted formatted as US dollars with two decimals.

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.

next_cursorstringrequirednullable

Opaque; pass as cursor (with the same sort, from and to) to fetch the next page. Null when the page was the last one in the period.

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"

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.

Item properties

startstringrequired

Start of the bucket, UTC.

format: date-time

credits_deductedintegerrequired

Charges in the bucket, in micro-dollars.

usdstringrequired

credits_deducted formatted as US dollars.

eventsintegerrequired

Number of charges in the bucket.

400Bad request - invalid query parameter (for example limit above 100 or a cursor that is not a timestamp)

application/json

errorstringrequired

Human-readable error message.

400 example

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

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example

{
  "error": "Unauthorized"
}

403Forbidden - account not accessible to the authenticated account

application/json

errorstringrequired

Human-readable error message.

Full specification

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

Download accounts.json

View operation source

json

{
  "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": "Order of the line items, both descending: `created_at` (newest first, the default) or `cost` (largest `credits_deducted` first, ties by newest).",
      "schema": {
        "type": "string",
        "enum": [
          "created_at",
          "cost"
        ],
        "default": "created_at"
      }
    },
    {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "Opaque paging token: pass the `next_cursor` value from the previous page, with the same `sort`, `from` and `to`. With `sort=created_at` it is the last item's `created_at`; with `sort=cost` it encodes the last item's amount and id. Returns the items that follow it.",
      "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 (for example `limit` above 100 or a `cursor` that is not a timestamp)",
      "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"
          }
        }
      }
    }
  }
}