Saldo akun

Baca saldo prabayar kamu, berapa bagian yang sedang ditahan oleh request yang masih berjalan, dan berapa yang bisa dipakai request baru. Panggil dari skrip atau agen sebelum memulai pekerjaan yang panjang. Endpoint ini khusus kenari dan tidak punya padanan di OpenAI maupun Anthropic.

GET /v1/account/balance

Request

Endpoint ini tidak menerima parameter query maupun body. Endpoint ini membutuhkan API key di header Authorization.

Header	Wajib	Keterangan
`Authorization`	ya	`Bearer kn-...`. Hanya key tanpa pembatasan dari akunmu sendiri yang bisa dipakai. API key dibagikan dan key yang dibatasi ditolak. Lihat Siapa yang bisa memanggil.

Response

Semua jumlah berupa integer dalam micro-Rupiah, yaitu Rp 1 sama dengan 1.000.000 micro-Rupiah. Lihat Cara penagihan.

Field	Tipe	Keterangan
`object`	string	Selalu `account.balance`.
`balance_micro_idr`	integer	Saldo kamu.
`reserved_micro_idr`	integer	Jumlah yang sedang ditahan oleh request yang masih berjalan.
`available_micro_idr`	integer	`balance_micro_idr` dikurangi `reserved_micro_idr`, tidak pernah di bawah 0. Inilah jumlah yang bisa ditahan oleh request baru.
`currency`	string	Selalu `IDR`.

Sebelum request berjalan, kenari menahan biaya kasus terburuknya. Saat request selesai, tahanan itu dilepas dan hanya biaya sebenarnya yang ditagih. Jadi reserved_micro_idr naik selama request berjalan dan kembali ke 0 setelah semuanya selesai. Pakai available_micro_idr untuk menentukan apakah request baru muat. balance_micro_idr bisa negatif kalau request yang sudah selesai ternyata lebih mahal dari tahanannya, sedangkan available_micro_idr tetap 0 dalam kondisi itu.

{
  "object": "account.balance",
  "balance_micro_idr": 25000000000,
  "reserved_micro_idr": 1500000,
  "available_micro_idr": 24998500000,
  "currency": "IDR"
}

Saldo ini Rp 25.000, dengan Rp 1,5 ditahan oleh satu request yang sedang berjalan.

Siapa yang bisa memanggil

Semua API key akunmu bisa memanggilnya, kecuali:

API key dibagikan mendapat 403 dan shared_key_not_allowed.
Key yang dibatasi mendapat 403 dan restricted_key_not_allowed. Key dibatasi kalau punya pembatasan model, batas biaya, atau batas token.

Pakai key tanpa pembatasan dari akun itu sendiri. Lihat Autentikasi & API key.

Contoh

curl

curl https://kenari.id/v1/account/balance \
  -H "Authorization: Bearer $KENARI_API_KEY"

Python

import os
import requests

response = requests.get(
    "https://kenari.id/v1/account/balance",
    headers={"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"},
)
response.raise_for_status()
balance = response.json()

print(balance["available_micro_idr"] / 1_000_000)

JavaScript

const response = await fetch("https://kenari.id/v1/account/balance", {
  headers: { Authorization: `Bearer ${process.env.KENARI_API_KEY}` },
});
if (!response.ok) throw new Error(await response.text());
const balance = await response.json();

console.log(balance.available_micro_idr / 1_000_000);

Cek sebelum batch

Skrip ini berhenti kalau saldo tersedia lebih kecil dari kebutuhan batch. Perkiraan kebutuhannya kamu tentukan sendiri.

import os
import requests

NEEDED_IDR = 50_000

response = requests.get(
    "https://kenari.id/v1/account/balance",
    headers={"Authorization": f"Bearer {os.environ['KENARI_API_KEY']}"},
)
response.raise_for_status()
available_idr = response.json()["available_micro_idr"] / 1_000_000

if available_idr < NEEDED_IDR:
    raise SystemExit(f"Hanya Rp {available_idr:,.0f} tersedia. Top up dulu.")

# Mulai batch di sini.

MCP

Tool MCP kenari_balance mengembalikan saldomu sebagai teks biasa, dalam Rupiah utuh. Lihat Server MCP.

Penagihan

Membaca saldo kamu gratis dan tidak punya batas laju sendiri. Lihat Cara penagihan.

Error

Status	Kode	Kapan
401	Tidak ada	Key tidak ada, tidak valid, atau sudah kedaluwarsa. Body-nya pesan teks singkat, bukan JSON.
403	`shared_key_not_allowed`	Key adalah API key dibagikan.
403	`restricted_key_not_allowed`	Key punya pembatasan model, batas biaya, atau batas token.
500	`internal_error`	Pembacaan saldo gagal di kenari. Coba lagi sekali.

Lihat Error untuk format error dan kode lainnya.