Runs (scopes)

Create, inspect, cancel and complete runs. The API calls a run a scope.

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

GET /v1/spaces/{spaceId}/scopes

Read-only scope list for consoles, most recent first.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Scopes

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

POST /scopes

POST /v1/spaces/{spaceId}/scopes

Create a root or child scope.

Key permission: coordination_write
Idempotency-Key header: required
TypeScript SDK: rs.scopes.create(), run.child()
Python SDK: rs.scopes.create(), run.child()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`name`	string	no	length 1–256; Label shown in reads and the console; not unique, never used for lookup
`parentId`	string (uuid)	no
`deadline`	string (date-time)	no
`childLimit`	integer	no	1–10000

Responses

Status	Meaning
`201`	Created scope

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/scopes" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /scopes/{id}

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

Stored and effective scope state.

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

Path parameters

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

Responses

Status	Meaning
`200`	Scope with stored and effective state
`404`	Error envelope `{"error":{"code","message","requestId"}}`

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

POST /scopes/{id}/cancel

POST /v1/spaces/{spaceId}/scopes/{id}/cancel

Terminal cancellation marker.

Key permission: coordination_write
TypeScript SDK: run.cancel()
Python SDK: run.cancel()

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/scopes/<id>/cancel" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /scopes/{id}/complete

POST /v1/spaces/{spaceId}/scopes/{id}/complete

Customer-declared close.

Key permission: coordination_write
TypeScript SDK: run.complete()
Python SDK: run.complete()

Path parameters

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

Responses

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

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