---
title: "Search sessions"
method: GET
path: "/v1/sessions"
tags: ["Sessions"]
---

# Search sessions

`GET /v1/sessions`

## Request

- Base URL: `https://api.ironfang.com/analytics`
- URL: `https://api.ironfang.com/analytics/v1/sessions`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Returns the organisation's sessions across its sites, newest first by when they started, as a bounded keyset page. Every filter is optional and they combine. Needs analytics.sessions.read.

## Query parameters

- `cursor` string
- `limit` integer
- `site_id` string, uuid
- `from` string, date-time
- `to` string, date-time
- `state` 'live' | 'active' | 'ended'
- `country` string
- `device` string
- `browser` string
- `os` string
- `ip` string
- `entry_path` string
- `visited_path` string
- `visitor_id` string, uuid
- `recording` 'with' | 'without'
- `diagnostics` 'errors' | 'requests' | 'any'

## Response `200`

A page of sessions

- object
  - `next_cursor` string, required: Opaque cursor for the next page; empty on the last page.
  - `sessions` SessionRow[], required
    - `anonymised` boolean, required: Its IP address, user agent, visitor id, error messages and event properties were cleared at the recording retention.
    - `browser` string, nullable, required
    - `country` string, nullable, required
    - `counts` object, required
      - `console_errors` integer, required: console.error calls (SDK 0.7.0).
      - `custom` integer, required: Events the page tracked.
      - `dropped` integer, required: Pages and other events beyond the session's limits, counted and not kept.
      - `errors` integer, required: Uncaught errors and unhandled rejections.
      - `errors_not_kept` integer, required: Errors and console errors past the per-page or per-session limits, counted and not kept.
      - `events` integer, required: Every event, of every type.
      - `failed_requests` integer, required: Requests that failed: an error answer, no answer, a timeout or a resource that did not load.
      - `pages` integer, required
      - `replayable_pages` integer, required: Pages a recording that can still be played saw.
      - `request_sample_percent` integer, nullable, required: The smallest share of successful requests kept while the session was reported; null when none were sampled.
      - `requests` integer, required: Requests kept: every outcome before SDK 0.7.0 only failed or slow ones.
      - `requests_not_kept` integer, required: Requests past the per-page or per-session limits, counted and not kept.
      - `requests_sampled_out` integer, required: Successful requests sampling left out.
      - `tabs` integer, required
    - `device` 'desktop' | 'mobile' | 'tablet' | 'null', nullable, required
    - `duration_ms` integer, required: From the start to the last activity.
    - `end_reason` 'idle_timeout' | 'duration_cap' | 'null', nullable, required: idle_timeout, 30 minutes without the visitor doing anything; duration_cap, 12 hours from its start.
    - `ended_at` string, date-time, nullable, required
    - `entry_path` string, nullable, required
    - `exit_path` string, nullable, required
    - `expires_at` string, date-time, required
    - `id` string, uuid, required
    - `ip` string, nullable, required: Null once the session is anonymised.
    - `last_activity_at` string, date-time, required: The visitor's last activity in any tab.
    - `live` boolean, required: Active and heard from in the last 90 seconds.
    - `origin` string, required
    - `os` string, nullable, required
    - `recording` object, required
      - `available` integer, required: Recordings that can be played.
      - `live` boolean, required: The open recording was heard from in the last 90 seconds.
      - `open_recording_id` string, uuid, nullable, required: The recording still open, to watch live.
      - `status` 'none' | 'recording' | 'available' | 'partial' | 'expired' | 'deleted' | 'unavailable', required: none, no recording; recording, one is still open; available, every page can be replayed; partial, some can; expired, deleted or unavailable, recordings exist and none can be played.
      - `total` integer, required
    - `referrer` string, nullable, required: Origin and path only.
    - `site_id` string, uuid, required
    - `site_name` string, required
    - `source` 'sdk' | 'recording', required: sdk, reported page by page by the SDK (0.6.0 and later); recording, known only from its recordings (older SDKs, and visits recorded before sessions), so only recorded pages are in it.
    - `started_at` string, date-time, required
    - `state` 'active' | 'ended', required
    - `visitor_id` string, uuid, nullable, required: Null once the session is anonymised.

## Other responses

- `400`: An unknown, repeated or malformed query parameter (`invalid_query`).
- `401`: No credential, an invalid one, an expired partner integration key, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `api_key_expired`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, names another organisation, or belongs to a partner integration that is not active (`forbidden`, `insufficient_scope`, `integration_inactive`).

---

[API](https://skmtc.dev/ironfang/apis/ironfang-analytics-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/revisions/08197080c3d7?raw)