# List analyses

> A windowed model analysis. Additional measurements appear as Measurement-valued fields.

`GET https://api.cymatics.tech/v1/analyses`

Scope: `results:read`

## Request

Send your key as `Authorization: Bearer cym_test_…`. Requires the `results:read` scope. Test keys read the simulator; live keys read your paired Cymos.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `room_id` | query | `string` | No | Room id |
| `person_id` | query | `string` | No | Person id |
| `track_id` | query | `string` | No | Track id |
| `from` | query | `string (date-time)` | No | From |
| `to` | query | `string (date-time)` | No | To |
| `limit` | query | `integer, ≥ 1 and ≤ 1000` | No | Limit |
| `cursor` | query | `string` | No | Cursor |
| `kind` | query | `string` | No | Kind |

## Response

`200 · application/json`

```json
{
  "data": [
    {
      "object": "analysis",
      "id": "ana_01",
      "kind": "sleep",
      "status": "processing",
      "track_id": "trk_001",
      "person_id": "person_001",
      "room_id": "room_bedroom",
      "window_start": "2026-10-24T23:55:30.000Z",
      "window_end": "2026-10-24T23:55:30.000Z",
      "timestamp": "2026-10-24T23:55:30.000Z",
      "updated_at": "2026-10-24T23:55:30.000Z",
      "revision": 1
    }
  ],
  "meta": {
    "request_id": "req_01",
    "project_id": "proj_demo",
    "livemode": false,
    "generated_at": "2026-10-24T23:55:30.000Z"
  },
  "page": {
    "has_more": false,
    "next_cursor": "cur_01"
  }
}
```

## Errors

| Status | Description |
| --- | --- |
| `429` | `rate_limit_exceeded`: Too many requests this minute for the key (or twice that across the project), or too many open streams for the project. Retry after the seconds in Retry-After.<br>`quota_exceeded`: A live key's project has used its monthly live-hour cap. There is no Retry-After. Don't retry; raise the live-hour cap in the dashboard. Headers: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset. |
| `503` | `live_unavailable`: This operation has no live data for this project yet (for example, no paired Cymo covers it). Don't retry the same request; pair a Cymo that covers it, or build against a test key.<br>`service_unavailable`: A dependency, such as API key verification, is unreachable, or the project is busy with another write. Retry after the seconds in Retry-After, with backoff. |
| `4XX` | Invalid request, credential, permission or revision. |
| `default` | Error with a stable code and request ID. |

Every error is a `{ error, meta }` envelope with a stable `code`. See [Errors](https://docs.cymatics.tech/errors) for each code and whether to retry.

## Call it

**TypeScript · @cymos/sdk**

```ts
import { Cymo } from "@cymos/sdk";

const cymo = new Cymo({ apiKey: process.env.CYMO_API_KEY! });

const { data, meta } = await cymo.analyses.list({ room_id: "room_bedroom" });
```

**terminal · cymatics CLI**

```sh
$ cymatics analyses list --room-id room_bedroom --json
```

**curl**

```sh
curl "https://api.cymatics.tech/v1/analyses?room_id=room_bedroom" \
  -H "Authorization: Bearer $CYMO_API_KEY"
```

**MCP tool**

```
list_analyses({ room_id: "room_bedroom" })
```

The MCP tool `list_analyses` calls this operation with your key.