Billing Public API

Use the Billing Public API to read Atlas Cloud billing data from scripts, dashboards, and finance systems.

Base URL: https://api.atlascloud.ai/public/v1

Endpoints

Endpoint	Description
`GET /balance`	Current account balance and credit grant summary
`GET /model-usage`	Daily model usage buckets
`GET /model-costs`	Daily model cost buckets

Detailed request and response schemas are available in the API reference:

Authentication

Send an Atlas Cloud API key in the Authorization header:

Authorization: Bearer apikey-...

Create API keys from API Keys. The secret key starts with apikey-.

Some responses and filters use an API key public ID such as ak_.... This public ID is safe to display in billing reports, but it is not a credential and cannot authenticate requests.

Permissions

/model-usage and /model-costs default to scope=self, which returns usage attributed to the authenticated user, including API keys they own.

Use scope=account to query account-wide usage and costs. Account scope requires account-level model billing read permission. /balance always uses account scope and requires account balance read permission.

Personal account owners can read their own account billing data. In team accounts, use an Account Admin or Finance role.

Query Balance

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

Money values are returned as fixed six-decimal strings with a currency:

{
  "value": "125.500000",
  "currency": "usd"
}

Usage and Cost Query Parameters

start_date and end_date are required UTC dates in YYYY-MM-DD format. end_date is exclusive, and the range can cover at most 180 days.

Common query parameters for /model-usage and /model-costs. Omitting group_by[] returns total daily buckets:

Parameter	Description
`start_date`	Inclusive UTC start date in `YYYY-MM-DD` format
`end_date`	Exclusive UTC end date in `YYYY-MM-DD` format; range can cover at most 180 days
`scope`	`self` or `account`; defaults to `self`
`group_by[]`	Optional grouping. Supported sets: `model_type`, `model`, `api_key`, or `model` plus `api_key`; use `group_by[]=model` for model breakdown
`model_types[]`	Repeat with `text`, `image`, or `video`
`model_ids[]`	Filter by model IDs; up to 100 values
`api_key_ids[]`	Filter by `ak_...` API key public IDs; up to 100 values
`limit`	Rows per page, 1 to 1000; defaults to 100
`page`	Opaque pagination cursor from `next_page`

Use repeated array parameters. Comma-delimited values are rejected.

Query Usage

The default response returns total daily usage buckets.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

Query Costs

/model-costs accepts the same date range, scope, filters, grouping, and pagination parameters as /model-usage. Omitting group_by[] returns total daily cost buckets.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

Pagination

When has_more is true, pass next_page back as the page query parameter. Treat the cursor as opaque and keep all other query parameters unchanged.

Errors and Rate Limits

Errors use a stable envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

Rate-limited responses return 429 rate_limit_error and may include a Retry-After header.

On This Page