Batas pengeluaran membatasi berapa banyak yang dapat dikeluarkan setiap pengembang melalui gateway aplikasi Claude Anda dalam hari, minggu, atau bulan tertentu. Ketika seorang pengembang melampaui batas mereka, gateway mengembalikan 429 pada permintaan berikutnya dan memblokir mereka sampai periode disetel ulang atau admin menaikkan batas. Gunakan batas pengeluaran untuk memberikan setiap pengembang, grup, atau seluruh organisasi batas maksimal pada kredensial yang dibagikan semua orang.
Gateway aplikasi Claude meneruskan semua inferensi melalui satu kredensial hulu bersama, sehingga tagihan penyedia Anda mengatribusikan semuanya ke kredensial tersebut, bukan ke pengembang individual. Tanpa batas per-pengembang, satu armada agen yang tidak terkontrol dapat menghabiskan seluruh komitmen organisasi. Batas pengeluaran adalah tampilan per-pengembang gateway dan pemutus sirkuit di atas tagihan bersama tersebut.
Tetapkan batas
Dengan blok admin: yang dikonfigurasi dalam gateway.yaml, gateway melayani Admin API di /v1/organizations/spend_limits dan memberlakukan batas secara langsung pada setiap permintaan inferensi. Batas itu sendiri ditetapkan melalui API tersebut, bukan dalam gateway.yaml; setiap permintaan POST /v1/organizations/spend_limits membuat atau mengganti satu batas dari {scope, amount, period}. API mencerminkan bentuk kawat dari Admin API publik Anthropic untuk titik akhir batas pengeluaran, sehingga klien HTTP yang ditulis terhadap kontrak tersebut dapat menargetkan gateway dengan mengubah URL dasarnya.
Permintaan ini menetapkan default seluruh organisasi sebesar $500 per bulan untuk setiap pengembang:
curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
-H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'
contractors:
curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
-H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'
| Bidang | Nilai | Deskripsi |
|---|
scope.type | user, rbac_group, organization | user menargetkan satu pengembang berdasarkan OpenID Connect (OIDC) sub mereka, ID pengguna stabil yang ditetapkan penyedia identitas Anda; teruskan sebagai scope.user_id. rbac_group menargetkan grup IdP berdasarkan nama; teruskan sebagai scope.rbac_group_id. organization adalah default seluruh organisasi. Gateway menerima ketiganya; POST publik Anthropic hanya untuk pengguna hari ini. |
amount | String angka keseluruhan sen USD, atau null | null tidak terbatas. "0" adalah batas nol, yang memblokir setiap permintaan. |
period | daily, weekly, monthly | Ruang lingkup dapat menahan satu batas per periode, dan masing-masing memberlakukan secara independen: pengembang diblokir jika melampaui salah satu dari mereka. |
admin.group_limit_mode: max membalik tie-break multi-grup ke yang paling tidak ketat sebagai gantinya.
Autentikasi ke Admin API
Kirim salah satu dari:
- Header
x-api-key yang cocok dengan kunci dalam admin.write_keys untuk akses penuh, atau admin.read_keys untuk akses GET-saja. Setiap kunci membawa id yang muncul dalam log audit sebagai admin-key:<id>, jadi berikan Terraform, CI, dan setiap otomasi miliknya sendiri.
- Token pembawa gateway yang klaim
groups mencakup salah satu dari admin.admin_groups. Ini adalah akses penuh dan audit sebagai oidc:<sub>, jadi lebih suka untuk admin manusia.
Cara penegakan bekerja
Pada setiap permintaan /v1/messages, gateway menyelesaikan batas pengembang dan pengeluaran periode-ke-tanggal dalam satu kueri Postgres. Jika mereka melampaui batas apa pun, permintaan mengembalikan 429 dengan error.type: billing_error dan header x-should-retry: false. Pesan adalah spend limit reached, diikuti oleh admin.blocked_message Anda jika ditetapkan.
/v1/messages/count_tokens dikecualikan. Penghitungan token gratis, jadi berjalan terlepas dari status batas.
Setelah setiap respons, meter penggunaan membaca jumlah token dari respons saat mengalir ke klien, menghargainya pada harga daftar USD, dan menambah penghitung Postgres untuk ketiga bucket periode. Meter adalah pembaca tunggal pada aliran, jadi byte klien tidak tersentuh dan kegagalan metering tidak merusak respons.
Batas pengeluaran memperkirakan pengeluaran dari jumlah token pada harga daftar USD; mereka adalah pemutus sirkuit, bukan faktur. Untuk penagihan yang berwenang, rekonsiliasi terhadap pelaporan penggunaan penyedia Anda sendiri, seperti Admin API Penggunaan & Biaya Anthropic, log invokasi di Bedrock, atau Cloud Monitoring di Google Cloud.
Penetapan harga menggunakan tabel yang sama yang digunakan Claude Code CLI untuk tampilan biaya sendiri, dengan kanonikalisasi ID model yang sama di seluruh Anthropic, Bedrock (us.anthropic.…-v1:0), Agent Platform (claude-…@date), dan bentuk ID Foundry. ID model yang tidak dapat ditempatkan tabel, seperti nama penerapan Foundry atau ARN profil inferensi, dihargai pada tingkat default model yang tidak dikenal sebesar $5/$25 per juta token input/output daripada nol, jadi ID yang tidak dikenali tidak dapat melewati batas dengan tidak diukur. Gateway memperingatkan saat boot dan sekali per ID saat runtime ketika model dihargai melalui fallback.
Pembatalan klien juga ditagih. Hulu melaporkan token output hanya dalam bingkai terminal aliran, jadi aliran yang dibatalkan tidak membawanya. Meter menyimpan perkiraan lantai konservatif dari ukuran konten yang dialirkan, sekitar empat karakter per token, dan menagihnya ketika dan hanya ketika bingkai penggunaan terminal hilang. Aliran lengkap selalu menagih jumlah yang dilaporkan hulu. Tanpa ini, pengembang yang dibatasi dapat mengalirkan output dan membatalkan setiap permintaan segera sebelum akhir, menghabiskan tanpa pernah dihitung.
Ketersediaan Postgres
Kueri pra-pemeriksaan Postgres dengan batas waktu dua detik. Jika toko tidak dapat dijangkau atau waktu habis, penegakan gagal terbuka secara default: permintaan dilanjutkan dan gateway mencatat peringatan. Atur enforcement.fail_closed_on_error: true untuk gagal tertutup sebagai gantinya, yang mengembalikan 429 billing_error yang sama dengan pesan spend limit unavailable. Gagal-terbuka menjaga pemadaman toko agar tidak menjadi pemadaman inferensi; gagal-tertutup menjamin tidak ada pengeluaran yang tidak diukur.
Referensi Admin API
Titik akhir di bawah ini disajikan di bawah /v1/organizations/spend_limits.
| Metode dan jalur | Deskripsi |
|---|
GET /v1/organizations/spend_limits | Daftar batas yang dikonfigurasi. Kueri: ?limit=&after_id=&before_id=. |
POST /v1/organizations/spend_limits | Buat atau ganti batas untuk {scope, period}. |
GET /v1/organizations/spend_limits/{id} | Ambil satu batas berdasarkan ID dengan awalan spl_. |
DELETE /v1/organizations/spend_limits/{id} | Hapus satu batas. Mengembalikan {type: "spend_limit_deleted", id}. |
GET /v1/organizations/spend_limits/effective | Batas yang diselesaikan dan pengeluaran periode-ke-tanggal per prinsipal per periode. |
GET /v1/organizations/spend_limits/audit | Jejak mutasi admin, terbaru-pertama. Kueri: ?limit=. |
type pada setiap objek- ID dengan awalan
spl_
- Jumlah sebagai string angka keseluruhan sen USD;
POST menolak currency lain apa pun dengan 400
- Amplop kesalahan
{type: "error", error: {type, message}, request_id}
- Header respons
request-id pada setiap respons admin, sukses atau kesalahan, cocok dengan request_id badan
Setiap mutasi menulis baris sebelum/sesudah ke admin_audit dalam transaksi yang sama, dikaitkan dengan admin-key:<id> atau oidc:<sub>.
Gateway melayani titik akhir batas pengeluaran saja. Permukaan Admin API lainnya, seperti antrian spend_limit_increase_requests, bukan bagian dari admin API gateway.
/effective
GET /v1/organizations/spend_limits/effective mengembalikan skema SpendSummary Anthropic: setiap baris adalah prinsipal untuk periode, dengan batas yang diselesaikan, pengeluaran periode-ke-tanggal, dan objek actor. Perbedaan khusus gateway:
user_id adalah OIDC sub.actor.name dan actor.email_address adalah null sampai permintaan inferensi pertama prinsipal melalui gateway. Gateway tidak memiliki direktori pengguna; itu mencatat nilai terakhir terlihat dari JWT sesi setiap pengguna.- Setiap baris juga membawa array
groups, grup IdP terakhir terlihat prinsipal. Ini adalah ekstensi gateway sehingga UI admin dapat menunjukkan setiap tingkat batas yang berlaku; klien berbentuk Anthropic mengabaikannya.
- Tanpa filter
user_ids[], itu mencantumkan prinsipal dengan pengeluaran yang tercatat, karena gateway tidak dapat menghitung semua anggota organisasi.
Batas bersumber grup diselesaikan terhadap grup terakhir terlihat dengan tie-break group_limit_mode yang sama yang digunakan penegakan, jadi penampil menunjukkan batas yang benar-benar berlaku.
| Parameter kueri | Deskripsi |
|---|
user_ids[] | Dapat diulang. Filter ke prinsipal spesifik berdasarkan OIDC sub. |
period[] | Dapat diulang. Filter ke baris daily, weekly, atau monthly. |
sort | spend_desc mencantumkan pengguna teratas terlebih dahulu. Memerlukan tepat satu period[]. |
q | Filter substring yang tidak peka huruf besar-kecil atas OIDC sub, email terakhir terlihat, dan nama tampilan terakhir terlihat. |
limit / page | Ukuran halaman, 1–1000 dengan default 20, dan kursor buram dari next_page respons sebelumnya. |
q= dan user_ids[]= naik string kueri GET, jadi proxy fronting apa pun atau penyeimbang beban menangkapnya dalam log akses. Jika kebijakan log PII Anda ketat, bersihkan parameter ini di sana.
/audit
Mengembalikan jejak mutasi batas pengeluaran: siapa yang mengubah batas mana, snapshot sebelum/sesudah, dan alasan opsional, terbaru-pertama. has_more tepat. Titik akhir ini mengikuti konvensi Admin API lokal daripada bentuk kawat pihak pertama.
Daftar mentah halaman berdasarkan after_id dan before_id, yang merupakan ID spl_… yang saling eksklusif; hasil diurutkan berdasarkan pembuatan dan has_more mencerminkan arah traversal. /effective halaman berdasarkan token next_page buram yang diteruskan kembali sebagai ?page=, dengan prinsipal diurutkan naik sehingga halaman tetap stabil saat pengeluaran sedang dicatat. limit adalah 1–1000, default 20, di keduanya.
Siklus hidup data
Gateway menyimpan empat tabel terkait pengeluaran; sapuan per jam memberlakukan jendela retensi:
| Tabel | Isi | Retensi |
|---|
spend | Penghitung periode-ke-tanggal per-prinsipal dalam sen | admin.spend_retention_months, default 13 |
spend_limits | Batas yang dikonfigurasi | Sampai dihapus melalui API |
admin_audit | Jejak mutasi | admin.audit_retention_days, default 365 |
principal_emails | Email terakhir terlihat setiap prinsipal, nama tampilan, dan grup IdP. Berisi PII. | admin.identity_retention_days sejak aktivitas terakhir, default 90 |
identity_retention_days sengaja lebih pendek dari spend_retention_months: identitas yang dihapus provisioning berhenti menyegarkan dan menua, sementara penghitung pengeluaran anonimnya tetap untuk pelaporan tahun-ke-tahun.
Ketika pengembang pergi, hapus batas per-pengguna apa pun melalui DELETE /v1/organizations/spend_limits/{id}; pengeluaran dan baris identitas mereka menua pada jendela retensi di atas. Untuk menghapus satu orang segera, untuk offboarding atau permintaan akses subjek data (DSAR), jalankan DELETE FROM principal_emails WHERE principal = '<sub>' langsung terhadap database gateway. Itu menghapus satu-satunya tabel yang menyimpan email, nama, dan grup mereka. Baris spend dan admin_audit mereferensikan OIDC sub pseudonim saja dan menua pada jendela mereka sendiri.
