Timers

Durable wakeups.

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

GET /v1/spaces/{spaceId}/timers

Read-only timer list with optional state filter.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Timers

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

POST /timers

POST /v1/spaces/{spaceId}/timers

Arm a durable wakeup.

Key permission: coordination_write
Idempotency-Key header: required

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	yes
`at`	string (date-time)	no
`afterSeconds`	integer	no	min 0

Responses

Status	Meaning
`201`	Timer id and fireAt

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

POST /timers/{id}/ack

POST /v1/spaces/{spaceId}/timers/{id}/ack

Acknowledge firing (idempotent)

Key permission: coordination_write
TypeScript SDK: runstate.sleep()
Python SDK: runstate.sleep()

Path parameters

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

Request body (JSON)

Field	Type	Required	Notes
`token`	string	yes

Responses

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

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

POST /timers/{id}/cancel

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

Disarm before firing.

Key permission: coordination_write

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

POST /timers/poll

POST /v1/spaces/{spaceId}/timers/poll

Pull-mode firing for customers without destinations.

Key permission: coordination_write

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	no

Responses

Status	Meaning
`200`	FIRED timers with wakeup tokens

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

PUT /timers/by-name/{name}

PUT /v1/spaces/{spaceId}/timers/by-name/{name}

Get-or-create a named timer in a run.

Returns the existing timer’s fire time and state (with its wakeup token while FIRED) and the database time as now.

Key permission: coordination_write
TypeScript SDK: runstate.sleep(name, duration)
Python SDK: runstate.sleep(name, duration)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`name`	string	length 1–256

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	yes
`at`	string (date-time)	no
`afterSeconds`	integer	no	0–31536000

Responses

Status	Meaning
`200`	Existing timer: {id, name, state, fireAt, token, now, created: false}
`201`	Armed

curl -X PUT "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/timers/by-name/<name>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scopeId":"<run id>"}'