Spend limit trên Claude apps gateway

Spend limit giới hạn số tiền mỗi developer có thể chi qua Claude apps gateway của bạn trong một ngày, tuần, hoặc tháng. Khi một developer vượt cap, gateway trả 429 cho request kế tiếp và chặn họ đến khi period reset hoặc admin nâng cap. Dùng spend limit để đặt trần chi tiêu cho từng developer, group, hoặc cả tổ chức trên một credential mà mọi người dùng chung.

Một Claude apps gateway forward toàn bộ inference qua một credential upstream chung, nên hóa đơn của provider gộp hết vào credential đó, không tách theo từng developer. Không có giới hạn theo developer, một agent fleet chạy loạn có thể tiêu hết commitment của cả tổ chức. Spend limit là góc nhìn theo developer và circuit breaker của gateway trên hóa đơn chung đó.

Đặt cap

Với block admin: đã cấu hình trong gateway.yaml, gateway serve admin API tại /v1/organizations/spend_limits và enforce cap trực tiếp trên mỗi request inference. Cap được set qua API đó, không phải trong gateway.yaml; mỗi request POST /v1/organizations/spend_limits tạo hoặc thay thế một cap từ {scope, amount, period}. API này mirror wire shape của Admin API công khai của Anthropic.

Request này set default toàn tổ chức $500/tháng cho mỗi developer:

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

Request này áp cap chặt hơn $100/ngày cho mỗi thành viên group 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"}'

Field	Giá trị	Mô tả
scope.type	user, rbac_group, organization	user nhắm một developer bằng OIDC sub (pass qua scope.user_id); rbac_group nhắm một IdP group theo tên (scope.rbac_group_id); organization là default toàn tổ chức.
amount	Chuỗi số nguyên đơn vị cent USD, hoặc null	null là không giới hạn. "0" là cap bằng không, chặn mọi request.
period	daily, weekly, monthly	Mỗi scope giữ một cap cho mỗi period, mỗi cap enforce độc lập - developer bị chặn nếu vượt bất kỳ cap nào.

Cap của group hay tổ chức là default per-seat mà mỗi thành viên kế thừa, không phải một pool chung. Mỗi period, cap hiệu lực của một developer resolve theo thứ tự: override theo user, rồi cap group chặt nhất, rồi default tổ chức, rồi không giới hạn. admin.group_limit_mode: max đảo ngược tie-break đa group thành lỏng nhất thay vì chặt nhất.

Xác thực với admin API

Gửi một trong hai:

• Header x-api-key khớp một key trong admin.write_keys (full access) hoặc admin.read_keys (chỉ đọc). Mỗi key có một id xuất hiện trong audit log dạng admin-key:<id> - nên cấp key riêng cho Terraform, CI, và từng automation.
• Một gateway bearer token có claim groups chứa một trong admin.admin_groups. Đây là full access, audit dạng oidc:<sub> - ưu tiên dùng cho admin là con người.

Cơ chế enforcement

Trên mỗi request /v1/messages, gateway resolve cap và spend period-to-date của developer trong một query Postgres. Nếu vượt bất kỳ cap nào, request trả 429 với error.type: billing_error và header x-should-retry: false. Message là spend limit reached, theo sau bởi admin.blocked_message nếu có set.

/v1/messages/count_tokens được miễn - đếm token miễn phí nên chạy bất kể trạng thái cap.

Sau mỗi response, một usage meter đọc token count từ response khi nó stream về client, định giá theo USD list price, và tăng bộ đếm Postgres cho cả ba period bucket. Meter chỉ là một reader trên stream nên bytes của client không bị đụng vào và lỗi metering không làm hỏng response.

Chú ý

Spend limit ước lượng chi tiêu từ token count theo giá list USD - nó là circuit breaker, không phải hóa đơn chính thức. Để có số liệu billing chính xác, đối chiếu với báo cáo usage riêng của provider (Anthropic Usage & Cost Admin API, log invocation Bedrock, Cloud Monitoring…).

Meter resolve tier giá theo thứ tự: rate chính xác cho model ID upstream (khi nhận diện được), rate cho models[].id bạn cấu hình map sang ID upstream (cần Claude Code v2.1.218+ trên gateway server), rồi tier default cho model chưa biết ở mức $5/$25 mỗi triệu token input/output. Gateway warning khi boot và mỗi khi định giá một model ở tier chưa biết trong runtime.

Client abort cũng được tính phí. Upstream chỉ báo output token trong frame kết thúc của stream, nên một stream bị abort không mang theo chúng. Meter giữ một ước lượng sàn thận trọng từ kích thước content đã stream (khoảng bốn ký tự mỗi token), và tính phí khi và chỉ khi frame usage kết thúc bị thiếu.

Khả dụng của Postgres

Pre-check query Postgres với timeout hai giây. Nếu store không reachable hoặc timeout, enforcement mặc định fail open: request tiếp tục và gateway log warning. Set enforcement.fail_closed_on_error: true để fail closed thay vào đó, trả cùng 429 billing_error với message spend limit unavailable. Fail-open giữ cho một outage của store không biến thành outage inference; fail-closed đảm bảo không có chi tiêu nào không được tính.

Admin API reference

Các endpoint dưới đây serve tại /v1/organizations/spend_limits.

Method và path	Mô tả
GET /v1/organizations/spend_limits	List cap đã cấu hình. Query: ?limit=&after_id=&before_id=.
POST /v1/organizations/spend_limits	Tạo hoặc thay thế cap cho {scope, period}.
GET /v1/organizations/spend_limits/{id}	Lấy một cap theo ID prefix spl_.
DELETE /v1/organizations/spend_limits/{id}	Xóa một cap.
GET /v1/organizations/spend_limits/effective	Cap đã resolve và spend to-date theo principal theo period.
GET /v1/organizations/spend_limits/audit	Lịch sử mutation admin, mới nhất trước. Query: ?limit=.

Quy ước theo Admin API của Anthropic: type trên mọi object, ID prefix spl_, amount dạng chuỗi cent USD, error envelope {type: "error", error: {type, message}, request_id}, và header request-id trên mọi response admin.

/effective

Trả về schema SpendSummary của Anthropic: mỗi dòng là một principal cho một period, kèm cap đã resolve, spend period-to-date, và object actor. Khác biệt riêng của gateway: user_id là OIDC sub; actor.name/actor.email_address là null đến lần inference đầu tiên của principal đó; mỗi dòng còn có mảng groups (IdP group last-seen, extension riêng của gateway).

Chú ý

q= và user_ids[]= đi trên query string GET, nên bất kỳ proxy/load balancer phía trước nào cũng ghi lại chúng trong access log. Nếu chính sách PII của bạn nghiêm ngặt, hãy scrub các tham số này ở đó.

Vòng đời dữ liệu

Gateway giữ bốn bảng liên quan đến spend; một lượt quét hằng giờ enforce các cửa sổ retention:

Bảng	Nội dung	Retention
spend	Bộ đếm period-to-date theo principal, tính bằng cent	admin.spend_retention_months, default 13
spend_limits	Cap đã cấu hình	Đến khi xóa qua API
admin_audit	Lịch sử mutation	admin.audit_retention_days, default 365
principal_emails	Email, tên hiển thị, IdP group last-seen (có PII)	admin.identity_retention_days, default 90

Khi một developer rời đi, xóa cap theo user (nếu có) qua DELETE /v1/organizations/spend_limits/{id}; spend và identity của họ tự hết hạn theo cửa sổ retention. Để xóa ngay lập tức cho offboarding hoặc yêu cầu xóa dữ liệu (DSAR), chạy trực tiếp DELETE FROM principal_emails WHERE principal = '<sub>' trên database gateway - đây là bảng duy nhất giữ email, tên, và group của họ.

Liên quan

• Cấu hình admin và enforcement: bật admin API và tinh chỉnh retention
• Deployment guide: schema Postgres và hướng dẫn backup

Nguồn

Dịch và biên soạn từ Claude apps gateway spend limits.