Public API

List model usage

Returns UTC daily model usage buckets for the authenticated API key's visible scope. Omitting `group_by[]` returns total daily buckets.

GET
/public/v1/model-usage

Authorization

AuthorizationBearer <token>

Use an Atlas Cloud API key in the form Authorization: Bearer apikey-....

In: header

Query Parameters

start_datestring

Inclusive UTC start date in YYYY-MM-DD format.

Formatdate
end_datestring

Exclusive UTC end date in YYYY-MM-DD format. The range can cover at most 180 daily buckets.

Formatdate
scope?string

Visibility scope. self reads usage from the authenticated user's API keys. account requires account-level billing read permission.

Default"self"
Value in"self" | "account"
group_by[]?array<string>

Repeated grouping parameter. Omit to return total daily buckets. Supported sets are model_type, model, api_key, and model plus api_key. Comma-delimited values are not accepted.

Itemsitems <= 3
model_types[]?array<string>

Repeated model type filter. Omit to include text, image, and video.

Itemsitems <= 3
model_ids[]?array<string>

Repeated model ID filter. At most 100 IDs.

Itemsitems <= 100
api_key_ids[]?array<string>

Repeated API key public ID filter. Use ak_... IDs returned by API key management, not the secret apikey-... token.

Itemsitems <= 100
limit?integer

Maximum number of grouped rows to return.

Default100
Range1 <= value <= 1000
page?string

Opaque cursor from the previous response's next_page. Pass it back unchanged.

Response Body

curl -X GET "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08&scope=self&group_by%5B%5D=model%2Capi_key&model_types%5B%5D=text%2Cimage&model_ids%5B%5D=deepseek-v3&api_key_ids%5B%5D=ak_abc123&limit=100&page=string"
{
  "object": "list",
  "scope": "self",
  "data": [
    {
      "object": "usage.bucket",
      "date": "2026-05-01",
      "start_at": "2026-05-01T00:00:00Z",
      "end_at": "2026-05-02T00:00:00Z",
      "covered_until": "2026-05-02T00:00:00Z",
      "partial": false,
      "results": [
        {
          "object": "usage.result",
          "usage": {
            "requests": 12,
            "invocations": 12,
            "tokens": {
              "input": 12000,
              "output": 3000,
              "total": 15000,
              "cache_creation": 0,
              "cache_creation_1h": 0,
              "cache_read": 0,
              "input_image": 0,
              "output_image": 0
            },
            "images": null,
            "video": null
          }
        }
      ]
    }
  ],
  "has_more": false,
  "next_page": null,
  "request_id": "req_123"
}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "string",
    "param": "string"
  },
  "request_id": "string"
}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "string",
    "param": "string"
  },
  "request_id": "string"
}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "string",
    "param": "string"
  },
  "request_id": "string"
}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "string",
    "param": "string"
  },
  "request_id": "string"
}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "string",
    "param": "string"
  },
  "request_id": "string"
}

Get account balance GET

Returns the current account balance and credit grant summary for the authenticated API key's account.

List model costs GET

Returns UTC daily model cost buckets for the authenticated API key's visible scope. Omitting `group_by[]` returns total daily buckets.