# Diagnostics, usage & limits

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

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

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

```http
GET /v1/spaces/{spaceId}/census
```

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

- **Key permission:** `usage_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

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

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

## GET /backlog

```http
GET /v1/spaces/{spaceId}/backlog
```

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

- **Key permission:** `usage_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

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

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

## GET /ops/waits

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

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

- **Key permission:** `usage_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"}}` |

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

## GET /usage

```http
GET /v1/spaces/{spaceId}/usage
```

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

- **Key permission:** `usage_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

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

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

## GET /limits

```http
GET /v1/spaces/{spaceId}/limits
```

Effective per-space limits (kernel defaults when unset; requestsPerMinute follows the organization's plan when unset)

- **Key permission:** `usage_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Limits |

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

## PUT /limits

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

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

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

Diagnostic run view across primitives for a scope subtree.

- **Key permission:** `usage_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"}}` |

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