# Timers

> Durable wakeups.

Source: https://docs.getrunstate.com/api/timers/

<!-- Generated by apps/docs/scripts/gen-api.mjs from packages/contracts/openapi.yaml. Do not edit. -->

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

## GET /timers

```http
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 |

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

## POST /timers

```http
POST /v1/spaces/{spaceId}/timers
```

Arm a durable wakeup.

- **Key permission:** `coordination_write`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `run.timers.create()`
- **Python SDK:** `run.timers.create()`

**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 |

```bash
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

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

Acknowledge firing (idempotent)

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `timer.wait() (acks when fired)`
- **Python SDK:** `timer.wait() (acks when fired)`

**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"}}` |

```bash
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

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

Disarm before firing.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `timer.cancel()`
- **Python SDK:** `timer.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"}}` |

```bash
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

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

Pull-mode firing for customers without destinations.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `timer.wait()`
- **Python SDK:** `timer.wait()`

**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 |

```bash
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 '{}'
```