Spend Limits API

Spend Limits API memungkinkan Anda menetapkan batas pengeluaran pada setiap anggota Claude Enterprise, melihat dari mana batas pengeluaran setiap anggota diwarisi, dan meninjau atau menindaklanjuti permintaan anggota untuk batas yang lebih tinggi.

Untuk pelaporan penggunaan dan biaya per pengguna dan berdasarkan rentang waktu, lihat Analytics API.



Ikhtisar

API ini menyediakan delapan endpoint di dua resource:

Gunakan endpoint spend limits untuk menjawab "batas pengeluaran apa yang berlaku untuk setiap anggota, dari mana asalnya, dan seberapa dekat mereka dengan batas tersebut?" dan untuk menetapkan override per pengguna. Gunakan endpoint spend limit increase requests untuk memproses antrean permintaan yang diajukan anggota.



Prasyarat

• Organisasi Anda harus menggunakan paket Claude Enterprise.
• Kredit penggunaan harus diaktifkan untuk organisasi Anda. Primary owner Anda dapat mengaktifkannya di pengaturan penagihan claude.ai.



Mulai cepat

Cantumkan batas pengeluaran bulanan efektif setiap anggota dan pengeluaran periode-hingga-saat-ini:

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Konsep utama



Hierarki batas pengeluaran

Sebuah batas pengeluaran efektif berlaku untuk pengeluaran setiap anggota, yang diresolusi dari hierarki tingkat cakupan. Ketika seorang anggota tidak memiliki override per pengguna, mereka mewarisi batas pengeluaran yang dikonfigurasi untuk grup mereka (jika organisasi Anda menggunakan batas berbasis grup), tingkat kursi mereka, atau default seluruh organisasi. Batas pengeluaran grup adalah default per anggota: setiap anggota yang mewarisinya dibatasi berdasarkan pengeluaran mereka sendiri, bukan anggaran grup yang digabungkan.

Membaca GET /v1/organizations/spend_limits/effective mengembalikan setiap anggota saat ini dengan batas pengeluaran efektif mereka yang telah diresolusi, dari mana batas tersebut diresolusi (source), dan pengeluaran periode-hingga-saat-ini mereka. Menetapkan override per pengguna dengan POST /v1/organizations/spend_limits mengunci anggota ke batas pengeluaran tertentu terlepas dari apa yang seharusnya mereka warisi. Menghapus override mengembalikan mereka ke batas pengeluaran yang diwarisi (atau membiarkan mereka tanpa batas jika tidak ada yang tersedia).

Field source pada baris setiap anggota memberi tahu Anda dari tingkat mana batas pengeluaran mereka diresolusi: user (override per pengguna), seat_tier, rbac_group, atau organization. Perlakukan tipe cakupan sebagai himpunan terbuka; lewati nilai yang tidak dikenal alih-alih gagal.



Periode

period adalah jendela berulang di mana batas pengeluaran diberlakukan dan pengeluaran direset. Sebuah batas pengeluaran diidentifikasi oleh pasangan (scope, period)-nya. Saat ini monthly adalah satu-satunya periode yang didukung; pengeluaran bulanan direset pada pukul 00



Jumlah dan mata uang

Semua nilai moneter adalah string dalam unit minor dari mata uang penagihan organisasi (sen, untuk USD). Misalnya, "50000" mewakili 500,00 USD. Parse sebagai desimal dan bagi dengan 100 untuk menampilkan dolar; hindari floating-point biner untuk nilai besar.

amount bersifat nullable. Pada baris efektif anggota, null berarti tanpa batas (tidak ada batas pengeluaran) dan "0" berarti anggota tidak dapat menggunakan Claude di luar penggunaan yang termasuk dalam paket mereka. Pada baris batas pengeluaran yang dikonfigurasi (seperti yang dikembalikan oleh GET /v1/organizations/spend_limits/{id}), null hanya berarti tidak ada batas pengeluaran numerik yang ditetapkan; baca baris efektif anggota untuk membedakan antara tanpa batas dan hanya-penggunaan-yang-termasuk.

period_to_date_spend adalah pengeluaran anggota yang terakumulasi sejak awal period saat ini, dalam format unit minor yang sama; nilai ini dapat mencakup bagian pecahan (misalnya, "41280.125"). Nilai ini dapat terbaca sebagai "0" jika pembacaan pengeluaran untuk sementara tidak tersedia; perlakukan sebagai informasi, bukan transaksional.



Siklus hidup permintaan peningkatan

Sebuah permintaan peningkatan batas pengeluaran dibuat ketika anggota mengklik Request more usage di claude.ai. Permintaan tidak dibuat melalui API ini. status permintaan adalah salah satu dari:

Baik approved maupun denied bersifat terminal. Seorang anggota memiliki paling banyak satu permintaan pending pada satu waktu.

Menyetujui dengan POST /v1/organizations/spend_limit_increase_requests/{id}/approve menulis baris batas pengeluaran per pengguna yang sama dengan yang ditulis oleh POST /v1/organizations/spend_limits. Menetapkan batas pengeluaran secara langsung tidak mengubah status permintaan yang pending; gunakan endpoint approve untuk menyelesaikan permintaan.

Secara default, Anthropic mengirim email kepada anggota ketika permintaan mereka disetujui atau ditolak. Sertakan suppress_notification: true pada approve atau deny untuk menekan email tersebut (misalnya, ketika sistem Anda sendiri yang memberi tahu anggota).



Pembatasan laju

Kedelapan endpoint berbagi satu batas per organisasi sebesar 60 permintaan per menit. Permintaan yang melebihi batas mengembalikan 429 Too Many Requests.



Paginasi

GET /v1/organizations/spend_limits/effective dan GET /v1/organizations/spend_limit_increase_requests dipaginasi dengan kursor opaque. Permintaan pertama mengembalikan hingga limit baris ditambah kursor next_page; sertakan kursor tersebut tanpa perubahan sebagai parameter page pada permintaan berikutnya, dan ulangi hingga next_page bernilai null.

Jangan mengubah parameter kueri di tengah urutan. Kursor terikat pada filter yang menghasilkannya. Jika Anda mengubah user_ids[], period[], status[], atau actor_ids[] dan menyertakan kursor lama, Anda akan mendapatkan 400 dengan "cursor does not match current query parameters". Mulai urutan baru dari halaman pertama sebagai gantinya.



Serialisasi parameter daftar

Parameter daftar menggunakan notasi kurung siku: ulangi nama parameter dengan [] untuk setiap nilai.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq



Respons error

Respons error mengikuti bentuk standar yang didokumentasikan di Errors. Kutip request_id dari body respons saat menghubungi dukungan.



Spend limits



Mencantumkan batas pengeluaran efektif setiap anggota

GET /v1/organizations/spend_limits/effective mengembalikan satu baris per anggota saat ini, yang mencerminkan batas pengeluaran efektif setiap anggota, source-nya dalam hierarki cakupan, dan period_to_date_spend mereka. Memerlukan cakupan read:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat List effective spend limits di referensi API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?limit=20" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

{
  "data": [
    {
      "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
      "actor": {
        "type": "user_actor",
        "user_id": "user_01AbCdEfGh",
        "name": "Jane Smith",
        "email_address": "[email protected]",
        "deleted": false
      },
      "amount": "50000",
      "currency": "USD",
      "period": "monthly",
      "source": { "type": "seat_tier", "seat_tier": "enterprise_standard" },
      "spend_limit_id": "spl_01XyZaBcDeFgHiJkLmNoPq",
      "period_to_date_spend": "31402.5"
    }
  ],
  "next_page": "page_..."
}



Mendapatkan satu batas pengeluaran

GET /v1/organizations/spend_limits/{spend_limit_id} mengembalikan satu batas pengeluaran yang dikonfigurasi berdasarkan ID. Gunakan untuk memeriksa baris yang direferensikan oleh field spend_limit_id. Memerlukan cakupan read:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Retrieve a spend limit di referensi API.

curl "https://api.anthropic.com/v1/organizations/spend_limits/spl_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Menetapkan override per pengguna

POST /v1/organizations/spend_limits menetapkan override batas pengeluaran per pengguna. Ini adalah upsert yang dikunci pada (scope, period): menetapkan batas untuk pengguna dan periode yang sudah memilikinya akan menimpanya di tempat. Endpoint ini hanya menerima scope.type: "user"; default tingkat kursi, grup, dan organisasi dikonfigurasi di pengaturan claude.ai. Memerlukan cakupan write:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Create a spend limit di referensi API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limits" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"scope": {"type": "user", "user_id": "user_01AbCdEfGh"}, "amount": "75000"}'

{
  "type": "spend_limit",
  "id": "spl_01RsTuVwXyZaBcDeFgHiJk",
  "created_at": "2026-05-11T10:02:44Z",
  "updated_at": "2026-05-11T10:02:44Z",
  "scope": { "type": "user", "user_id": "user_01AbCdEfGh" },
  "amount": "75000",
  "currency": "USD",
  "period": "monthly"
}



Menghapus override per pengguna

DELETE /v1/organizations/spend_limits/{spend_limit_id} menghapus override per pengguna, setelah itu anggota kembali ke default tingkat kursi, grup, atau organisasi yang diwarisi. Baris tingkat kursi, grup, dan organisasi tidak dapat dihapus melalui endpoint ini. Memerlukan cakupan write:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Delete a spend limit di referensi API.

curl --request DELETE "https://api.anthropic.com/v1/organizations/spend_limits/spl_01RsTuVwXyZaBcDeFgHiJk" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Spend limit increase requests



Mencantumkan permintaan peningkatan

GET /v1/organizations/spend_limit_increase_requests mencantumkan permintaan, yang terbaru lebih dulu. Filter berdasarkan status[] (pending, approved, denied) dan actor_ids[]. Daftar ini mengecualikan permintaan yang pemohonnya bukan lagi anggota organisasi. Memerlukan cakupan read:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat List spend limit increase requests di referensi API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=50" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

Setiap permintaan pending membawa spend_summary langsung yang menunjukkan batas pengeluaran efektif pemohon saat ini dan pengeluaran periode-hingga-saat-ini, cukup untuk memutuskan tanpa pencarian terpisah.



Mendapatkan satu permintaan peningkatan

GET /v1/organizations/spend_limit_increase_requests/{id} mengembalikan satu permintaan berdasarkan ID. Memerlukan cakupan read:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Retrieve a spend limit increase request di referensi API.

curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"



Menyetujui permintaan peningkatan

POST /v1/organizations/spend_limit_increase_requests/{id}/approve menyetujui permintaan pending: endpoint ini menulis batas pengeluaran per pengguna pada amount yang disediakan admin untuk pemohon dan mengubah status permintaan menjadi approved. Permintaan tidak membawa jumlah yang diminta; Anda menyediakan batas pengeluaran baru saat persetujuan. Memerlukan cakupan write:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Approve a spend limit increase request di referensi API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/approve" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"amount": "75000", "suppress_notification": true}'



Menolak permintaan peningkatan

POST /v1/organizations/spend_limit_increase_requests/{id}/deny menolak permintaan pending. Idempoten pada denied: menolak permintaan yang sudah ditolak mengembalikan 200 dengan resource yang ada. Endpoint menolak upaya untuk menolak permintaan yang sudah disetujui sehingga otomatisasi dapat membedakan percobaan ulang dari keputusan yang bertentangan. Memerlukan cakupan write:spend_limits.

Untuk detail parameter lengkap dan skema respons, lihat Deny a spend limit increase request di referensi API.

curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/slir_01AbCdEfGhIjKlMnOpQrSt/deny" \
  --header "content-type: application/json" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  --data '{"suppress_notification": true}'



Contoh alur kerja

Alur kerja ini menggabungkan Spend Limits API dengan endpoint biaya Analytics API. Endpoint biaya Analytics dirancang untuk pelaporan pengeluaran seluruh organisasi di seluruh rentang tanggal. GET /spend_limits/effective mengembalikan batas yang saat ini berlaku untuk setiap anggota. Mulai penyisiran dengan Analytics untuk menemukan anggota mana yang perlu dilihat, lalu baca batas mereka saat ini dengan /effective.

Endpoint Spend Limits memerlukan cakupan spend_limits dan endpoint biaya Analytics memerlukan read:analytics; lihat Analytics API untuk cara menyediakan akses. Semua nilai moneter pada keduanya adalah string desimal dalam unit minor (sen). Kedua API dipaginasi dengan kursor opaque. Tetapkan limit eksplisit dan lakukan paginasi melalui next_page hingga bernilai null untuk mencakup seluruh organisasi.



Mengotomatiskan alur peninjauan permintaan peningkatan

Jalankan tugas terjadwal yang mengambil permintaan pending, menerapkan kebijakan persetujuan organisasi Anda, dan menyelesaikan masing-masing.

1. Cantumkan permintaan pending:

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests?status[]=pending&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   Setiap permintaan membawa actor.user_id pemohon dan spend_summary langsung dengan amount efektif mereka saat ini dan period_to_date_spend, cukup untuk memutuskan tanpa pencarian terpisah.

2. Terapkan kebijakan Anda. Misalnya, setujui otomatis ketika amount anggota saat ini di bawah ambang batas, dan arahkan batas yang lebih besar untuk peninjauan manual.

3. Selesaikan setiap permintaan. Untuk menyetujui, sediakan batas baru:

   cURL

   

   curl --request POST "https://api.anthropic.com/v1/organizations/spend_limit_increase_requests/{id}/approve" \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY" \
     --data '{"amount": "75000", "suppress_notification": true}'

   Untuk menolak, lakukan POST ke .../{id}/deny sebagai gantinya. Sertakan suppress_notification: true ketika sistem Anda sendiri yang memberi tahu pemohon.



Mengidentifikasi anggota yang mendekati batas pengeluaran mereka

Temukan anggota yang mendekati batas mereka sehingga Anda dapat menaikkannya sebelum mereka diblokir.

1. Ambil pengeluaran bulan-hingga-saat-ini setiap anggota dari Analytics API (satu baris per anggota, pengeluaran tertinggi lebih dulu secara default):

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   Setiap baris membawa actor.user_id, actor.email, dan amount (pengeluaran anggota dalam sen). Lakukan paginasi melalui next_page untuk mencakup seluruh organisasi.

2. Untuk pembelanja teratas (atau semua orang di atas ambang batas dolar), ambil batas efektif dalam batch:

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/spend_limits/effective?user_ids[]=user_01Ab...&user_ids[]=user_01Cd...&limit=100" \
     --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

   Setiap baris mengembalikan batas sebagai amount (null = tanpa batas, "0" = hanya penggunaan yang termasuk) bersama dengan period_to_date_spend.

3. Untuk setiap anggota dengan batas positif, hitung period_to_date_spend / amount dan tandai mereka yang berada pada atau di atas ambang batas Anda (misalnya, 80 persen). Perlakukan batas "0" sebagai sudah mencapai batas. Tidak ada filter sisi server untuk rasio ini.

4. Tindak lanjuti anggota yang ditandai: naikkan batas dengan POST /v1/organizations/spend_limits, setujui permintaan peningkatan pending jika ada, atau hubungi anggota tersebut.



Menemukan anggota dengan penggunaan yang berubah cepat

Tampilkan anggota yang pengeluarannya melonjak dari minggu ke minggu.

1. Ambil biaya harian per anggota untuk dua minggu terakhir dari Analytics API:

   cURL

   

   curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \
     --header "x-api-key: $ANALYTICS_API_KEY"

   Dengan bucket_width ditetapkan, setiap anggota mencakup satu baris per hari dengan penggunaan; lakukan paginasi melalui next_page untuk mengumpulkan seri lengkap setiap anggota.

2. Kelompokkan baris berdasarkan actor.user_id. Untuk setiap anggota, jumlahkan tujuh hari terakhir dan tujuh hari sebelumnya. Tandai anggota yang minggu terakhirnya melebihi minggu sebelumnya dengan kelipatan yang Anda pilih (misalnya, tiga). Biaya hari terakhir bersifat sementara dan dapat direvisi ke atas; untuk perbandingan yang dapat diulang, tetapkan ending_at pada atau sebelum data_refreshed_at yang dikembalikan sebelumnya (lihat Ketersediaan dan kesegaran data).

3. Tindak lanjuti anggota yang ditandai: sesuaikan batas dengan POST /v1/organizations/spend_limits, atau hubungi mereka.



Pertanyaan yang sering diajukan



Apakah menetapkan batas pengeluaran secara langsung menyelesaikan permintaan peningkatan pending anggota?

Tidak. POST /v1/organizations/spend_limits menulis override tetapi membiarkan permintaan pending tidak tersentuh. Gunakan POST /v1/organizations/spend_limit_increase_requests/{id}/approve untuk menyelesaikan permintaan dan menulis override dalam satu panggilan.



Apa yang terjadi ketika saya menghapus override per pengguna?

Anggota kembali ke apa pun yang akan mereka warisi dari hierarki: default grup, tingkat kursi, atau organisasi mereka. Jika tidak ada default di tingkat mana pun, anggota tersebut tanpa batas.



Dapatkah saya menetapkan default tingkat kursi atau seluruh organisasi melalui API ini?

Tidak. Hanya override per pengguna yang dapat ditulis melalui API ini. Default tingkat kursi, grup, dan organisasi dikonfigurasi di pengaturan Organisasi claude.ai.



Mengapa period_to_date_spend terkadang terbaca sebagai "0" untuk anggota yang aktif?

Pembacaan pengeluaran dapat untuk sementara tidak tersedia, dalam hal ini field terbaca "0" alih-alih menghasilkan error. Perlakukan sebagai informasi.



Lihat juga