Get a usage summary

curl --request GET \
  --url https://api.crustdata.com/account/usage/summary \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/account/usage/summary"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/account/usage/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "buckets": [
    {
      "requests": 423,
      "credits": 1590.79,
      "errors": 37,
      "results": 9599
    }
  ]
}

Usage summary

Adds up your team’s API usage over a time window: requests, credits, errors and results. Pass group_by to split the totals by day, product, endpoint, charge component, API key, client surface, client platform or status class. Leave it out to get one total row.

Every row is scoped to your team. No parameter reads another team’s usage.

With the default bucket=1d and a window made of whole UTC days, the summary is read from daily totals. Those know the day, product, endpoint, API key, client surface and status class, so some shapes are rejected with a 400 that tells you to retry with bucket=1h:

group_by=component combines only with day and product, and filters only by products.
The status and error_type filters need bucket=1h.

A window that starts or ends mid-day, bucket=1h, or any grouping that includes client_platform accepts every combination.

This endpoint is free: the response carries no X-Credits-Used header. It shares a limit of 60 requests per minute with the other /account/usage/* endpoints.

GET

https://api.crustdata.com

account

usage

summary

Get a usage summary

curl --request GET \
  --url https://api.crustdata.com/account/usage/summary \
  --header 'Authorization: Bearer <token>' \
  --header 'x-api-version: <x-api-version>'

import requests

url = "https://api.crustdata.com/account/usage/summary"

headers = {
    "x-api-version": "<x-api-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-api-version': '<x-api-version>', Authorization: 'Bearer <token>'}
};

fetch('https://api.crustdata.com/account/usage/summary', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "buckets": [
    {
      "requests": 423,
      "credits": 1590.79,
      "errors": 37,
      "results": 9599
    }
  ]
}

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

API version to use. This endpoint currently requires 2025-11-01. Requests without the header, or with any other value, return 400.

Available options:

2025-11-01

Example:

"2025-11-01"

Query Parameters

group_by

enum<string>[]

Dimensions to split the totals by. Repeat the parameter or send a comma-separated list, for example group_by=day,component. A dimension can appear once. Omit it for a single total row.

Grouping by day returns the time column as bucket_start. Grouping by component returns component and label, and swaps errors and results for quantity.

client_platform is the tool or runtime that made the call, such as claude-code, python or curl. New values can appear at any time, so do not hard-code the list. It works with any bucket.

Available options:

day,

product,

endpoint,

component,

api_key_id,

client_surface,

client_platform,

status_class

bucket

enum<string>

default:1d

Size of each time bucket when you group by day. 1d returns a date in bucket_start, 1h an ISO 8601 timestamp.

Available options:

1d,

1h

start

string

Start of the window, inclusive. An ISO 8601 timestamp such as 2026-09-23T14:00:00Z, or a date such as 2026-09-21, which reads as midnight UTC. Defaults to 7 days before end. Cannot be more than 12 months ago.

end

string

End of the window, exclusive. Same formats as start. Defaults to the coming midnight UTC, so the default window is the last 7 whole days including today.

api_key_ids

integer[]

Keep only requests made with these API key ids (api_key_id on an event). Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

Required range: x >= 1

endpoints

string[]

Keep only these endpoints, as they appear in endpoint, for example /person/search. Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

products

string[]

Keep only these products, as they appear in product, for example person_search. Repeat the parameter or send a comma-separated list, up to 50.

Maximum array length: 50

status

integer[]

Keep only these HTTP status codes, for example status=400,404. Up to 20. On GET /account/usage/summary it needs bucket=1h, or a window that is not whole days.

Maximum array length: 20

Required range: 100 <= x <= 599

status_class

enum<string>

Keep only one status class.

Available options:

2xx,

3xx,

4xx,

5xx

client_surface

string[]

Keep only requests from these surfaces, as they appear in client_surface, for example api or mcp. Repeat the parameter or send a comma-separated list, up to 10.

Maximum array length: 10

error_type

string

Keep only requests that failed with this error_type, for example invalid_request. On GET /account/usage/summary it needs bucket=1h, or a window that is not whole days.

Response

One row per combination of the grouped dimensions. Rows are sorted by bucket_start when you group by day, then by credits, highest first.

Usage totals, one row per combination of the grouped dimensions.

buckets

object[]

required

The rows. A single row when group_by is omitted.

Show child attributes

Example:

[
  {
    "requests": 423,
    "credits": 1590.79,
    "errors": 37,
    "results": 9599
  }
]