Docs / API
Usage API
Baca saldo, pemakaian harian, request, dan project dengan management key lewat /v1/organization/*.
Terakhir diperbarui
Management key
Usage API membaca data akun Anda dari server Anda sendiri. API ini memakai management key, bukan API key.
Management key berbentuk cai_mgmt_<secret>. Buat di Pengaturan di dashboard. Key hanya tampil sekali; Cent AI hanya menyimpan hash-nya. Anda bisa mencabutnya di tempat yang sama, dan pencabutan berlaku dalam hitungan detik.
| Key | Berlaku di | Di tempat lain |
|---|---|---|
Management key cai_mgmt_<secret> | Hanya /v1/organization/* | 401 di endpoint model |
API key cai_<secret> | Endpoint model | 401 di /v1/organization/* |
Kirim management key sebagai token Bearer:
GET https://api.cent-ai.dev/v1/organization/balance
Authorization: Bearer cai_mgmt_<secret>
Usage API hanya membaca. Management key tidak bisa memanggil model, membuat key, atau mengubah budget.
Endpoint
| Method | Path | Isi |
|---|---|---|
| GET | /v1/organization/balance | Saldo PAYG, grant promo, dan paket budget |
| GET | /v1/organization/usage | Pemakaian per hari, project, key, dan model |
| GET | /v1/organization/requests | Metadata request 90 hari terakhir, tanpa isi |
| GET | /v1/organization/projects | Project beserta budget dan pengeluarannya |
Path-nya mengikuti pola OpenAI Admin API. Bentuk responsnya milik Cent AI sendiri dan dijelaskan di halaman ini.
Jumlah uang berupa string desimal dengan 9 digit pecahan. Waktu memakai RFC 3339 dalam UTC.
Kesegaran data: as_of
Setiap respons punya field as_of di tingkat atas:
| Endpoint | Arti as_of |
|---|---|
/balance, /requests, /projects | Waktu data dibaca |
/usage | Waktu sampai mana total harian sudah lengkap; null sebelum total pertama siap |
Total pemakaian disusun di latar belakang, jadi request terbaru bisa muncul di /requests sebelum muncul di /usage. Angkanya sama dengan dashboard pada waktu yang sama.
Saldo
GET /v1/organization/balance
GET /v1/organization/balance?model=glm-5.3
| Field | Arti |
|---|---|
payg_usd | Saldo pay-as-you-go. Bisa negatif setelah request yang biayanya melebihi saldo |
promo[] | Grant promo yang belum kedaluwarsa, dengan expires_at |
packs[] | Satu entri per tier paket budget yang Anda miliki. Paket tidak kedaluwarsa |
packs[].credited_usd | Total yang dikreditkan ke tier itu |
packs[].official_value_up_to_usd | Nilai sisa paket pada harga resmi, hanya untuk tampilan; bukan saldo. null bila tidak ada model di tier itu yang punya tarif resmi |
packs_total | Jumlah semua paket; nol bila Anda tidak punya paket |
available_for_model_usd | Hanya dengan ?model=: promo yang mencakup model itu, ditambah paket yang tier-nya memuat model itu, ditambah PAYG |
Pemakaian
Total harian per project, key, dan model.
| Query | Tipe | Catatan |
|---|---|---|
from, to | Tanggal ISO, UTC | Wajib; maksimal 366 hari |
project, key, model | string, boleh berulang | Filter |
granularity | day | Hanya day |
limit | int | Default 100, maksimal 1.000 |
cursor | string | Dari next_cursor halaman sebelumnya |
curl "https://api.cent-ai.dev/v1/organization/usage?from=2026-10-01&to=2026-10-31&model=glm-5.3" \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
Jumlah semua baris sama dengan ekspor CSV halaman Usage di dashboard untuk filter yang sama.
Request
Satu baris per request: hanya metadata, tidak pernah berisi prompt atau respons.
| Query | Catatan |
|---|---|
from, to | Tanggal ISO, UTC; dalam 90 hari terakhir |
project, key, model | Filter |
status | ok, partial, atau error |
limit, cursor | Default 100, maksimal 1.000 |
Filter status | Baris yang dikembalikan |
|---|---|
ok | Status HTTP di bawah 400 dan request selesai |
partial | Status HTTP di bawah 400, tetapi request tidak selesai: client memutus koneksi, stream terputus, atau mencapai durasi maksimum |
error | Status HTTP 400 atau lebih |
curl "https://api.cent-ai.dev/v1/organization/requests?status=error&limit=50" \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
Di dalam baris, status adalah status HTTP request itu. request_id sama dengan header respons x-request-id dan ID di halaman Requests. estimated: true berarti jumlah token adalah perkiraan karena model tidak melaporkan usage.
Untuk membaca semua halaman, ulangi panggilan dengan cursor berisi next_cursor sampai has_more bernilai false.
Project
curl https://api.cent-ai.dev/v1/organization/projects \
-H "Authorization: Bearer $CENT_AI_MGMT_KEY"
Budget null berarti tanpa budget. Lihat Project dan budget.
Batas dan error
Setiap management key bisa mengirim 60 request per menit.
| Status | Kode | Kapan |
|---|---|---|
| 400 | invalid_request | Parameter query salah, misalnya rentang lebih dari 366 hari |
| 401 | invalid_api_key | Key salah, sudah dicabut, atau berupa API key, bukan management key |
| 429 | rate_limited | Lebih dari 60 request per menit; tunggu sesuai Retry-After |
Panggil dari server Anda
/v1/organization/* tidak mengirim header CORS, jadi browser memblokir panggilan dari halaman web. Panggil dari server Anda dan simpan management key di sana.
Kontrak
GET/v1/organization/balance
Balance
Autentikasi · Management key
Parameter query
modelstringopsionalPublic model name; adds available_for_model_usd.
Respons
- 200Balance by source.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
Retry-Afterx-request-id
GET/v1/organization/usage
Daily usage
Autentikasi · Management key
Parameter query
fromstringwajibtostringwajibAt most 366 days after from.
projectstring[]opsionalkeystring[]opsionalmodelstring[]opsionalgranularitystringopsionallimitintegeropsionalcursorstringopsionalOpaque cursor from next_cursor.
Respons
- 200Rows per day, project, key and model.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
Retry-Afterx-request-id
GET/v1/organization/requests
Requests of the last 90 days
Autentikasi · Management key
Parameter query
fromstringopsionaltostringopsionalprojectstringopsionalkeystringopsionalmodelstringopsionalstatusstringopsionallimitintegeropsionalcursorstringopsionalOpaque cursor from next_cursor.
Respons
- 200Request metadata without content.
- 400Error in the OpenAI shape.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
Retry-Afterx-request-id
GET/v1/organization/projects
Projects with budgets and spend
Autentikasi · Management key
Respons
- 200Projects.
- 401Error in the OpenAI shape.
- 429Error in the OpenAI shape that may be retried after Retry-After.ulangi
Header respons
Retry-Afterx-request-id
Dibuat dari kontrak OpenAPI.