Diagnostics, usage & limits

Read-only diagnostic views, usage counters and per-space limits.

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 /census

GET /v1/spaces/{spaceId}/census

Aggregate counts by state across scopes, claims, timers, messages, waiters, barriers.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

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

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

GET /backlog

GET /v1/spaces/{spaceId}/backlog

Queued or stuck work: outbox by state, ready messages, waiting waiters, armed timers.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

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

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

GET /ops/waits

GET /v1/spaces/{spaceId}/ops/waits

What each waiting task and held resource is waiting on: waiters, held grants, held claims.

Key permission: coordination_read
TypeScript SDK: rs.diagnostics.waits()
Python SDK: rs.diagnostics.waits()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

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

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

GET /usage

GET /v1/spaces/{spaceId}/usage

Per-day syscall counts and retained bytes (from/to as YYYY-MM-DD)

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Usage rows
`400`	Error envelope `{"error":{"code","message","requestId"}}`

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

GET /limits

GET /v1/spaces/{spaceId}/limits

Effective per-space limits (kernel defaults when unset)

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Limits

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

PUT /limits

PUT /v1/spaces/{spaceId}/limits

Upsert per-space limits.

Key permission: resource_config
Idempotency-Key header: required

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

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

curl -X PUT "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/limits" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

GET /ops/runs/{scopeId}

GET /v1/spaces/{spaceId}/ops/runs/{scopeId}

Diagnostic run view across primitives for a scope subtree.

Key permission: coordination_read
TypeScript SDK: rs.diagnostics.run(), rs.diagnostics.workers()
Python SDK: rs.diagnostics.run(), rs.diagnostics.workers()

Path parameters

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

Responses

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

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/ops/runs/<scopeId>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"