# Sessions and replays

> List sessions, read one session's timeline of events, and get its replay as short-lived links.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/sessions-and-replays/

For agents: Reference of the Sessions and replays endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

A session is one visit by one person. The engine keeps an index of sessions in Postgres and each session's
events as objects in your bucket, so reading a timeline is one read of that session's files.

The session list is complete within 10 minutes of the events. A replay is watchable once its session has been
idle for 2 minutes or has ended. `GET /v1/summary` returns `data_through`, the time up to which everything
has been processed.

Sessions belong to a **person** when your app called `identify()` (`person.id`, and `name` and `email` only if
your app sent them) and, optionally, to the **account** that person belongs to in your app (a team, a company).
Anonymous sessions are first-class: `person` is `null` and the session is still listed, searchable by id and
counted. The people and accounts endpoints on this page show activity per person and per account.

Replay content needs the `replay` scope. A token with only `read` sees that a replay exists
(`has_replay`) and cannot fetch it.

## The session object

**Fields:**

- `id` (string, optional): The session id, 32 hex characters, chosen by the SDK.
- `started_at` (timestamp, optional): The first event.
- `ended_at` (timestamp, optional): The latest event. A session ends after 30 minutes without activity.
- `duration_ms` (integer, optional): From the first event to the latest.
- `person` (object or null, optional): Who it was, if your app identified them. `null` for an anonymous session.
- `person.id` (string): The id your app gave. An opaque string.
- `person.name` (string or null): Only if your app sent it.
- `person.email` (string or null): Only if your app sent it.
- `account` (object or null, optional): The account the person belongs to in your app, if your app sent one.
- `environment` (string, optional)
- `release` (string or null, optional): The release the session ran on.
- `device` (string or null, optional): By viewport width, under 768, under 1024, or wider. One of: `mobile`, `tablet`, `desktop`.
- `browser` (string or null, optional): Name and major version, `Chrome 134`.
- `os` (string or null, optional)
- `locale` (string or null, optional): The page's language.
- `entry_route` (string or null, optional): The first page.
- `routes` (array of string, optional): The pages visited, in order of first visit. Up to 50.
- `page_views` (integer, optional)
- `clicks` (integer, optional)
- `rage_clicks` (integer, optional)
- `dead_clicks` (integer, optional)
- `errors` (integer, optional)
- `requests` (integer, optional)
- `failed_requests` (integer, optional)
- `trouble` (boolean, optional): `true` when the session has an error, a rage click, a dead click or a failed request.
- `has_replay` (boolean, optional): Whether a recording exists and can be played. It turns `false` when the replay passes its retention.
- `url` (URL, optional): The session in the app or the Console.

## The session event object

**Fields:**

- `at` (timestamp, optional): When it happened, to the millisecond.
- `offset_ms` (integer, optional): Milliseconds since the session started.
- `type` (string, optional): What kind of event it is. One of: `page_view`, `page_leave`, `click`, `rage_click`, `dead_click`, `error`, `server_error`, `request`, `vital`, `form_invalid`, `custom`.
- `route` (string or null, optional): The page it happened on.
- `text` (string, optional): The event in plain words, ready to show or to hand to a model.
- `data` (object, optional): The details, by type.
  `click`, `rage_click`, `dead_click`: `selector`, `role`, `label`, `context`, `href`; `count` (rage: clicks in the burst); `waited_ms` (dead: how long nothing happened).
  `request`: `method`, `path`, `status`, `duration_ms`, `code` and `message` (from the error body, failed requests only).
  `error`, `server_error`: `name`, `message`, `source`, `problem_id`.
  `page_view`: `navigation` (`load`, `push`, `replace`, `traverse`), `from`.
  `page_leave`: `duration_ms`, `scroll` (deepest scroll, 0 to 100).
  `vital`: `name`, `value`, `rating`, `selector`, `kind`.
  `form_invalid`: `field`, `context`, `reason`, `selector`.
  `custom`: `name`, `props`.
- `trace_id` (string or null, optional): The trace of a request, or of the request that failed.
- `problem_id` (string or null, optional): The problem an error belongs to.

## The person object

**Fields:**

- `id` (string, optional): The id your app gave with `identify()`.
- `name` (string or null, optional): Only if your app sent it.
- `email` (string or null, optional): Only if your app sent it.
- `account` (object or null, optional): The account the person was last seen in.
- `first_seen` (timestamp, optional)
- `last_seen` (timestamp, optional)
- `sessions` (integer, optional): Sessions in the range.
- `trouble_sessions` (integer, optional): Sessions with trouble in the range.
- `errors` (integer, optional): Errors in the range.

## The account object

**Fields:**

- `id` (string, optional): The id your app gave.
- `name` (string or null, optional): Only if your app sent it.
- `people` (integer, optional): Different people active in the range.
- `sessions` (integer, optional)
- `trouble_sessions` (integer, optional)
- `first_seen` (timestamp, optional)
- `last_seen` (timestamp, optional)
- `always_record` (boolean, optional): Whether an «always record» rule covers this account. Only on a single account.

## List sessions

`GET /v1/sessions` \[Engine, Cloud]

Sessions that started in the time range. A session «with trouble» has at least one error, rage click, dead
click or failed request; the same rule is used everywhere in Sypnia.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Only sessions that started after this moment.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `trouble` (boolean, optional, default `false`): `true` returns only sessions with trouble.
- `person` (string, up to 128 characters, optional): Only sessions of this person (`person.id`, exact).
- `account` (string, up to 128 characters, optional): Only sessions of this account (`account.id`, exact).
- `route` (string, up to 500 characters, optional): Only sessions that visited this page. A full URL is accepted and normalized (`/orders/1042` becomes `/orders/:id`).
- `event` (string, up to 80 characters, optional): Only sessions that sent this custom event (the `name` given to `track()`).
- `device` (string, optional): Only sessions on this kind of device. One of: `mobile`, `tablet`, `desktop`.
- `release` (string, optional): Only sessions on this release version.
- `has_replay` (boolean, optional): `true` returns only sessions that have a replay.
- `sort` (string, optional, default `recent`): `recent` (last activity first), `trouble` (most trouble first) or `longest`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/sessions?trouble=true&route=/checkout&since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "ended_at": "2026-03-12T10:31:58Z",
      "duration_ms": 42000,
      "person": {
        "id": "u_1042",
        "name": "Ada Park",
        "email": "ada@example.com"
      },
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "environment": "production",
      "release": "4f2a91c",
      "device": "desktop",
      "browser": "Chrome 134",
      "os": "macOS",
      "locale": "en-US",
      "entry_route": "/cart",
      "routes": [
        "/cart",
        "/checkout"
      ],
      "page_views": 2,
      "clicks": 7,
      "rage_clicks": 1,
      "dead_clicks": 0,
      "errors": 1,
      "requests": 6,
      "failed_requests": 1,
      "trouble": true,
      "has_replay": true,
      "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQwOTowNDowMloifQ"
}
```

## Get a session

`GET /v1/sessions/{session}` \[Engine, Cloud]

The session, plus `problems`, the problems that happened in it.

**Authentication:** API token (`read`)

**Path parameters:**

- `session` (string, required): The session id, 32 hex characters.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "started_at": "2026-03-12T10:31:16Z",
  "ended_at": "2026-03-12T10:31:58Z",
  "duration_ms": 42000,
  "person": {
    "id": "u_1042",
    "name": "Ada Park",
    "email": "ada@example.com"
  },
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  },
  "environment": "production",
  "release": "4f2a91c",
  "device": "desktop",
  "browser": "Chrome 134",
  "os": "macOS",
  "locale": "en-US",
  "entry_route": "/cart",
  "routes": [
    "/cart",
    "/checkout"
  ],
  "page_views": 2,
  "clicks": 7,
  "rage_clicks": 1,
  "dead_clicks": 0,
  "errors": 1,
  "requests": 6,
  "failed_requests": 1,
  "trouble": true,
  "has_replay": true,
  "url": "https://app.sypnia.com/shop/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "problems": [
    {
      "id": "prb_8f3k2m9x4q7w",
      "slug": "pay-button-does-nothing",
      "status": "open",
      "sentence": "3 people tried to pay today and could not. The Pay button does nothing since yesterday's change.",
      "title": "createPayment answered 400 in POST /api/checkout",
      "occurrences": 1,
      "first_occurrence_at": "2026-03-12T10:31:47Z"
    }
  ],
  "replay": {
    "chunks": 5,
    "bytes": 412380,
    "recorded_from": "2026-03-12T10:31:16Z",
    "recorded_until": "2026-03-12T10:31:58Z",
    "expires_at": "2026-04-11T10:31:58Z"
  }
}
```

**Errors:**

- `404` `not_found`: No session has this id in the project, or it is not processed yet (give it 10 minutes).
- `410` `expired`: The session is older than the project's retention and was deleted.

## Delete a session

`DELETE /v1/sessions/{session}` \[Engine, Cloud]

Deletes the session, its events, its replay and its page snapshots, for good. Counts on problems and
performance numbers stay as they are: they are totals and hold nothing about the person. The session leaves
lists at once; the stored objects are removed within 24 hours.

**Authentication:** API token (`admin`)

**Path parameters:**

- `session` (string, required): The session id, 32 hex characters.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/sessions/c4e1a8f3d7b24c69a0e5d3b1f9c7a5e3" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errors:**

- `404` `not_found`: No session has this id in the project.

## Get a session's timeline

`GET /v1/sessions/{session}/events` \[Engine, Cloud]

The session's events in the order they happened, each with a sentence in plain words (`text`) and its details
(`data`). Requests made by the browser come paired with their server trace (`trace_id`).

Typed input is never in a timeline, because it is never collected: a click on a field is named by the field's
label. Clicks inside a masked element have no label.

Use `notable=true` to get only what matters when reading a failure: page views, clicks, rage and dead clicks,
errors, failed requests, form failures and custom events. Successful requests and vitals are left out.

**Authentication:** API token (`read`)

**Path parameters:**

- `session` (string, required): The session id, 32 hex characters.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `types` (string, optional): Comma-separated event types to return: `page_view`, `page_leave`, `click`, `rage_click`, `dead_click`, `error`, `server_error`, `request`, `vital`, `form_invalid`, `custom`. All by default.
- `notable` (boolean, optional, default `false`): `true` leaves out successful requests, vitals and page leaves.
- `around` (timestamp, optional): An ISO 8601 timestamp. Returns the events around that moment (half of `limit` before, half after) instead of from the start.
- `limit` (integer, 1 to 1,000, optional, default `200`): Most events to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0/events?notable=true" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "at": "2026-03-12T10:31:16.004Z",
      "offset_ms": 0,
      "type": "page_view",
      "route": "/cart",
      "text": "Opened /cart",
      "data": {
        "navigation": "load",
        "from": null
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:28.412Z",
      "offset_ms": 12412,
      "type": "page_view",
      "route": "/checkout",
      "text": "Opened /checkout (from /cart)",
      "data": {
        "navigation": "push",
        "from": "/cart"
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:43.090Z",
      "offset_ms": 27090,
      "type": "click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» in «Your order»",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "href": null
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:45.310Z",
      "offset_ms": 29310,
      "type": "rage_click",
      "route": "/checkout",
      "text": "Clicked button «Pay $64.00» 4 more times",
      "data": {
        "selector": "#pay-button",
        "role": "button",
        "label": "Pay $64.00",
        "context": "Your order",
        "count": 4
      },
      "trace_id": null,
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:47.000Z",
      "offset_ms": 31000,
      "type": "request",
      "route": "/checkout",
      "text": "POST /api/checkout answered 400 amount_required after 3,870 ms",
      "data": {
        "method": "POST",
        "path": "/api/checkout",
        "status": 400,
        "duration_ms": 3870,
        "code": "amount_required",
        "message": "amount is required"
      },
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
      "problem_id": null
    },
    {
      "at": "2026-03-12T10:31:47.004Z",
      "offset_ms": 31004,
      "type": "error",
      "route": "/checkout",
      "text": "ApiError: POST /api/checkout failed with 400 (amount_required)",
      "data": {
        "name": "ApiError",
        "message": "POST /api/checkout failed with 400 (amount_required)",
        "source": "promise"
      },
      "trace_id": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
      "problem_id": "prb_8f3k2m9x4q7w"
    },
    {
      "at": "2026-03-12T10:31:58.230Z",
      "offset_ms": 42230,
      "type": "page_leave",
      "route": "/checkout",
      "text": "Left /checkout after 30 s",
      "data": {
        "duration_ms": 29818,
        "scroll": 100
      },
      "trace_id": null,
      "problem_id": null
    }
  ],
  "omitted": {},
  "next_cursor": null
}
```

**Errors:**

- `404` `not_found`: No session has this id in the project.
- `410` `expired`: The session's events are older than the project's retention.

## Get a session's replay

`GET /v1/sessions/{session}/replay` \[Engine, Cloud]

Returns the recording as a **window** of chunks, each with a link that works for 15 minutes. Your client
downloads the chunks straight from storage, in order, and joins their `events` (rrweb events) to play them.
A recording never passes through the API, because a long one can weigh more than 100 MB.

A window always starts at a chunk that holds a full snapshot of the page, so it can be played from its first
event. By default the window starts at the beginning. Pass `at` to start at the last full snapshot before a
moment, for example an error's time. A window holds as many chunks as fit in `max_bytes`. When
`window.has_more` is `true`, ask again with `from_seq` set to `window.next_seq`.

Links expire. When one does, storage answers `403`: call this endpoint again for fresh links.

`gaps` lists the stretches that were not recorded (the SDK was told to stop, or chunks never arrived), so a
player can show them instead of freezing.

**Authentication:** API token (`replay`)

**Path parameters:**

- `session` (string, required): The session id, 32 hex characters.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `at` (timestamp, optional): An ISO 8601 timestamp inside the session. The window starts at the last full snapshot at or before it.
- `from_seq` (integer, 0 to 719, optional): Start the window at this chunk. Use `window.next_seq` of the previous answer. Not together with `at`.
- `max_bytes` (integer, 1,000,000 to 40,000,000, optional, default `40000000`): Most compressed bytes of chunks in the window.

**Request:**

```bash
curl "https://api.sypnia.com/v1/sessions/8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0/replay?at=2026-03-12T10:31:47Z" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response: A window that starts before the failure (200):**

```json
{
  "available": true,
  "session_id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "duration_ms": 42000,
  "recorded_from": "2026-03-12T10:31:16Z",
  "recorded_until": "2026-03-12T10:31:58Z",
  "mask": 1,
  "total_chunks": 5,
  "total_bytes": 412380,
  "window": {
    "from_seq": 0,
    "to_seq": 4,
    "starts_at": "2026-03-12T10:31:16Z",
    "ends_at": "2026-03-12T10:31:58Z",
    "bytes": 412380,
    "has_more": false,
    "next_seq": null
  },
  "chunks": [
    {
      "seq": 0,
      "starts_at": "2026-03-12T10:31:16Z",
      "ends_at": "2026-03-12T10:31:26Z",
      "bytes": 301204,
      "full": true,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000000.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 1,
      "starts_at": "2026-03-12T10:31:26Z",
      "ends_at": "2026-03-12T10:31:36Z",
      "bytes": 58110,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000001.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 2,
      "starts_at": "2026-03-12T10:31:36Z",
      "ends_at": "2026-03-12T10:31:46Z",
      "bytes": 21930,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000002.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 3,
      "starts_at": "2026-03-12T10:31:46Z",
      "ends_at": "2026-03-12T10:31:56Z",
      "bytes": 24716,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000003.json.gz?X-Amz-Signature=…"
    },
    {
      "seq": 4,
      "starts_at": "2026-03-12T10:31:56Z",
      "ends_at": "2026-03-12T10:31:58Z",
      "bytes": 6420,
      "full": false,
      "url": "https://sypnia-shop.s3.us-east-1.amazonaws.com/prj_5k2m9x4q7w1z/replays/8f3a6c1e…/000004.json.gz?X-Amz-Signature=…"
    }
  ],
  "gaps": [],
  "expires_at": "2026-03-12T10:50:00Z"
}
```

**Response: A session without a replay (200):**

```json
{
  "available": false,
  "reason": "not_recorded",
  "session_id": "2b7d9e4f1a6c4830b5d2f7e9c1a3b5d7",
  "chunks": []
}
```

**Errors:**

- `400` `invalid_request`: `at` and `from_seq` together, or `at` outside the session.
- `403` `forbidden`: The token does not have the `replay` scope.
- `404` `not_found`: No session has this id in the project.

## List people

`GET /v1/people` \[Engine, Cloud]

The people who used your app in the time range, with their activity. A person exists once your app called
`identify()` with an id. Anonymous visitors are not listed here; they are counted in `people` on problems and
in the summary, by device.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `30d`): Only people active after this moment. Counts cover this range.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `account` (string, up to 128 characters, optional): Only people of this account.
- `q` (string, up to 120 characters, optional): Text to find in the id, the name or the e-mail.
- `sort` (string, optional, default `last_seen`): `last_seen`, `sessions` or `trouble` (most sessions with trouble first).
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/people?sort=trouble&since=7d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "active": 412,
  "data": [
    {
      "id": "u_1042",
      "name": "Ada Park",
      "email": "ada@example.com",
      "account": {
        "id": "acc_77",
        "name": "Corner Café"
      },
      "first_seen": "2026-02-18T16:02:11Z",
      "last_seen": "2026-03-12T10:31:58Z",
      "sessions": 6,
      "trouble_sessions": 1,
      "errors": 1
    },
    {
      "id": "u_0977",
      "name": null,
      "email": null,
      "account": null,
      "first_seen": "2026-03-01T11:45:09Z",
      "last_seen": "2026-03-12T09:49:02Z",
      "sessions": 3,
      "trouble_sessions": 1,
      "errors": 2
    }
  ],
  "next_cursor": "eyJvIjoyfQ"
}
```

## Get a person

`GET /v1/people/{person_id}` \[Engine, Cloud]

One person with their activity in the range and their five latest sessions. For all of them, list sessions with `person`.

**Authentication:** API token (`read`)

**Path parameters:**

- `person_id` (string, up to 128 characters, required): The person's id, as your app sent it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `30d`): Counts cover this range.

**Request:**

```bash
curl "https://api.sypnia.com/v1/people/u_1042" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "u_1042",
  "name": "Ada Park",
  "email": "ada@example.com",
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  },
  "first_seen": "2026-02-18T16:02:11Z",
  "last_seen": "2026-03-12T10:31:58Z",
  "sessions": 6,
  "trouble_sessions": 1,
  "errors": 1,
  "always_record": false,
  "latest_sessions": [
    {
      "id": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "started_at": "2026-03-12T10:31:16Z",
      "duration_ms": 42000,
      "trouble": true,
      "has_replay": true
    }
  ]
}
```

**Errors:**

- `404` `not_found`: No person has this id in the project.

## Delete a person's data

`DELETE /v1/people/{person_id}` \[Engine, Cloud]

Deletes everything Sypnia holds about one person: their name and e-mail, their sessions, events, replays and
page snapshots. Use it to answer a request to be forgotten. Totals (how many people a problem hit, page
performance) keep their numbers and hold nothing about the person.

The person leaves every list at once. Stored objects, including the raw event files that held their events,
are rewritten without them within 24 hours. New events with the same id create the person again: stop sending
them first.

**Authentication:** API token (`admin`)

**Path parameters:**

- `person_id` (string, up to 128 characters, required): The person's id, as your app sent it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/people/u_0977" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Response (202):**

```json
{
  "person_id": "u_0977",
  "sessions": 3,
  "status": "deleting",
  "done_by": "2026-03-13T10:40:00Z"
}
```

**Errors:**

- `404` `not_found`: No person has this id in the project.

## List accounts

`GET /v1/accounts` \[Engine, Cloud]

The accounts (teams, companies, whatever your app groups people by) that were active in the range, with their
activity. An account exists once your app sent `account.id` with `identify()`. A project that never sends
accounts gets an empty list.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `30d`): Only accounts active after this moment. Counts cover this range.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `q` (string, up to 120 characters, optional): Text to find in the id or the name.
- `sort` (string, optional, default `last_seen`): `last_seen`, `sessions`, `people` or `trouble`.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/accounts?since=30d" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "acc_77",
      "name": "Corner Café",
      "people": 14,
      "sessions": 96,
      "trouble_sessions": 4,
      "first_seen": "2026-02-03T08:11:40Z",
      "last_seen": "2026-03-12T10:02:19Z"
    }
  ],
  "next_cursor": null
}
```

## Get an account

`GET /v1/accounts/{account_id}` \[Engine, Cloud]

One account with its activity in the range. For its people, list people with `account`; for its sessions, list sessions with `account`.

**Authentication:** API token (`read`)

**Path parameters:**

- `account_id` (string, up to 128 characters, required): The account's id, as your app sent it. URL-encode it.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `30d`): Counts cover this range.

**Request:**

```bash
curl "https://api.sypnia.com/v1/accounts/acc_77" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "acc_77",
  "name": "Corner Café",
  "people": 14,
  "sessions": 96,
  "trouble_sessions": 4,
  "first_seen": "2026-02-03T08:11:40Z",
  "last_seen": "2026-03-12T10:02:19Z",
  "always_record": false
}
```

**Errors:**

- `404` `not_found`: No account has this id in the project.

## List custom events

`GET /v1/custom-events` \[Engine, Cloud]

The events your app sent with `track(name, props)`, by name, with how often each happened in the range. To see
the sessions behind one, list sessions with `event`. A project keeps up to 500 different names; events with a
new name beyond that are stored in their sessions and not counted here.

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `environment` (string, optional, default `production`): The environment to read. Any name the project has sent, or `all`.
- `since` (string, optional, default `7d`): Counts cover this range.
- `until` (string, optional): End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.
- `name` (string, up to 80 characters, optional): Only names that start with this text.
- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://api.sypnia.com/v1/custom-events?since=24h" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "name": "checkout_started",
      "count": 58,
      "sessions": 51,
      "people": 49,
      "last_seen": "2026-03-12T10:31:28Z"
    },
    {
      "name": "order_paid",
      "count": 31,
      "sessions": 31,
      "people": 30,
      "last_seen": "2026-03-12T07:52:10Z"
    }
  ],
  "next_cursor": null
}
```

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
