# Runs (scopes)

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

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

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

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

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

## POST /scopes

```http
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 |
| --- | --- | --- | --- |
| `parentId` | string (uuid) | no |  |
| `deadline` | string (date-time) | no |  |
| `childLimit` | integer | no | 1–10000 |

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Created scope |

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

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

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

## POST /scopes/{id}/cancel

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

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

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

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