---
title: "List Sessions"
method: GET
path: "/analytics/sessions"
tags: ["Analytics"]
---

# List Sessions

`GET /analytics/sessions`

Returns a paginated list of sessions with address, cart progression, order, and commission data.
Scoped to all tokens belonging to the authenticated client.

## Filtering
- `start_date` / `end_date`: ISO 8601 date strings to bound the query window
- `updated_since`: Return only sessions whose session or order data changed on or after this time; results are ordered by most recent change first
- `token_ids[]`: Restrict to specific API tokens (must belong to your account)
- `with_clicks`: When `true`, only returns sessions with click activity

## Pagination
Results are paginated at 50 sessions per page. Use the `page` parameter and
the `meta.pages` field to navigate.

## Syncing order status
To keep a local copy of order status current, poll with `updated_since` set to the time of
your last successful sync and page through all results. A session is returned whenever the
session or its order changed, including installs, cancellations, and commission updates on
sessions created long ago. Treat each returned row as authoritative and overwrite your stored
copy. Do not use `start_date` as a sync cursor: it filters on session creation time, so status
changes on previously synced sessions are never returned. Unrecognized parameters are ignored.

## Query parameters

- `page` integer
- `start_date` string, date-time
- `end_date` string, date-time
- `updated_since` string, date-time
- `token_ids[]` string[]
- `with_clicks` boolean

## Response `200`

Paginated list of analytics sessions

- object
  - `message` string, required — A message returned by the API. Includes a human-readable message about the status of the request.
  - `request_status` 'ok' | 'warning' | 'error', required — An informational summary returned in API response bodies: `ok` for successful responses, `warning` for standard request errors, and `error` for endpoint-specific failures. Integrations must use the HTTP status code, not `request_status`, to determine whether a request succeeded.
  - `data` AnalyticsSessionSummary[], required
    - `id` string, uuid
    - `created_at` string, date-time
    - `context` 'move_in' | 'move_out' — Traffic context for the session, set from the API token that created it. `move_in` is a resident setting up service at a home they are moving into. `move_out` is a resident leaving a partner's property. Note that the address on a move-out session is the resident's destination home, not the partner's building. Sessions created before this field was introduced read `move_in`.
    - `campaign_id` string, nullable — Campaign tracking identifier, if provided when the session was created.
    - `address` AnalyticsAddress — Service address for the session.
      - `street1` string, nullable
      - `street2` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `zip` string, nullable
    - `furthest_step` integer, nullable — Highest checkout step reached during this session (1-8). Null if no cart events.
    - `order_number` string, nullable — Order number, if an order was placed.
    - `status` 'draft' | 'submitted' | 'processing' | 'confirmed' | 'complete' | 'cancelled', nullable — Order status. Null if no order was placed. Cancelled orders are final.
    - `ordered_at` string, date-time, nullable — When the order was submitted.
    - `installed` boolean, nullable — Whether the service has been installed. Always false for cancelled orders.
    - `installed_at` string, date-time, nullable — When the service was installed. Null for cancelled orders.
    - `commission_cents` integer, nullable — Locked commission in cents. Null if no commission recorded and for cancelled orders.
  - `meta` AnalyticsPaginationMeta, required — Pagination metadata for list responses.
    - `responded_at` string, date-time — The timestamp when the response was generated.
    - `page` integer — Current page number.
    - `pages` integer — Total number of pages.
    - `count` integer — Total number of sessions matching the query.

## Other responses

- `401` — Unauthorized. Use the HTTP status code, not `request_status`, to detect the error.
- `403` — Forbidden. The requested resource does not belong to the authenticated account, or a security policy blocked the request.
- `429` — Rate Limit Exceeded
- `500` — Unexpected internal error handled by an API controller.

---

[API](https://skmtc.dev/letshum/apis/hum-api.md) · [All operations](https://skmtc.dev/letshum/apis/hum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/letshum/hum-api/revisions/5e36540cb9b0/schema)