## `GET /sop/instances`

**List all instances** — Returns a paginated list of instances across all processes. Filter by process name or state to narrow results.

> **Auth:** Requires `X-SOP-Token` header. See [Authentication](/api-docs/guides/authentication.md).

### Query parameters

- `process` (string, optional) — Filter to a specific process name.
- `state` (enum, optional) — One of: `pending`, `running`, `completed`, `failed`, `cancelled`.

### Response

`200 application/json` — Paginated list of instance objects.

```json
[
  {
    "id":         "01HXYZ...",
    "process":    "customer-onboarding",
    "state":      "running",
    "started_at": "2024-01-15T10:30:00Z"
  }
]
```

### Errors

| Status | Code | Meaning |
|--------|------|---------|
| 401 | `unauthorized` | Token missing or revoked. |

### Code examples

#### curl

```bash
curl "https://api.opensop.dev/sop/instances?state=running" \
  -H "X-SOP-Token: $OPENSOP_TOKEN"
```

#### Node

```js
const res = await fetch(
  "https://api.opensop.dev/sop/instances?state=running",
  { headers: { "X-SOP-Token": process.env.OPENSOP_TOKEN } }
);
```

#### Python

```python
resp = requests.get(
  "https://api.opensop.dev/sop/instances",
  params={"state": "running"},
  headers={"X-SOP-Token": os.environ["OPENSOP_TOKEN"]}
)
```

#### Ruby

```ruby
Net::HTTP.start("api.opensop.dev", use_ssl: true) do |h|
  req = Net::HTTP::Get.new("/sop/instances?state=running")
  req["X-SOP-Token"] = ENV["OPENSOP_TOKEN"]
  puts h.request(req).body
end
```