Claude Enterprise Admin API reference guide (original) (raw)
This guide covers spend limits and spend limit increase requests for your Claude Enterprise organization using the Claude Enterprise Admin API. Spend limits let you cap each member's usage credit spending over a recurring period, see where each member's limit is inherited from, and review or act on members' requests for a higher limit.
Overview
There are eight endpoints across two resources:
Use the spend limits endpoints to answer, “What limit applies to each member, where does it come from, and how close are they to it?" and to set a per-user override. Use the spend limit increase requests endpoints to work the queue of member-submitted requests.
Prerequisites and authentication
Pass the key in the x-api-key header on every request.
Base URL
Rate limiting
All eight endpoints share a single per-organization limit of 60 requests per minute. Requests over the limit return 429 Too Many Requests.
Pagination
GET /v1/organizations/spend_limits/effective and GET /v1/organizations/spend_limit_increase_requests are paginated with an opaque cursor. The first request returns up to limit rows plus a next_page cursor. Pass that cursor unchanged as the page parameter on the next request, and repeat until next_page is null.
Treat the cursor string as opaque: don't parse, modify, or construct it yourself.
Serializing list parameters
List parameters use bracket notation: repeat the parameter name with [] for each value.
Error responses
Error bodies have the shape:
error.type is a status-dependent discriminator: invalid_request_error (400), authentication_error (401), permission_error (403), not_found_error (404), rate_limit_error (429), api_error (500). request_id is always present and is the value to quote when contacting support. The Validations table under each endpoint lists the specific messages.
Concepts
The spend limit hierarchy
Each member's usage credit spending is capped by an effective spend limit, resolved from a hierarchy of scope levels. When a member has no per-user override, they inherit the limit configured for their seat tier, their group (if your organization uses group-based limits), or the organization-wide default.
Reading GET /v1/organizations/spend_limits/effective returns every current member with their resolved effective limit, where that limit was resolved from (source), and their period-to-date spend. Setting a per-user override via POST /v1/organizations/spend_limits pins a member to a specific limit regardless of what they would otherwise inherit. Deleting the override returns them to the inherited limit.
Scope
A scope identifies the level a spend limit is written or resolved at:
scope.type is an open string. Clients should treat unknown values as opaque and fall through rather than fail. Additional scope types may be added in future.
Period
period is the recurring window over which the limit is enforced and spend resets. The only value today is "monthly".
period is an open string. Clients should treat unknown values as opaque and fall through rather than fail. Additional period values may be added in the future.
Amounts and currency
All monetary values are strings in minor units of the organization's billing currency (cents, for USD). For example, "50000" represents 500.00 USD. Parse as a decimal and divide by 100 to display dollars. Avoid binary floating-point for large values.
amount is nullable: null means unlimited (no limit). "0" means usage credits are disabled for that member.
period_to_date_spend is the member's usage credit accrued since the start of the current period, in the same minor-unit format. It may include a fractional part (for example, "41280.125").
Increase request lifecycle
A spend limit increase request is created when a member clicks "request more usage" in claude.ai. Requests are not created via this API.
Both approved and denied are terminal. A member has at most one pending request at a time.
Approving via POST …/approve writes the same per-user spend limit row that POST /v1/organizations/spend_limits writes. Setting a spend limit directly does not transition a pending request. Use the approve endpoint to resolve a request.
By default, Anthropic emails the member when their request is approved or denied. Pass suppress_notification: true on approve or deny to suppress that email (for example, when your own system notifies the member).
The SpendLimit object
A configured limit at one scope level.
The SpendSummary object
A computed per-member report row: the member's effective limit, where it came from, and their period-to-date spend. Not an addressable resource (no id).
The SpendLimitIncreaseRequest object
Actor
Spend limits
1. List effective spend limits
Returns every current member of the organization with their resolved effective limit and period-to-date spend. Members without a per-user override appear with source.type of seat_tier, rbac_group, or organization. Ex-members aren’t listed.
Requires scope: read:spend_limits.
Query parameters
Response fields
Example request
Example response
Validations
2. Get a spend limit
Returns a single spend limit by ID. Use this to inspect the row that a SpendSummary.spend_limit_id or a POST response referenced.
Requires scope: read:spend_limits.
Path parameters
Response
A SpendLimit object.
Example request
Validations
3. Set a spend limit
Sets a per-user spend limit override. Upsert: setting a limit for a user who already has one overwrites it in place.
Only scope.type: "user" is accepted. Seat-tier, group, and organization-level defaults are configured in claude.ai settings.
Setting a spend limit directly does not transition a member's pending increase request. Use the approve endpoint to resolve a request.
Requires scope: write:spend_limits.
Request body
Response
A SpendLimit object reflecting the written override.
Example request
Example response
Validations
4. Remove a spend limit
Removes a per-user override so the member falls back to the inherited limit (seat tier, group, or organization default). Seat-tier, group, and organization-level rows can’t be deleted via this endpoint.
Requires scope: write:spend_limits.
Path parameters
Response
Example request
Validations
Spend limit increase requests
5. List increase requests
Lists increase requests, most recent first. Requests whose requester is no longer a member of the organization are excluded.
Requires scope: read:spend_limits.
Query parameters
Response fields
Example request
Example response
Validations
6. Get an increase request
Returns a single increase request.
Requires scope: read:spend_limits.
Path parameters
Response
A SpendLimitIncreaseRequest object.
Example request
Validations
7. Approve an increase request
Approves a pending request. Writes a per-user spend limit at amount for the requester and transitions the request to approved. The request doesn’t carry a requested amount, the admin supplies the new limit on approval.
Requires scope: write:spend_limits.
Path parameters
Request body
Response
The SpendLimitIncreaseRequest in status approved, with an additional spend_limit field containing the SpendLimit that was written.
Example request
Example response
Validations
8. Deny an increase request
Denies a pending request. Idempotent on denied: denying an already-denied request returns 200 with the existing resource. Denying an already-approved request is rejected so automation can distinguish a retry from a conflicting decision.
Requires scope: write:spend_limits.
Path parameters
Request body
Response
A SpendLimitIncreaseRequest in status denied.
Example request
Validations
Related Articles
Manage usage credits for Team and seat-based Enterprise plansEnterprise configuration for Claude DesktopGet started with the Claude Enterprise Analytics APIClaude Enterprise Analytics API reference guideClaude Enterprise consumption guide