Langsung ke konten
Search documentation titles, headings, and guides
API v1Updated 2026-09-28

API Penggunaan & Saldo

Endpoint REST workspace untuk membaca saldo, riwayat penggunaan, transaksi, analitik, dan ekspor data Anda sendiri — via sesi browser atau API key zr_.

Endpoint-endpoint ini memberikan akses read-only ke data workspace Anda sendiri: saldo, riwayat penggunaan, transaksi, analitik, dan ekspor CSV/JSON. Di browser Anda memakainya dengan sesi dashboard; dari server atau script Anda kini bisa memakai API key zr_ yang sama dengan yang Anda pakai untuk API inference.

Autentikasi#

Setiap endpoint di bawah menerima salah satu kredensial, yang mana pun datang lebih dulu:

  • Cookie sesi — cookie httpOnly zrouter_session dari login Google. Beginilah dashboard memanggil API.
  • API key — key zr_ yang dibuat di dashboard bagian API Keys (ditampilkan sekali saat pembuatan). Kirim lewat header Authorization sebagai Bearer token atau lewat header X-Api-Key.

Akses via API key hanya berlaku untuk lima path read-only ini: GET /api/customer/balances, GET /api/customer/usage, GET /api/customer/transactions, GET /api/customer/analytics, dan GET /api/customer/exports/{kind}. Semua yang lain di bawah /api/customer/* — checkout, unduh receipt, manajemen sesi, dan manajemen API key — tetap membutuhkan sesi browser. Jika kedua header dikirim dan berisi key yang berbeda, request ditolak.

Panggil dengan API key (dua gaya header yang setara)
# Gaya 1: Authorization Bearer
curl -H "Authorization: Bearer zr_<public-id>_<secret>" \
  https://api.zrouter.dev/api/customer/balances

# Gaya 2: X-Api-Key
curl -H "X-Api-Key: zr_<public-id>_<secret>" \
  https://api.zrouter.dev/api/customer/balances

Jika sebuah request membawa cookie sesi yang valid, sesi menang dan API key diabaikan. Key yang diblokir mengembalikan 401 invalid_api_key yang sama dengan key yang salah, dicabut, atau kedaluwarsa — responsnya identik secara desain, sehingga tidak mungkin membedakan mode kegagalannya.

Batas laju#

Request yang diautentikasi dengan API key dibatasi 60 request per menit per key (nilai default; operator bisa mengubahnya lewat CUSTOMER_KEY_RATE_LIMIT_PER_MINUTE). Melebihi batas mengembalikan 429 rate_limited dengan header Retry-After: 60. Percobaan berulang dengan key yang tidak valid juga dithrottle per IP sumber. Panggilan dengan cookie sesi tidak dihitung terhadap limiter key.

Error#

HTTPcodeKapan
401invalid_sessionTidak ada atau cookie sesi tidak valid dan tidak ada API key.
401invalid_api_keyAPI key salah, dicabut, kedaluwarsa, atau diblokir — body identik di semua kasus.
429rate_limitedTerlalu banyak request. Coba lagi sebentar lagi. Lihat Retry-After.
503blacklist_unavailableKondisi sementara di sisi server. Coba lagi sebentar; jangan anggap key Anda tidak valid.

Lihat saldo#

GET/api/customer/balances
Auth: session-cookie or api-key

Mengembalikan saldo PAYG Anda (sebagai string desimal) dan ringkasan token tersisa untuk setiap Token Plan yang Anda miliki.

Responses

200Saldo untuk user yang terautentikasi.
{
  "payg": { "currency": "USD", "balance": "12.345678" },
  "token_plans": [
    {
      "model": "<public-name>",
      "purchased_tokens": 1000,
      "used_tokens": 320,
      "remaining_tokens": 680,
      "status": "active"
    }
  ],
  "as_of": "2026-09-16T00:00:00Z"
}
401Tidak ada kredensial valid (lihat Error).
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }
Baca saldo dengan API key
curl -H "Authorization: Bearer zr_<public-id>_<secret>" \
  https://api.zrouter.dev/api/customer/balances

Lihat penggunaan#

GET/api/customer/usage
Auth: session-cookie or api-key

Mengembalikan event penggunaan inference Anda, terbaru lebih dulu, dengan paginasi cursor dan retensi 90 hari.

Parameters

limitintegerqueryoptional

Ukuran halaman, 1-100. Default 50.

cursorstringqueryoptional

Cursor opak dari next_cursor / prev_cursor.

prevbooleanqueryoptional

Set true untuk halaman ke belakang. Butuh cursor.

fromstringqueryoptional

Batas bawah RFC3339, inklusif.

tostringqueryoptional

Batas atas RFC3339, inklusif.

modelstringqueryoptional

Filter berdasarkan nama publik model.

api_key_iduuidqueryoptional

Filter berdasarkan id API key (UUID). Hanya key milik Anda yang terlihat.

Responses

200Halaman penggunaan untuk user yang terautentikasi.
{
  "data": [
    {
      "id": "b8c1...",
      "request_id": "req_9f2e...",
      "model": "<public-name>",
      "input_tokens": 1204,
      "output_tokens": 356,
      "total_tokens": 1560,
      "display_cost_usd_micro": "0.000120",
      "funding_mode": "token_plan",
      "status": "success",
      "timestamp": "2026-09-16T04:12:33Z"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjUwfQ",
  "prev_cursor": null,
  "total": 1234,
  "retention_days": 90
}
400Parameter salah format atau di luar rentang.
{ "error": { "code": "invalid_request", "message": "limit must be between 1 and 100" } }
401Tidak ada kredensial valid (lihat Error).
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }

Setiap item juga membawa api_key_id, api_key_name, api_key_prefix, endpoint_kind, streamed, cache_read_input_tokens, plan_debit_tokens, payg_debit_usd_micro, funding, settlement_status, completed_at, dan settled_at bila tersedia.

Berpindah halaman penggunaan
curl -H "X-Api-Key: zr_<public-id>_<secret>" \
  "https://api.zrouter.dev/api/customer/usage?limit=100&cursor=eyJvZmZzZXQiOjB9"

Lihat transaksi#

GET/api/customer/transactions
Auth: session-cookie or api-key

Mengembalikan transaksi top-up dan pembelian Anda (order checkout), terbaru lebih dulu, dengan paginasi cursor.

Parameters

limitintegerqueryoptional

Ukuran halaman, 1-100. Default 50.

cursorstringqueryoptional

Cursor opak dari next_cursor / prev_cursor.

prevbooleanqueryoptional

Set true (atau 1) untuk halaman ke belakang. Butuh cursor.

Responses

200Halaman transaksi untuk user yang terautentikasi.
{
  "data": [
    {
      "id": "3f1c...",
      "type": "token_plan",
      "status": "credited",
      "amount_idr": 16000000,
      "usd_value_micro": 1000000,
      "fee_idr": 800000,
      "total_idr": 16800000,
      "granted_tokens": 1000,
      "created_at": "2026-09-12T08:30:00Z",
      "credited_at": "2026-09-12T08:31:02Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null,
  "total": 7
}
400Parameter salah format atau cursor tidak valid.
{ "error": { "code": "invalid_request", "message": "invalid cursor" } }
401Tidak ada kredensial valid (lihat Error).
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }

amount_idr, fee_idr, dan total_idr adalah integer IDR (IDR tidak punya unit minor). usd_value_micro adalah micro-USD. credited_at terisi setelah pembayaran dikreditkan; unduh receipt (GET /api/customer/transactions/{order_id}/receipt) tetap hanya lewat dashboard dan bukan bagian dari akses API key.

Lihat transaksi dengan API key
curl -H "Authorization: Bearer zr_<public-id>_<secret>" \
  "https://api.zrouter.dev/api/customer/transactions?limit=50"

Analitik penggunaan#

GET/api/customer/analytics
Auth: session-cookie or api-key

Mengembalikan analitik penggunaan teragregasi untuk satu rentang waktu (default: 30 hari terakhir), dirinci per hari, per model, dan per API key, plus perbandingan dengan periode sebelumnya yang sama panjangnya.

Parameters

fromstringqueryoptional

Batas bawah RFC3339. Default 30 hari lalu.

tostringqueryoptional

Batas atas RFC3339. Default sekarang. Harus setelah from.

modelstringqueryoptional

Filter berdasarkan nama publik model.

api_key_iduuidqueryoptional

Filter berdasarkan id API key (UUID). Hanya key milik Anda yang terlihat.

Responses

200Analitik untuk user yang terautentikasi.
{
  "summary": {
    "requests": 210,
    "tokens": 348000,
    "cost_usd_micro": 25400,
    "input_tokens": 300000,
    "output_tokens": 48000,
    "cache_read_tokens": 12000,
    "cached_input_share": 0.04,
    "blended_cost_usd_micro_per_million": 73000
  },
  "previous_summary": { ... },
  "daily": [
    { "date": "2026-09-16", "requests": 18, "tokens": 26000, "cost_usd_micro": 1900,
      "input_tokens": 22000, "output_tokens": 4000, "cache_read_tokens": 900 }
  ],
  "breakdown_by_model": [
    { "model": "<public-name>", "requests": 180, "input_tokens": 250000,
      "output_tokens": 45000, "cache_read_tokens": 11000, "cost_usd_micro": 22000 }
  ],
  "breakdown_by_key": [
    { "api_key_id": "d1e2...", "name": "prod-key", "requests": 200,
      "tokens": 340000, "cost_usd_micro": 24000 }
  ],
  "token_breakdown": { "input_tokens": 300000, "output_tokens": 48000, "cache_read_tokens": 12000 }
}
400Parameter salah format atau from tidak sebelum to.
{ "error": { "code": "invalid_range", "message": "from must be before to" } }
401Tidak ada kredensial valid (lihat Error).
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }
Ambil analitik dengan API key
curl -H "X-Api-Key: zr_<public-id>_<secret>" \
  "https://api.zrouter.dev/api/customer/analytics?from=2026-09-01T00:00:00Z&to=2026-09-28T00:00:00Z"

Ekspor data#

GET/api/customer/exports/{kind}
Auth: session-cookie or api-key

Unduh data Anda sebagai file lampiran. Respons membawa Content-Disposition: attachment.

Parameters

kindstringpathrequired

Salah satu dari usage, transactions, balances.

formatstringqueryrequired

Salah satu dari csv, json.

fromstringqueryoptional

Batas bawah RFC3339 (hanya usage dan transactions).

tostringqueryoptional

Batas atas RFC3339 (hanya usage dan transactions).

Responses

200Lampiran file (CSV atau JSON). Simpan dengan curl -o.
Content-Disposition: attachment; filename="usage-2026-09-28.csv"
400kind atau format tidak dikenal.
{ "error": { "code": "invalid_request", "message": "unsupported export kind" } }
401Tidak ada kredensial valid (lihat Error).
{ "error": { "code": "invalid_api_key", "message": "Invalid API key." } }
Ekspor penggunaan sebagai CSV dengan API key
curl -o usage.csv -H "Authorization: Bearer zr_<public-id>_<secret>" \
  "https://api.zrouter.dev/api/customer/exports/usage?format=csv"