---
title: "Search recordings"
method: GET
path: "/v1/recordings"
tags: ["Recordings"]
---

# Search recordings

`GET /v1/recordings`

## Request

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

Returns the organisation's unexpired recordings across its sites, newest first, 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` string
- `country` string
- `device` string
- `browser` string
- `os` string
- `ip` string
- `entry_path` string
- `visited_path` string
- `visitor_id` string, uuid

## Response `200`

A page of recordings

- object
  - `next_cursor` string, required: Opaque cursor for the next page; empty on the last page.
  - `recordings` RecordingRow[], required
    - `browser` string, nullable, required: Coarse class from the user agent.
    - `bytes` integer, required: Compressed bytes stored.
    - `chunks` integer, required
    - `country` string, nullable, required: From Cloudflare, when the request came through it.
    - `created_at` string, date-time, required
    - `device` 'desktop' | 'mobile' | 'tablet' | 'null', nullable, required
    - `duration_ms` integer, required: The recorded activity, in milliseconds: in each page load, from its first batch's start to its last batch's end by the browser's monotonic clock, summed.
    - `end_reason` 'finished' | 'idle_timeout' | 'duration_cap' | 'byte_cap' | 'site_disabled' | 'null', nullable, required
    - `ended_at` string, date-time, nullable, required
    - `entry_path` string, nullable, required
    - `events` integer, required
    - `expires_at` string, date-time, required
    - `first_received_at` string, date-time, nullable, required
    - `id` string, uuid, required
    - `ip` string, nullable, required: The visitor's IP address.
    - `last_received_at` string, date-time, nullable, required
    - `last_seen_at` string, date-time, required: The last batch or heartbeat. An open page sends a heartbeat every 30 seconds.
    - `live` boolean, required: Still open and heard from in the last 90 seconds: someone is on the page. Open but quiet means the visitor has most likely gone; the recording closes after 30 minutes without a word, because leaving a page cannot be told apart from moving to the next one.
    - `origin` string, required
    - `os` string, nullable, required
    - `playable` boolean, required: True once some epoch holds a checkpoint at its start.
    - `session_id` string, uuid, nullable, required: The session the recording belongs to. Null only for a recording made before sessions that has not been placed in one yet.
    - `site_id` string, uuid, required
    - `site_name` string, required
    - `state` 'pending' | 'recording' | 'ready' | 'partial' | 'unplayable', required
    - `visitor_id` string, uuid, nullable, required: The browser that made the recording: a random id the recorder (SDK 0.3.0 and later) keeps in the site's localStorage. The same id on two recordings is the same browser, unless its storage was cleared in between. Null for recordings from older recorders.

## 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)