Docs

Sessions and replays

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

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The session object
  2. The session event object
  3. The person object
  4. The account object
  5. List sessions
  6. Get a session
  7. Delete a session
  8. Get a session’s timeline
  9. Get a session’s replay
  10. List people
  11. Get a person
  12. Delete a person’s data
  13. List accounts
  14. Get an account
  15. List custom events

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 EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Only sessions that started after this moment.

    Default: 7d

  • until
    string optional

    End of the time range. An ISO 8601 timestamp or a relative value. Defaults to now.

  • trouble
    boolean optional

    true returns only sessions with trouble.

    Default: false

  • 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

    recent (last activity first), trouble (most trouble first) or longest.

    Default: recent

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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} EngineCloud

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

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

Response200

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

  • 404not_found

    No session has this id in the project, or it is not processed yet (give it 10 minutes).

  • 410expired

    The session is older than the project’s retention and was deleted.

Delete a session

DELETE /v1/sessions/{session} EngineCloud

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

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

Errors

  • 404not_found

    No session has this id in the project.

Get a session’s timeline

GET /v1/sessions/{session}/events EngineCloud

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

    true leaves out successful requests, vitals and page leaves.

    Default: false

  • 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

    Most events to return.

    Default: 200

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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

  • 404not_found

    No session has this id in the project.

  • 410expired

    The session’s events are older than the project’s retention.

Get a session’s replay

GET /v1/sessions/{session}/replay EngineCloud

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

    Most compressed bytes of chunks in the window.

    Default: 40000000

Request

Terminal
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 failure200

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 replay200

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

Errors

  • 400invalid_request

    at and from_seq together, or at outside the session.

  • 403forbidden

    The token does not have the replay scope.

  • 404not_found

    No session has this id in the project.

List people

GET /v1/people EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Only people active after this moment. Counts cover this range.

    Default: 30d

  • 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

    last_seen, sessions or trouble (most sessions with trouble first).

    Default: last_seen

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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} EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Counts cover this range.

    Default: 30d

Request

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

Response200

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

  • 404not_found

    No person has this id in the project.

Delete a person’s data

DELETE /v1/people/{person_id} EngineCloud

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

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

Response202

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

Errors

  • 404not_found

    No person has this id in the project.

List accounts

GET /v1/accounts EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Only accounts active after this moment. Counts cover this range.

    Default: 30d

  • 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

    last_seen, sessions, people or trouble.

    Default: last_seen

  • limit
    integer, 1 to 200 optional

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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} EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Counts cover this range.

    Default: 30d

Request

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

Response200

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

  • 404not_found

    No account has this id in the project.

List custom events

GET /v1/custom-events EngineCloud

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

    The environment to read. Any name the project has sent, or all.

    Default: production

  • since
    string optional

    Counts cover this range.

    Default: 7d

  • 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

    Most items to return.

    Default: 50

  • cursor
    string optional

    The next_cursor of the previous page. Keep every other parameter the same.

Request

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

Response200

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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close