Menu docs

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.

KeyBerlaku diDi tempat lain
Management key cai_mgmt_<secret>Hanya /v1/organization/*401 di endpoint model
API key cai_<secret>Endpoint model401 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

MethodPathIsi
GET/v1/organization/balanceSaldo PAYG, grant promo, dan paket budget
GET/v1/organization/usagePemakaian per hari, project, key, dan model
GET/v1/organization/requestsMetadata request 90 hari terakhir, tanpa isi
GET/v1/organization/projectsProject 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:

EndpointArti as_of
/balance, /requests, /projectsWaktu data dibaca
/usageWaktu 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
FieldArti
payg_usdSaldo 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_usdTotal yang dikreditkan ke tier itu
packs[].official_value_up_to_usdNilai sisa paket pada harga resmi, hanya untuk tampilan; bukan saldo. null bila tidak ada model di tier itu yang punya tarif resmi
packs_totalJumlah semua paket; nol bila Anda tidak punya paket
available_for_model_usdHanya 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.

QueryTipeCatatan
from, toTanggal ISO, UTCWajib; maksimal 366 hari
project, key, modelstring, boleh berulangFilter
granularitydayHanya day
limitintDefault 100, maksimal 1.000
cursorstringDari 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.

QueryCatatan
from, toTanggal ISO, UTC; dalam 90 hari terakhir
project, key, modelFilter
statusok, partial, atau error
limit, cursorDefault 100, maksimal 1.000
Filter statusBaris yang dikembalikan
okStatus HTTP di bawah 400 dan request selesai
partialStatus HTTP di bawah 400, tetapi request tidak selesai: client memutus koneksi, stream terputus, atau mencapai durasi maksimum
errorStatus 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.

StatusKodeKapan
400invalid_requestParameter query salah, misalnya rentang lebih dari 366 hari
401invalid_api_keyKey salah, sudah dicabut, atau berupa API key, bukan management key
429rate_limitedLebih 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

  • modelstringopsional

    Public 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

  • fromstringwajib

  • tostringwajib

    At most 366 days after from.

  • projectstring[]opsional

  • keystring[]opsional

  • modelstring[]opsional

  • granularitystringopsional

  • limitintegeropsional

  • cursorstringopsional

    Opaque 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

  • fromstringopsional

  • tostringopsional

  • projectstringopsional

  • keystringopsional

  • modelstringopsional

  • statusstringopsional

  • limitintegeropsional

  • cursorstringopsional

    Opaque 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.