Shared quotas (allowances)

Fixed-window shared quotas with durable FIFO waiting. The API calls them allowances.

All paths are relative to the API base URL (https://api.getrunstate.com) and require Authorization: Bearer <api key>. See the API overview for authentication, idempotency and the error envelope.

GET /allowances

GET /v1/spaces/{spaceId}/allowances

Read-only allowance list with current-window balances.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Allowances

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /allowances

POST /v1/spaces/{spaceId}/allowances

Configure a shared quota (fixed-window consumable units)

Key permission: resource_config
Idempotency-Key header: required
TypeScript SDK: rs.quotas.ensure()
Python SDK: rs.quotas.ensure()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`name`	string	yes
`unitsLimit`	integer	yes	min 1
`windowSeconds`	integer	yes	min 1

Responses

Status	Meaning
`201`	Created allowance
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","unitsLimit":1,"windowSeconds":1}'

GET /allowances/{id}

GET /v1/spaces/{spaceId}/allowances/{id}

Current-window balance and cooldown for one allowance.

Key permission: coordination_read
TypeScript SDK: quota.status()
Python SDK: quota.status()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Responses

Status	Meaning
`200`	Allowance status
`404`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances/<id>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /allowances/{id}/consume

POST /v1/spaces/{spaceId}/allowances/{id}/consume

Consume window units now (work_key dedup applies)

Key permission: resource_config
Idempotency-Key header: required
TypeScript SDK: run.quota(name).tryTake() / .take()
Python SDK: run.quota(name).try_take() / .take()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	yes
`units`	integer	yes	min 1
`holder`	string	yes
`workKey`	string	no	length 1–512

Responses

Status	Meaning
`201`	Consumption recorded
`429`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances/<id>/consume" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","units":1,"holder":"worker-1"}'

POST /allowances/{id}/wait

POST /v1/spaces/{spaceId}/allowances/{id}/wait

Enqueue durably for units; strict FIFO, head-of-line blocking.

Key permission: resource_config
Idempotency-Key header: required
TypeScript SDK: quota.take() (when the window is exhausted)
Python SDK: quota.take() (when the window is exhausted)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	yes
`units`	integer	yes	min 1
`holder`	string	yes
`ttlSeconds`	integer	no	5–3600

Responses

Status	Meaning
`201`	waiterId and state (GRANTED on fast path)

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances/<id>/wait" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>","units":1,"holder":"worker-1"}'

POST /allowances/{id}/cooldown

POST /v1/spaces/{spaceId}/allowances/{id}/cooldown

Provider-reported backoff; blocks consumption and grants until expiry.

Key permission: resource_config
TypeScript SDK: quota.cooldown()
Python SDK: quota.cooldown()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`seconds`	integer	yes	1–3600
`reason`	string	no	max length 512

Responses

Status	Meaning
`200`	cooldownUntil
`404`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowances/<id>/cooldown" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"seconds":1}'

GET /allowance-waiters/{id}

GET /v1/spaces/{spaceId}/allowance-waiters/{id}

Durable allowance waiter state.

Key permission: coordination_read
TypeScript SDK: quota.take() (polls its waiter)
Python SDK: quota.take() (polls its waiter)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Responses

Status	Meaning
`200`	Waiter
`404`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowance-waiters/<id>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /allowance-waiters/{id}/cancel

POST /v1/spaces/{spaceId}/allowance-waiters/{id}/cancel

Cancel a WAITING allowance waiter (cleanup, ungated)

Key permission: coordination_write
TypeScript SDK: quota.take() (on timeout, best effort)
Python SDK: quota.take() (on timeout, best effort)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Responses

Status	Meaning
`200`	CANCELLED
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/allowance-waiters/<id>/cancel" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"