# Limits & plans

> Plan limits for operations, agents working at once, spaces, active runs and tasks, request rate, payload size and retention, plus per-space limits and hard API bounds.

Source: https://docs.getrunstate.com/limits/

## Plans

Every limit in this table is counted across the whole organization, not per space, so splitting work into more spaces never buys more capacity. During the developer preview, new organizations start on the Free plan. There is no self-serve upgrade yet; talk to us to change plans.

| | Free | Builder | Team | Scale | Enterprise |
| --- | --- | --- | --- | --- | --- |
| Operations per month | 100,000 (hard stop) | 2,000,000 | 15,000,000 | 100,000,000 | custom |
| Agents working at once | 10 | 100 | 1,000 | 5,000 | custom |
| Spaces | 2 | 10 | unlimited | unlimited | custom |
| Active runs | 200 | 1,000 | 10,000 | 50,000 | custom |
| Active tasks (pending or running) | 1,000 | 10,000 | 100,000 | 500,000 | custom |
| API keys (not revoked) | 10 | 25 | 100 | 500 | custom |
| Requests per minute (whole organization) | 600 | 1,500 | 3,000 | 20,000 | custom |
| Payload size per message | 64 KiB | 64 KiB | 64 KiB | 64 KiB | 64 KiB |
| Data retention | 7 days | 14 days | 30 days | 90 days | custom |

Organizations created before plans existed are on a legacy Preview plan: 3 spaces, 200 active runs, 1,000 active tasks, 10 keys, 600 requests per minute, 64 KiB payloads, 7-day retention, and no cap on operations or agents working at once.

### Operations

An operation is a successful call that changes state: claiming, releasing, sending, receiving a message, completing, submitting, acquiring and so on. These are never counted:

- lease renewals,
- reads (status, lists, events, watch, diagnostics),
- polls that return nothing,
- failed calls,
- idempotent replays of work that already happened.

On the Free plan, new work is refused with `OPERATIONS_EXHAUSTED` once the month's operations are used; work already running can still finish. Paid plans are tracked, not blocked.

### Agents working at once

This counts live leases across the organization: held claims, received messages being worked on and held pool units. It's a soft limit (counts are cached briefly), so treat it as "about" the number shown. Going over returns `CONCURRENCY_LIMITED`; waiting claim and pool acquisitions retry it automatically.

### Request rate

Two limits apply to every request, and a request has to pass both:

- **Organization.** The plan's requests per minute are one shared count for the whole organization, across all its spaces and keys. Going over returns `SERVICE_RATE_LIMITED` until the next minute. 20% of that capacity is reserved for recovery calls (renew, release, retry, complete, cancel, detach, ack), so new work can't starve the calls agents use to hand work back.
- **Space.** Each space also has a `requestsPerMinute` limit, which returns `RATE_LIMITED`. Unless you set it, it follows the plan's rate. It exists so you can hold one space below the organization's rate, for example so a noisy test space can't use up the requests production needs; it can't be set above the plan. The same 20% recovery reserve applies within the space. It's enforced by each API server separately, so treat it as approximate. See [per-space limits](#per-space-limits).

Two kinds of request are given back to both counts once they finish, so keeping held work alive and idle workers waiting don't use up the rate: successful lease renewals (claims, deliveries and pool units), and receives (`receive`, `admit`) that long-polled with `waitMs` of at least 1,000 and came back empty. They still count while they are in flight, so the limits also cap how many can run at once. An empty receive without a wait is counted like any other request; `consume()` long-polls by default, so an idle worker makes about three requests a minute.

### Retention

Task results, message payloads and finished messages are kept for the plan's retention window. After that a task is tombstoned: its state and reason stay readable and its outcome is cleared. The event journal is kept for the longer of the plan window and 30 days. Audit events are kept for 365 days and usage records for 400 days regardless of plan.

## Per-space limits

Each space also has operational limits, readable with `GET /v1/spaces/{spaceId}/limits` (key permission `usage_read`) and adjustable with `PUT` (key permission `resource_config`):

| Limit | Default | Allowed | Notes |
| --- | --- | --- | --- |
| `requestsPerMinute` | the plan's requests per minute | 1–100,000 | Can't exceed the plan's requests per minute. Exceeding it returns `RATE_LIMITED`. |
| `maxBacklog` | 1,000 | 1–1,000,000 | Queued plus in-progress messages across the space. Exceeding it returns `BACKLOG_FULL`. |
| `maxPayloadBytes` | 65,536 | 1–65,536 | Can't exceed the plan's payload size. |
| `maxLeaseSeconds` | 600 | 5–600 | |
| `maxPendingWaiters` | 10,000 | 1–1,000,000 | |
| `maxArmedTimers` | 10,000 | 1–1,000,000 | |

A space you haven't set `requestsPerMinute` on follows the plan, including after a plan change. Setting it pins the space to that value, and all spaces still share the organization's count. To hold a space below the plan:

```bash
curl -X PUT "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/limits" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"requestsPerMinute": 300, "maxBacklog": 10000}'
```

A value above the plan ceiling returns `ENTITLEMENT_EXCEEDED`. If the organization moves to a plan with a lower rate, pinned values above it are lowered to the new plan's rate.

## API bounds

Fixed bounds enforced on requests:

| What | Bound |
| --- | --- |
| Claim key, task key, `workKey`, usage key | 1–512 characters |
| Lease length (`leaseSeconds`) | 5–600 seconds, default 30 |
| Child runs per run (`childLimit`) | 1–10,000, default 1,000 |
| Work queue backlog (`backlogLimit` on create) | 1–100,000, default 1,000 |
| Requirements per task | up to 4 pools and 4 quotas |
| Members per task group | 100 |
| Task group `threshold` | 1–1,000 |
| Quota cooldown | 1–3,600 seconds |
| Quota waiter time-to-live | 5–3,600 seconds |
| Budget currency / scale | 3 letters / 0–9 decimal places |
| Budget amounts | up to 18 digits in minor units |
| Events page (`limit`) | up to 500, default 100 |
| Watch hold (`waitSeconds`) | 0–30 seconds |
| Receive long poll (`waitMs` on receive and admit) | up to 30,000 ms (longer values are shortened) |
| `Idempotency-Key` replay window | 24 hours |
| Queue attempts before a task fails | 5 |

## Service status

The hosted service is a developer preview in a single EU region, without an SLA.