Billing Public API

Billing Public API digunakan untuk membaca data billing Atlas Cloud dari script, dashboard, dan sistem keuangan.

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

Endpoint

Endpoint	Deskripsi
`GET /balance`	Saldo akun saat ini dan ringkasan credit grant
`GET /model-usage`	Bucket penggunaan model harian
`GET /model-costs`	Bucket biaya model harian

Schema lengkap tersedia di API reference:

Authentication

Kirim Atlas Cloud API Key di header Authorization:

Authorization: Bearer apikey-...

Buat API Key dari API Keys. Secret key diawali dengan apikey-.

Beberapa response dan filter menggunakan API Key public ID seperti ak_.... ID ini aman untuk ditampilkan di laporan billing, tetapi bukan credential.

Permissions

/model-usage dan /model-costs memakai scope=self secara default dan mengembalikan penggunaan yang dikaitkan dengan user terautentikasi, termasuk API Key yang dimilikinya.

Gunakan scope=account untuk query penggunaan dan biaya seluruh akun. Scope ini memerlukan account-level model billing read permission. /balance selalu memakai account scope dan memerlukan account balance read permission.

Owner personal account dapat membaca data billing akunnya sendiri. Untuk team account, gunakan role Account Admin atau Finance.

Query Balance

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

Nilai uang dikembalikan sebagai string enam desimal dengan currency:

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

Usage and Cost Query Parameters

start_date dan end_date wajib diisi sebagai tanggal UTC dengan format YYYY-MM-DD. end_date bersifat exclusive, dan rentang maksimal adalah 180 hari.

Parameter umum untuk /model-usage dan /model-costs. Jika group_by[] tidak dikirim, respons berisi total harian:

Parameter	Deskripsi
`start_date`	Tanggal mulai UTC inklusif dalam format `YYYY-MM-DD`
`end_date`	Tanggal akhir UTC eksklusif dalam format `YYYY-MM-DD`; rentang maksimal 180 hari
`scope`	`self` atau `account`; default `self`
`group_by[]`	Pengelompokan opsional. Set yang didukung: `model_type`, `model`, `api_key`, atau `model` plus `api_key`; gunakan `group_by[]=model` untuk rincian per model
`model_types[]`	Ulangi dengan `text`, `image`, atau `video`
`model_ids[]`	Filter berdasarkan model ID; maksimal 100 nilai
`api_key_ids[]`	Filter berdasarkan public ID `ak_...`; maksimal 100 nilai
`limit`	Baris per halaman, 1 sampai 1000; default 100
`page`	Cursor opaque dari `next_page`

Gunakan parameter berulang untuk array. Nilai yang dipisahkan koma akan ditolak.

Query Usage

Respons default mengembalikan total penggunaan harian.

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 memakai rentang tanggal, scope, filter, pengelompokan, dan parameter paginasi yang sama seperti /model-usage. Jika group_by[] tidak dikirim, respons berisi total biaya harian.

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

Saat has_more bernilai true, kirim next_page apa adanya sebagai parameter query page. Cursor bersifat opaque; jangan decode, dan jangan ubah parameter query lainnya.

Errors and Rate Limits

Error memakai envelope stabil:

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

Response yang terkena rate limit mengembalikan 429 rate_limit_error dan dapat menyertakan header Retry-After.

On this page