Events & ExportSession list

Session list

One row per session, most recent first — the backbone of attribution reporting. Attribution fields (all UTMs, click IDs, referrer, landing page) come from the session's entry properties. engaged is derived: a session is engaged if it has more than one pageview, lasted at least 10 seconds, or fired a non-pageview event; bounce is the inverse. Empty string on a filter means "no value set". Not yet returned: is_new_visitor and converted/goal fields.

Segment scoping: pass segment_id (a segment created via the Segments API) to list only sessions by that segment's members — composable with every other filter:

GET /client/v1/data/sessions?segment_id=9f4e...&engaged=1&device_type=mobile

The segment decides which people qualify (evaluated live at query time); the date window decides which of their sessions are returned — a qualifying person contributes all their in-window sessions, including ones unrelated to how they qualified. See the segment_id parameter for attribution-scope and identity-graph details.

Person scoping (profile views): pass person_id (canonical id from the People API) or distinct_id (any raw identity value) to list one person's sessions — resolved through the identity graph, so anonymous pre-identification sessions are included:

GET /client/v1/data/sessions?person_id=019f69bc-...&date_from=2026-01-01

curl -X GET "https://mythic-analytics.gulp.workers.dev/client/v1/data/sessions?location_id=example_string&session_id=example_string&date_from=2024-12-25&date_to=2024-12-25&utm_source=example_string&utm_medium=example_string&utm_campaign=example_string&device_type=example_string&browser=example_string&os=example_string&country=USA&landing_page=example_string&engaged=true&bounce=true&is_identified=true&person_id=example_string&distinct_id=example_string&min_duration=42&segment_id=123e4567-e89b-12d3-a456-426614174000&limit=100&offset=0" \
  -H "Content-Type: application/json" \
  -H "X-Location-Id: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "success": true,
  "data": [
    {
      "session_id": "example_string",
      "distinct_id": "example_string",
      "user_id": "example_string",
      "is_identified": true,
      "started_at": "2024-12-25T10:00:00Z",
      "ended_at": "2024-12-25T10:00:00Z",
      "duration_seconds": 42,
      "events": 42,
      "pageviews": 25,
      "engaged": true,
      "bounce": true,
      "landing_page": "example_string",
      "landing_url": "example_string",
      "exit_page": "example_string",
      "referrer": "example_string",
      "referring_domain": "example_string",
      "has_recording": true,
      "recording_available_until": "2024-12-25T10:00:00Z",
      "utm_source": "example_string",
      "utm_medium": "example_string",
      "utm_campaign": "example_string",
      "utm_content": "example_string",
      "utm_term": "example_string",
      "utm_id": "example_string",
      "gclid": "example_string",
      "gbraid": "example_string",
      "wbraid": "example_string",
      "fbclid": "example_string",
      "msclkid": "example_string",
      "ttclid": "example_string",
      "twclid": "example_string",
      "li_fat_id": "example_string",
      "oppref": "example_string",
      "obref": "example_string",
      "epik": "example_string",
      "sccid": "example_string",
      "device_type": "example_string",
      "browser": "example_string",
      "os": "example_string",
      "country": "USA",
      "city": "New York",
      "timezone": "example_string"
    }
  ],
  "rows": 42
}
GET
/sessions
GET
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

Agency key (ak_) or location secret key (sk_) as a bearer token. Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need the read scope of the family the route belongs to (people, events, sessions, replays, exceptions, heatmaps or bigquery_export). See Using an mcp_ key over HTTP.

Agency key (ak_) or location secret key (sk_) as a bearer token. Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need the read scope of the family the route belongs to (people, events, sessions, replays, exceptions, heatmaps or bigquery_export). See Using an mcp_ key over HTTP.
query
location_idstring

Alternative to the X-Location-Id header for agency (ak_) keys. Ignored for secret (sk_) keys.

query
session_idstring

Return just this one session (exact match). Useful for looking up a single session's attribution — e.g. alongside its replay. When set, other filters and the date window are effectively moot.

query
date_fromstring

Start date (YYYY-MM-DD).

Format: date
query
date_tostring

End date (YYYY-MM-DD).

Format: date
query
utm_sourcestring

Filter to sessions with this UTM source. Empty string = "no value set".

query
utm_mediumstring

Filter to sessions with this UTM medium.

query
utm_campaignstring

Filter to sessions with this UTM campaign.

query
device_typestring

Filter to sessions on this device type.

query
browserstring

Filter to sessions on this browser.

query
osstring

Filter to sessions on this operating system.

query
countrystring

Filter to sessions from this country (ISO code).

query
landing_pagestring

Filter to sessions whose entry path matches. Case-insensitive and trailing-slash-insensitive (/About/ matches /about). Query params never apply — the path is captured without them.

query
engagedboolean

Filter by engagement (1/0, or true/false).

query
bounceboolean

Filter by bounce (1/0, or true/false).

query
is_identifiedboolean

Filter to identified (1) or anonymous (0) sessions.

query
person_idstring

Scope to one person's sessions: the canonical person id from the People API (GET /people, GET /people/{personId}). Matches every session whose visitor id belongs to that person in the identity graph (anonymous ids, user ids, emails), so pre-identification sessions are included. Powers per-person Sessions/Recordings tabs on a profile view. Composable with all other filters and the date window; widen date_from for history older than the 30-day default.

query
distinct_idstring

Scope to one person's sessions by any raw identity value (anonymous id, user id, or email). Resolved through the identity graph to the owning person's full identity set — same resolution as GET /people/{personId} — so it returns the same rows as person_id for the same person. A value not in the graph (a never-identified visitor) falls back to an exact distinct_id match. If person_id is also given, both conditions must match (AND) — pass one or the other.

query
min_durationinteger

Minimum session duration in seconds.

query
segment_idstring

Scope results to members of a saved segment (created via the Segments API). Two independent time filters apply: the segment decides WHICH PEOPLE qualify (a live definition, evaluated at query time — not stored membership), and date_from/date_to decides WHICH OF THEIR ROWS are returned. A person who qualifies today contributes all their sessions/events inside the date window — including ones unrelated to how they qualified; there is no "only rows from while they were a member". For first/last attribution scopes membership runs through the identity graph (a row counts when its distinct_id maps to a matching person); a segment with attribution: "session" instead matches visitors directly against the sessions store ("ever had a session that arrived via X"), with no identity-graph dependency. Composable with all other filters. Unknown or foreign id → 404 segment_not_found.

Format: uuid
query
limitinteger

Max rows. Default 100, min 1, max 1000.

Min: 1 • Max: 1000
query
offsetinteger

Row offset for pagination.

header
X-Location-Idstring

Location to scope the request to. Required for agency (ak_) keys on the event routes. Ignored for secret (sk_) keys, which resolve their own location, and not used by /export.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. Agency key (ak_) or location secret key (sk_) as a bearer token. Format: Bearer ak_... or Bearer sk_.... Scoped keys (mcp_) are accepted too and need the read scope of the family the route belongs to (people, events, sessions, replays, exceptions, heatmaps or bigquery_export). See Using an mcp_ key over HTTP.

Query Parameters

location_idstring

Alternative to the X-Location-Id header for agency (ak_) keys. Ignored for secret (sk_) keys.

session_idstring

Return just this one session (exact match). Useful for looking up a single session's attribution — e.g. alongside its replay. When set, other filters and the date window are effectively moot.

date_fromstring

Start date (YYYY-MM-DD).

date_tostring

End date (YYYY-MM-DD).

utm_sourcestring

Filter to sessions with this UTM source. Empty string = "no value set".

utm_mediumstring

Filter to sessions with this UTM medium.

utm_campaignstring

Filter to sessions with this UTM campaign.

device_typestring

Filter to sessions on this device type.

browserstring

Filter to sessions on this browser.

osstring

Filter to sessions on this operating system.

countrystring

Filter to sessions from this country (ISO code).

landing_pagestring

Filter to sessions whose entry path matches. Case-insensitive and trailing-slash-insensitive (/About/ matches /about). Query params never apply — the path is captured without them.

engagedboolean

Filter by engagement (1/0, or true/false).

bounceboolean

Filter by bounce (1/0, or true/false).

is_identifiedboolean

Filter to identified (1) or anonymous (0) sessions.

person_idstring

Scope to one person's sessions: the canonical person id from the People API (GET /people, GET /people/{personId}). Matches every session whose visitor id belongs to that person in the identity graph (anonymous ids, user ids, emails), so pre-identification sessions are included. Powers per-person Sessions/Recordings tabs on a profile view. Composable with all other filters and the date window; widen date_from for history older than the 30-day default.

distinct_idstring

Scope to one person's sessions by any raw identity value (anonymous id, user id, or email). Resolved through the identity graph to the owning person's full identity set — same resolution as GET /people/{personId} — so it returns the same rows as person_id for the same person. A value not in the graph (a never-identified visitor) falls back to an exact distinct_id match. If person_id is also given, both conditions must match (AND) — pass one or the other.

min_durationinteger

Minimum session duration in seconds.

segment_idstring

Scope results to members of a saved segment (created via the Segments API). Two independent time filters apply: the segment decides WHICH PEOPLE qualify (a live definition, evaluated at query time — not stored membership), and date_from/date_to decides WHICH OF THEIR ROWS are returned. A person who qualifies today contributes all their sessions/events inside the date window — including ones unrelated to how they qualified; there is no "only rows from while they were a member". For first/last attribution scopes membership runs through the identity graph (a row counts when its distinct_id maps to a matching person); a segment with attribution: "session" instead matches visitors directly against the sessions store ("ever had a session that arrived via X"), with no identity-graph dependency. Composable with all other filters. Unknown or foreign id → 404 segment_not_found.

limitinteger

Max rows. Default 100, min 1, max 1000.

offsetinteger

Row offset for pagination.

Headers

X-Location-Idstring

Location to scope the request to. Required for agency (ak_) keys on the event routes. Ignored for secret (sk_) keys, which resolve their own location, and not used by /export.

Responses

successboolean
dataarray
rowsinteger

Number of rows returned.