Spend Limits API

The Spend Limits API lets you set a spend limit on each Claude Enterprise member, see where each member's spend limit is inherited from, and review or act on members' requests for a higher limit.

For per-user and time-bucketed usage and cost reporting, see Analytics APIs.



Overview

The API exposes eight endpoints across two resources:

Use the spend limits endpoints to answer "what spend 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

• Your organization must be on a Claude Enterprise plan.
• Usage credits must be turned on for your organization. Your primary owner can turn them on in claude.ai billing settings.



Quick start

List every member's effective monthly spend limit and period-to-date spend:

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



Key concepts



The spend limit hierarchy

An effective spend limit applies to each member's spend, resolved from a hierarchy of scope levels. When a member has no per-user override, they inherit the spend limit configured for their group (if your organization uses group-based limits), their seat tier, or the organization-wide default. A group spend limit is a per-member default: each member inheriting it is gated against their own spend, not a pooled group budget.

Reading GET /v1/organizations/spend_limits/effective returns every current member with their resolved effective spend limit, where that limit was resolved from (source), and their period-to-date spend. Setting a per-user override with POST /v1/organizations/spend_limits pins a member to a specific spend limit regardless of what they would otherwise inherit. Deleting the override returns them to the inherited spend limit (or leaves them unlimited if none exists).

The source field on each member's row tells you which level their spend limit resolved from: user (a per-user override), seat_tier, rbac_group, or organization. Treat scope types as an open set; fall through on unknown values rather than failing.



Period

period is the recurring window over which the spend limit is enforced and spend resets. A spend limit is identified by its (scope, period) pair. Currently monthly is the only supported period; monthly spend resets at 00



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. In a member's effective row, null means unlimited (no spend limit) and "0" means the member cannot use Claude beyond their plan's included usage. On a configured spend-limit row (as returned by GET /v1/organizations/spend_limits/{id}), null only means no numeric spend limit is set; read the member's effective row to distinguish unlimited from included-usage-only.

period_to_date_spend is the member's spend accrued since the start of the current period, in the same minor-unit format; it may include a fractional part (for example, "41280.125"). It may read as "0" if the spend reading is temporarily unavailable; treat it as informational, not transactional.



Increase request lifecycle

A spend limit increase request is created when a member clicks "request more usage" in claude.ai. Requests are not created through this API. A request's status is one of:

Both approved and denied are terminal. A member has at most one pending request at a time.

Approving with POST /v1/organizations/spend_limit_increase_requests/{id}/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).



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.

Do not change query parameters mid-sequence. Cursors are bound to the filters that issued them. If you change user_ids[], period[], status[], or actor_ids[] and pass an old cursor, you'll get a 400 with "cursor does not match current query parameters". Start a new sequence from the first page instead.



Serializing list parameters

List parameters use bracket notation: repeat the parameter name with [] for each value.

user_ids[]=user_01AbCdEfGh&user_ids[]=user_01JkLmNoPq



Error responses

Error responses follow the standard shape documented in Errors. Quote the request_id from the response body when contacting support.



Spend limits



List each member's effective spend limit

GET /v1/organizations/spend_limits/effective returns one row per current member, reflecting each member's effective spend limit, its source in the scope hierarchy, and their period_to_date_spend. Requires the read:spend_limits scope.

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_..."
}



Get a single spend limit

GET /v1/organizations/spend_limits/{spend_limit_id} returns one configured spend limit by ID. Use it to inspect the row that a spend_limit_id field referenced. Requires the read:spend_limits scope.

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



Set a per-user override

POST /v1/organizations/spend_limits sets a per-user spend limit override. This is an upsert keyed on (scope, period): setting a limit for a user and period that already has one overwrites it in place. This endpoint accepts only scope.type: "user"; seat-tier, group, and organization-level defaults are configured in claude.ai settings. Requires the write:spend_limits scope.

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



Remove a per-user override

DELETE /v1/organizations/spend_limits/{spend_limit_id} removes a per-user override, after which the member falls back to any inherited seat-tier, group, or organization default. Seat-tier, group, and organization-level rows cannot be deleted through this endpoint. Requires the write:spend_limits scope.

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



Spend limit increase requests



List increase requests

GET /v1/organizations/spend_limit_increase_requests lists requests, most recent first. Filter by status[] (pending, approved, denied) and actor_ids[]. The list excludes requests whose requester is no longer a member of the organization. Requires the read:spend_limits scope.

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

Each pending request carries a live spend_summary showing the requester's current effective spend limit and period-to-date spend, enough to decide without a separate lookup.



Get a single increase request

GET /v1/organizations/spend_limit_increase_requests/{id} returns one request by ID. Requires the read:spend_limits scope.

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



Approve an increase request

POST /v1/organizations/spend_limit_increase_requests/{id}/approve approves a pending request: it writes a per-user spend limit at the admin-supplied amount for the requester and transitions the request to approved. The request does not carry a requested amount; you supply the new spend limit on approval. Requires the write:spend_limits scope.

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



Deny an increase request

POST /v1/organizations/spend_limit_increase_requests/{id}/deny denies a pending request. Idempotent on denied: denying an already-denied request returns 200 with the existing resource. The endpoint rejects an attempt to deny an already-approved request so automation can distinguish a retry from a conflicting decision. Requires the write:spend_limits scope.

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



Frequently asked questions



Does setting a spend limit directly resolve a member's pending increase request?

No. POST /v1/organizations/spend_limits writes the override but leaves the pending request untouched. Use POST /v1/organizations/spend_limit_increase_requests/{id}/approve to resolve the request and write the override in one call.



What happens when I delete a per-user override?

The member falls back to whatever they'd inherit from the hierarchy: their group, seat-tier, or organization default. If no default exists at any level, the member is unlimited.



Can I set a seat-tier or organization-wide default through this API?

No. Only per-user overrides can be written through this API. Seat-tier, group, and organization-level defaults are configured in claude.ai Organization settings.



Why does period_to_date_spend sometimes read as "0" for an active member?

The spend reading can be temporarily unavailable, in which case the field reads "0" rather than erroring. Treat it as informational.



See also