Batas pengeluaran gateway aplikasi Claude

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"}'

Permintaan ini menerapkan batas yang lebih ketat sebesar $100 per hari pada setiap anggota grup 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.

Batas grup atau organisasi adalah default per-kursi yang diwarisi setiap anggota, bukan kumpulan bersama. Per periode, batas efektif pengembang diselesaikan dalam urutan ini: penggantian per-pengguna, kemudian yang paling ketat dari batas grup mereka, kemudian default organisasi, kemudian tidak terbatas. 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=`.

Konvensi mencerminkan Admin API Anthropic:

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.

Paginasi

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.

Konfigurasi admin dan enforcement: mengaktifkan Admin API dan menyetel retensi
Panduan penerapan: skema Postgres dan panduan cadangan

Pengaturan dan akses

Penyebaran

Gateway

Penggunaan dan biaya

Distribusi Plugin

Keamanan dan data

Adopsi

Batas pengeluaran gateway aplikasi Claude

Tetapkan batas

Autentikasi ke Admin API

Cara penegakan bekerja

Ketersediaan Postgres

Referensi Admin API

`/effective`

`/audit`

Siklus hidup data

​Tetapkan batas

​Autentikasi ke Admin API

​Cara penegakan bekerja

​Ketersediaan Postgres

​Referensi Admin API

​/effective

​/audit

​Paginasi

​Siklus hidup data

​Terkait

Tetapkan batas

Autentikasi ke Admin API

Cara penegakan bekerja

Ketersediaan Postgres

Referensi Admin API

`/effective`

`/audit`

Paginasi

Siklus hidup data

Terkait