spend-limits-api changedmanage-claude/spend-limits-api
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+36added
Lines−36removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits15to this page, all time
### List each member’s effective spend limit ### Temporarily raise a member’s spend limit during an incident ### Does setting a spend limit directly resolve a member’s pending increase request? ### List each member's effective spend limit ### Temporarily raise a member's spend limit during an incident ### Does setting a spend limit directly resolve a member's pending increase request?
The whole hunk
from line 4, old and new numbered
/
from line 4
44description: 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.
55---
66
7The 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.
7The 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.
88
99For per-user and time-bucketed usage and cost *reporting*, see [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api).
1010
from line 24
2424
2525| Resource | Endpoints | Use for |
2626| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
27| **Spend limits** | `GET /v1/organizations/spend_limits/effective`<br />`GET /v1/organizations/spend_limits/{spend_limit_id}`<br />`POST /v1/organizations/spend_limits`<br />`DELETE /v1/organizations/spend_limits/{spend_limit_id}` | Read each member's effective spend limit and period-to-date spend; set or clear a per-user override. |
28| **Spend limit increase requests** | `GET /v1/organizations/spend_limit_increase_requests`<br />`GET /v1/organizations/spend_limit_increase_requests/{id}`<br />`POST /v1/organizations/spend_limit_increase_requests/{id}/approve`<br />`POST /v1/organizations/spend_limit_increase_requests/{id}/deny` | List members' requests for a higher spend limit, with the context needed to decide; approve or deny each request. |
27| **Spend limits** | `GET /v1/organizations/spend_limits/effective`<br />`GET /v1/organizations/spend_limits/{spend_limit_id}`<br />`POST /v1/organizations/spend_limits`<br />`DELETE /v1/organizations/spend_limits/{spend_limit_id}` | Read each member’s effective spend limit and period-to-date spend; set or clear a per-user override. |
28| **Spend limit increase requests** | `GET /v1/organizations/spend_limit_increase_requests`<br />`GET /v1/organizations/spend_limit_increase_requests/{id}`<br />`POST /v1/organizations/spend_limit_increase_requests/{id}/approve`<br />`POST /v1/organizations/spend_limit_increase_requests/{id}/deny` | List members’ requests for a higher spend limit, with the context needed to decide; approve or deny each request. |
2929
30Use 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.
30Use 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.
3131
3232## Prerequisites
3333
from line 38
3838
3939## Quick start
4040
41List every member's effective monthly spend limit and period-to-date spend:
41List every member’s effective monthly spend limit and period-to-date spend:
4242
4343<CodeGroup>
4444 ```bash cURL
from line 174
174174
175175### The spend limit hierarchy
176176
177An **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.
177An **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.
178178
179179Reading `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).
180180
181The `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.
181The `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.
182182
183183### Period
184184
from line 186
186186
187187### Amounts and currency
188188
189All 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.
189All 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.
190190
191`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.
191`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.
192192
193`period_to_date_spend` is the member's spend accrued since the start of the current `period`, in the same minor-unit format; it might include a fractional part (for example, `"41280.125"`). It might read as `"0"` if the spend reading is temporarily unavailable; treat it as informational, not transactional.
193`period_to_date_spend` is the member’s spend accrued since the start of the current `period`, in the same minor-unit format; it might include a fractional part (for example, `"41280.125"`). It might read as `"0"` if the spend reading is temporarily unavailable; treat it as informational, not transactional.
194194
195195### Increase request lifecycle
196196
197A **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:
197A **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:
198198
199199| Status | Meaning |
200200| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
201| `pending` | Awaiting admin action. The request normally carries a live `spend_summary` so you can see the member's current effective spend limit and period-to-date spend while deciding; `spend_summary` might be `null` if it could not be computed. |
202| `approved` | The request was resolved with approval: either an admin approved it explicitly, another admin action raised the member's spend limit, or Anthropic support raised a spend limit on the organization's behalf. `spend_summary` is `null`. |
203| `denied` | An admin declined. `spend_summary` is `null`. The member can send a new request right away; only a `pending` request blocks a new one. An admin can still raise the member's spend limit directly at any time. |
201| `pending` | Awaiting admin action. The request normally carries a live `spend_summary` so you can see the member’s current effective spend limit and period-to-date spend while deciding; `spend_summary` might be `null` if it could not be computed. |
202| `approved` | The request was resolved with approval: either an admin approved it explicitly, another admin action raised the member’s spend limit, or Anthropic support raised a spend limit on the organization’s behalf. `spend_summary` is `null`. |
203| `denied` | An admin declined. `spend_summary` is `null`. The member can send a new request right away; only a `pending` request blocks a new one. An admin can still raise the member’s spend limit directly at any time. |
204204
205205Both `approved` and `denied` are terminal. A member has at most one `pending` request at a time.
206206
from line 220
220220
221221`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`.
222222
223**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.
223**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.
224224
225225## Serializing list parameters
226226
from line 236
236236
237237## Spend limits
238238
239### List each member's effective spend limit
239### List each member’s effective spend limit
240240
241`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.
241`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.
242242
243243For complete parameter details and response schemas, see [List effective spend limits](https://platform.claude.com/docs/en/api/beta/organization/spend_limits/effective/list) in the API reference.
244244
from line 843
843843 ```
844844</CodeGroup>
845845
846Each 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.
846Each 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.
847847
848848### Get a single increase request
849849
from line 1187
11871187
11881188Some of these workflows combine the Spend Limits API with the [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) cost endpoints. The Analytics cost endpoints are designed for organization-wide spend reporting across a date range. `GET /spend_limits/effective` returns the cap that currently applies to each member. Start a sweep with Analytics to discover which members to look at, then read their current caps with `/effective`.
11891189
1190Spend Limits endpoints require the `spend_limits` scopes and Analytics cost endpoints require `read:analytics`; see [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) for how to provision access. The examples use one Admin API key that has the scopes of every API they call. A primary owner [selects these scopes when creating the key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#choose-scopes-for-a-claude-enterprise-key). All monetary values on both are decimal strings in minor units (cents). Both APIs paginate with an opaque cursor. Set an explicit `limit` and page through `next_page` until it's `null` to cover the whole organization.
1190Spend Limits endpoints require the `spend_limits` scopes and Analytics cost endpoints require `read:analytics`; see [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) for how to provision access. The examples use one Admin API key that has the scopes of every API they call. A primary owner [selects these scopes when creating the key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#choose-scopes-for-a-claude-enterprise-key). All monetary values on both are decimal strings in minor units (cents). Both APIs paginate with an opaque cursor. Set an explicit `limit` and page through `next_page` until it’s `null` to cover the whole organization.
11911191
11921192### Automate the increase-request review flow
11931193
1194Run a scheduled job that fetches pending requests, applies your organization's approval policy, and resolves each one.
1194Run a scheduled job that fetches pending requests, applies your organization’s approval policy, and resolves each one.
11951195
119611961. List pending requests:
11971197
from line 1307
13071307 ```
13081308 </CodeGroup>
13091309
1310 Each request carries the requester's `actor.user_id` and a live `spend_summary` with their current effective `amount` and `period_to_date_spend`, enough to decide without a separate lookup.
1310 Each request carries the requester’s `actor.user_id` and a live `spend_summary` with their current effective `amount` and `period_to_date_spend`, enough to decide without a separate lookup.
13111311
13122. Apply your policy. For example, auto-approve when the member's current `amount` is below a threshold, and route larger caps for manual review.
13122. Apply your policy. For example, auto-approve when the member’s current `amount` is below a threshold, and route larger caps for manual review.
13131313
131413143. Resolve each request. To approve, supply the new cap:
13151315
from line 1435
14351435
14361436### Identify members close to their spend limit
14371437
1438Find members approaching their cap so you can raise it before they're blocked.
1438Find members approaching their cap so you can raise it before they’re blocked.
14391439
14401. Pull each member's month-to-date spend from the Analytics API (one row for each member, highest spend first by default):
14401. Pull each member’s month-to-date spend from the Analytics API (one row for each member, highest spend first by default):
14411441
14421442 <CodeGroup>
14431443 ```bash cURL
from line 1556
15561556 ```
15571557 </CodeGroup>
15581558
1559 Each row contains `actor.user_id`, `actor.email_address`, and `amount` (the member's spend in cents). Page through `next_page` to cover the whole organization.
1559 Each row contains `actor.user_id`, `actor.email_address`, and `amount` (the member’s spend in cents). Page through `next_page` to cover the whole organization.
15601560
156115612. For the top spenders (or everyone above a dollar threshold), fetch effective caps in batches:
15621562
from line 1854
18541854 ```
18551855 </CodeGroup>
18561856
1857 With `bucket_width` set, each member spans one row for each day with usage. Page through `next_page` to collect every member's full series.
1857 With `bucket_width` set, each member spans one row for each day with usage. Page through `next_page` to collect every member’s full series.
18581858
185918592. Group rows by `actor.user_id`. For each member, sum the most recent 7 days and the prior 7 days. Flag members whose recent week exceeds the prior week by your chosen multiple (for example, three). Recent-day cost is provisional and can be revised upward; for repeatable comparisons, set `ending_at` at or before a previously returned `data_refreshed_at` (see [Data availability and freshness](https://platform.claude.com/docs/en/manage-claude/analytics-api#data-availability-and-freshness)).
18601860
186118613. Act on flagged members: adjust the cap with `POST /v1/organizations/spend_limits`, or contact the member.
18621862
1863### Temporarily raise a member's spend limit during an incident
1863### Temporarily raise a member’s spend limit during an incident
18641864
18651865Give an incident responder room to work while an incident is open: raise their spend cap when the incident starts, and roll it back after the incident closes. Gate the raise on your incident management system, for example, by requiring a live incident ID with the member assigned to it.
18661866
18671. Read the member's current cap, and record it for the rollback:
18671. Read the member’s current cap, and record it for the rollback:
18681868
18691869 <CodeGroup>
18701870 ```bash cURL
from line 2264
22642264
22652265## Frequently asked questions
22662266
2267### Does setting a spend limit directly resolve a member's pending increase request?
2267### Does setting a spend limit directly resolve a member’s pending increase request?
22682268
22692269No. `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.
22702270
22712271### What happens when I delete a per-user override?
22722272
2273The 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.
2273The 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.
22742274
22752275### Can I set a seat-tier or organization-wide default through this API?
22762276
No line in this hunk matches that.