GET/api/v1/usage

Page through settled requests with cost and attribution

Keyset-paginated feed of settled requests, newest first, for rebilling end customers. Filter by attribution_label (the safety_identifier/user you sent) for one end customer. While a full page returns, echo next_cursor's three fields back as cursor_ts, cursor_id, cursor_after.

Authentication: Bearer API key in the Authorization header

Query parameters

  • windowenum

    Lookback window. Default 7d.

    "24h""7d""30d"
    Default: "7d"
  • modelstring

    Only requests to this model slug.

  • api_key_idstring

    Only requests made with this key id (uuid).

  • statusenum

    Terminal status, or error for every status other than completed.

    "completed""failed""cancelled""incomplete""expired_before_dispatch""unknown_after_crash""error"
  • attribution_labelstring

    Only requests carrying this end-customer label.

  • cursor_tsstring

    From next_cursor.cursor_ts. Pass with cursor_id.

  • cursor_idstring

    From next_cursor.cursor_id. Pass with cursor_ts.

  • cursor_afterstring

    From next_cursor.cursor_after; freezes the window's lower bound across pages.

  • limitinteger

    Page size, 1 to 200.

    Default: 50

Responses

  • 200

    One page of settled requests.

    Response
    • dataarray<object>required
      data
      • idstring

        Request id.

      • created_atstring
      • modelstring
      • providerstring | null
      • attribution_labelstring | null

        The safety_identifier or user you sent; null when neither.

      • real_cost_usdnumber

        Charged credits plus attributed own-key estimate, USD. 0 with pricing_known false means unpriced, not free.

      • cost_usdnumber

        Charged, USD.

      • estimated_cost_usdnumber

        Own-key list estimate, USD.

      • pricing_knownboolean
      • input_tokensinteger
      • output_tokensinteger
      • cached_input_tokensinteger
      • reasoning_tokensinteger
      • statusenum
        "completed""failed""cancelled""incomplete""expired_before_dispatch""unknown_after_crash"
      • api_key_idstring | null
    • next_cursorobject | nullrequired

      Present while a full page came back; null on the last page.

      One of

      object

      • cursor_tsstringrequired
      • cursor_idstringrequired
      • cursor_afterstringrequired
  • 400

    Unknown window or status, malformed key id, or a half-supplied cursor.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 401

    Missing, unknown or revoked API key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    The resource does not exist or belongs to another organization.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 422

    limit outside 1 to 200.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

Request

curl https://api.experientiallabs.ai/api/v1/usage?window=30d&model=claude-opus-5.5&api_key_id=0b9d4f6e-2a1c-4e8b-9f37-5c6d2e1a8b40&status=completed&attribution_label=customer-4821&cursor_ts=2026-11-18T21%3A04%3A11.392Z&cursor_id=req_3a9e1f0c7b2d4c58a6e1d9f4b0c2a817&cursor_after=2026-10-20T21%3A04%3A00%2B00%3A00&limit=100 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "req_3a9e1f0c7b2d4c58a6e1d9f4b0c2a817",
      "created_at": "2026-11-18T21:04:11.392Z",
      "model": "claude-opus-5.5",
      "provider": "anthropic",
      "attribution_label": "customer-4821",
      "real_cost_usd": 0.004215,
      "cost_usd": 0.004215,
      "estimated_cost_usd": 0,
      "pricing_known": true,
      "input_tokens": 1840,
      "output_tokens": 402,
      "cached_input_tokens": 1024,
      "reasoning_tokens": 0,
      "status": "completed",
      "api_key_id": "0b9d4f6e-2a1c-4e8b-9f37-5c6d2e1a8b40"
    }
  ],
  "next_cursor": {
    "cursor_ts": "2026-11-18T21:04:11.392Z",
    "cursor_id": "req_3a9e1f0c7b2d4c58a6e1d9f4b0c2a817",
    "cursor_after": "2026-10-20T21:04:00+00:00"
  }
}

https://api.experientiallabs.ai/api/v1/usage?window=30d&model=claude-opus-5.5&api_key_id=0b9d4f6e-2a1c-4e8b-9f37-5c6d2e1a8b40&status=completed&attribution_label=customer-4821&cursor_ts=2026-11-18T21%3A04%3A11.392Z&cursor_id=req_3a9e1f0c7b2d4c58a6e1d9f4b0c2a817&cursor_after=2026-10-20T21%3A04%3A00%2B00%3A00&limit=100