---
title: "Put User Usage Limits"
method: PUT
path: "/v2/users/{user_id}/usage-limits"
tags: ["usage-limits"]
---

# Put User Usage Limits

`PUT /v2/users/{user_id}/usage-limits`

## Request

- Base URL: `https://api.getauctor.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getauctor.com/v2/users/{user_id}/usage-limits`
- Auth: none declared

Replace the spend caps for one member of your organization. The body is the full desired state for both periods: caps you include are created or updated, and caps you omit are removed. Both `monthly` and `daily` are required, so a body that leaves one out is rejected rather than treated as a partial update. Send `{"monthly": {}, "daily": {}}` to clear every cap for the user. The response is the resulting state, in the same form `GET` returns.

Rules, identical to the Settings → Usage editor:

- `model_key` must be a canonical ledger model key (lowercase, no provider prefix), e.g. `claude-sonnet-4`.
- Within a period, a per-model cap cannot exceed that period's overall `limit_amount` when one is set.
- At most 50 per-model caps per period, with no duplicate model keys.
- Amounts are nonnegative and support at most 4 decimal places.

Each created, changed, or removed cap is recorded in the audit log as `usage_policy.created`, `usage_policy.updated`, or `usage_policy.deleted`, attributed to the API key or OAuth client that made the call. Caps that were sent unchanged are not re-recorded.

API keys are not scoped: any key for your organization can raise, lower, or remove any member's caps, exactly as an administrator can in Settings. Treat keys that call this endpoint accordingly.

Returns `404` if the user is not an active member of your organization, `409` if the body sets a cap while your organization has no billing profile yet (caps are denominated in the billing currency; a body that only clears caps succeeds), `400` when the body breaks one of the rules above, and `500` with `Failed to record audit trail.` if the audit trail for the change could not be written (the limits were not changed).

## Path parameters

- `user_id` string, required: ID of the organization member whose limits to read or replace.

## Request body

- UsageLimitsPutRequest
  - `monthly` PeriodLimits, required
    - `limit_amount` number, nullable: Overall spend cap for the period across all models. `null` removes the cap.
    - `model_limits` ModelLimit[]: Per-model caps for the period (at most 50). Each cap must not exceed `limit_amount` when one is set.
      - `model_key` string, required: Canonical ledger model key, e.g. `claude-sonnet-4`. Provider prefixes (`anthropic/`, `openai:`) and mixed case are rejected. Surrounding whitespace is trimmed.
      - `limit_amount` number, required: Spend cap for this model in the organization billing currency.
  - `daily` PeriodLimits, required
    - `limit_amount` number, nullable: Overall spend cap for the period across all models. `null` removes the cap.
    - `model_limits` ModelLimit[]: Per-model caps for the period (at most 50). Each cap must not exceed `limit_amount` when one is set.
      - `model_key` string, required: Canonical ledger model key, e.g. `claude-sonnet-4`. Provider prefixes (`anthropic/`, `openai:`) and mixed case are rejected. Surrounding whitespace is trimmed.
      - `limit_amount` number, required: Spend cap for this model in the organization billing currency.

## Response `200`

Successful Response

- UsageLimitsResponse
  - `user_id` string, required
  - `currency` string, nullable, required: Organization billing currency the amounts are denominated in; `null` when no caps are set.
  - `monthly` PeriodLimitsResponse, required
    - `limit_amount` number, nullable: Overall spend cap for the period across all models; `null` when unset.
    - `model_limits` ModelLimit[]: Per-model caps for the period.
      - `model_key` string, required: Canonical ledger model key, e.g. `claude-sonnet-4`. Provider prefixes (`anthropic/`, `openai:`) and mixed case are rejected. Surrounding whitespace is trimmed.
      - `limit_amount` number, required: Spend cap for this model in the organization billing currency.
  - `daily` PeriodLimitsResponse, required
    - `limit_amount` number, nullable: Overall spend cap for the period across all models; `null` when unset.
    - `model_limits` ModelLimit[]: Per-model caps for the period.
      - `model_key` string, required: Canonical ledger model key, e.g. `claude-sonnet-4`. Provider prefixes (`anthropic/`, `openai:`) and mixed case are rejected. Surrounding whitespace is trimmed.
      - `limit_amount` number, required: Spend cap for this model in the organization billing currency.

## Other responses

- `400`: The request body fails the usage-limit rules. Schema failures (missing period, non-number amount, too many decimals, model cap above the overall cap) return the `error`/`details`/`fields` body; noncanonical model keys return `detail`.
- `404`: User is not an active member of your organization.
- `409`: The body sets a cap but your organization has no billing profile yet.
- `422`: Validation Error
- `500`: The audit trail for the change could not be written; the limits were not changed.

## Changes

- **2026-09-16** `f1aa066f4c84`: 1 info
  - added the non-success response with the status `500`
- **2026-09-16** `6ebc99fb362b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getauctor/apis/getauctor-api/changes/v2/users/:user_id/usage-limits/put.md)

---

[API](https://skmtc.dev/getauctor/apis/getauctor-api.md) - [All operations](https://skmtc.dev/getauctor/apis/getauctor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getauctor/apis/getauctor-api/revisions/be39c59c13f6?raw)