# Operations

Mutating environment endpoints return `202 Accepted` with an operation record.
Poll this endpoint until the operation reaches a terminal state.

## Endpoint

### GET /v1/operations/{operation_id}

Read an operation's current state.

**Headers required:** `X-Scribase-Organization-ID: <org-id>`

**Response `200 OK`:**

```json
{
  "id": "op-01J...",
  "kind": "create_environment",
  "state": "running",
  "organization_id": "acme",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:05Z",
  "result": null,
  "error": null
}
```

## Operation states

| State | Terminal | Description |
|---|---|---|
| `pending` | No | Queued, not yet started |
| `running` | No | In progress |
| `succeeded` | Yes | Completed successfully |
| `failed` | Yes | Completed with an error |

## Operation kinds

| Kind | Triggered by |
|---|---|
| `create_environment` | `POST /v1/environments` |
| `delete_environment` | `DELETE .../environments/{env}` |
| `suspend_environment` | `POST .../environments/{env}/suspend` |
| `resume_environment` | `POST .../environments/{env}/resume` |
| `run_migrations` | `POST .../environments/{env}/migrations` with `apply: true` |
| `import` | `POST /v1/imports` |

## Polling

```sh
scribase operation get acme op-01J...
```

Poll every few seconds until `state` is `succeeded` or `failed`. The SDK's
`operations.wait()` handles polling automatically:

```ts
const { operation } = await scribase.environments.create({ ... });
const result = await scribase.operations.wait(operation.id, 'acme');
```

## Error details

When `state` is `failed`, the `error` field carries a human-readable reason:

```json
{
  "id": "op_01J...",
  "kind": "create_environment",
  "state": "failed",
  "attempt_count": 3,
  "error": "provider rejected the environment: region us-east is at capacity"
}
```

Errors returned by the request itself (as opposed to a failed operation) use
the Problem Details format described in the [API overview](https://docs.scribase.com/docs/api.md).

## CLI

```sh
scribase operation get acme op-01J...
```