# Limits

Canonical HTML: https://anchorshell.com/docs/limits

Control requests, tokens, spending, and concurrency without confusing resource limits with individual budgets.

Last updated: 2026-09-17

Limits define how much capacity Relay may use. Provider/model limits protect shared resources; hosted user and API-key policies restrict a particular person or workload. Applicable limits combine—the tightest boundary wins.

Requests may wait for capacity within the Group's wait budget. Spend limits use configured pricing, not a provider invoice. Request pacing spreads eligible short-window requests rather than releasing a burst.

## Dashboard

1. Open **Limits** and choose the provider/model, user, or API-key section.
2. Add a policy. Choose its target, metric, time window, value, and enabled state.
3. Save, then inspect remaining capacity and reset times while requests run.

Provider/resource limits are available when self-hosting. Hosted individual budgets support requests, tokens, and spend, targeted globally or to a provider/model. User limits cover that user's browser and key traffic; exact-key limits cover only that key.

## API

Use a key with the relevant permissions; see [API authentication](https://anchorshell.com/docs/api). Replace placeholders with IDs from the corresponding list or create response.

Shared policy reads require `relay:limits:read:organization`; mutations require `relay:limits:manage`. Individual reads respect self/organization visibility.

### List resource policies

```bash
curl 'https://api.anchorshell.com/api/relay/limit-policies' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
[
  {
    "id": "<POLICY_ID>",
    "scope_type": "global",
    "metric": "requests",
    "period": "minute",
    "limit_value": 60,
    "enabled": true
  }
]
```

### Create a resource policy

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/limit-policies' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scope_type": "global",
  "metric": "requests",
  "period": "minute",
  "limit_value": 60,
  "enabled": true
}'
```

**Response — 201 Created**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<POLICY_ID>",
  "scope_type": "global",
  "metric": "requests",
  "period": "minute",
  "limit_value": 60,
  "enabled": true
}
```

### Update a resource policy

```bash
curl -X PUT 'https://api.anchorshell.com/api/relay/limit-policies/<POLICY_ID>' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "scope_type": "global",
  "metric": "requests",
  "period": "minute",
  "limit_value": 120,
  "enabled": true
}'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "id": "<POLICY_ID>",
  "scope_type": "global",
  "metric": "requests",
  "period": "minute",
  "limit_value": 120,
  "enabled": true
}
```

### Delete a resource policy

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/limit-policies/<POLICY_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 204 No Content**

No response body.

### List hosted user policies

```bash
curl 'https://api.anchorshell.com/api/relay/pro/user-limit-policies' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "policies": [
    {
      "id": "<POLICY_ID>",
      "limit_uuid": "<POLICY_ID>",
      "user_uuid": "<MEMBER_ID>",
      "target_type": "global",
      "metric": "tokens",
      "period": "day",
      "limit_value": 100000,
      "enabled": true
    }
  ]
}
```

### Create a user budget

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/pro/user-limit-policies' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_uuid": "<MEMBER_ID>",
  "target_type": "global",
  "metric": "tokens",
  "period": "day",
  "limit_value": 100000,
  "enabled": true
}'
```

**Response — 200 OK**

No policy ID is returned. List policies to obtain its limit_uuid.

```json
{
  "ok": true
}
```

User-policy writes use POST upsert: include the `limit_uuid` from the policy list to update that policy.

### Update a user budget

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/pro/user-limit-policies' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "limit_uuid": "<POLICY_ID>",
  "user_uuid": "<MEMBER_ID>",
  "target_type": "global",
  "metric": "tokens",
  "period": "day",
  "limit_value": 200000,
  "enabled": true
}'
```

**Response — 200 OK**

No policy ID is returned. List policies to obtain its limit_uuid.

```json
{
  "ok": true
}
```

### Delete a user budget

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/pro/user-limit-policies?limit_uuid=<POLICY_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

The policy was removed.

```json
{
  "ok": true
}
```

### List hosted API-key policies

```bash
curl 'https://api.anchorshell.com/api/relay/api-key-limit-policies' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

Selected response fields shown; IDs and values are illustrative.

```json
{
  "policies": [
    {
      "id": "<POLICY_ID>",
      "limit_uuid": "<POLICY_ID>",
      "api_key_uuid": "<API_KEY_ID>",
      "owner_user_uuid": "<MEMBER_ID>",
      "target_type": "global",
      "metric": "requests",
      "period": "day",
      "limit_value": 2000,
      "enabled": true
    }
  ]
}
```

### Create an API-key budget

```bash
curl -X POST 'https://api.anchorshell.com/api/relay/api-key-limit-policies' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "api_key_uuid": "<API_KEY_ID>",
  "target_type": "global",
  "metric": "requests",
  "period": "day",
  "limit_value": 2000,
  "enabled": true
}'
```

**Response — 200 OK**

No policy ID is returned. List policies to obtain its limit_uuid.

```json
{
  "ok": true
}
```

To update an exact-key policy, POST its `limit_uuid` from the policy list with the same key/target/metric/window and the new value.

### Delete an API-key budget

```bash
curl -X DELETE 'https://api.anchorshell.com/api/relay/api-key-limit-policies?limit_uuid=<POLICY_ID>' \
  -H 'Authorization: Bearer <API_KEY>'
```

**Response — 200 OK**

The policy was removed.

```json
{
  "ok": true
}
```

Use the public key ID, never its secret, in policy bodies. Replacing a key creates a new ID; its old policy does not automatically transfer.

## Next

[Usage](https://anchorshell.com/docs/usage).