> For the complete documentation index, see [llms.txt](https://docs.birdie.so/birdie-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.birdie.so/birdie-docs/birdie-api/reference/api-reference/list-recordings.md).

# List Recordings

This is the method to get a list a recordings, you can query them with some parameters.

## Retrieve a list of videos

> Returns a paginated list of video objects. Optional filters include: ticket, email, and a custom metadata filter using param and value.

```json
{"openapi":"3.1.1","info":{"title":"Birdie API","version":"1.0.0"},"servers":[{"url":"https://app.birdie.so/api/v1"}],"paths":{"/videos":{"get":{"summary":"Retrieve a list of videos","description":"Returns a paginated list of video objects. Optional filters include: ticket, email, and a custom metadata filter using param and value.","operationId":"getVideos","parameters":[{"schema":{"type":"string"},"name":"ticket","in":"query","description":"Filter videos by ticket id.","required":false},{"schema":{"type":"string"},"name":"email","in":"query","description":"Filter videos by customer email (recorded_by).","required":false},{"schema":{"type":"string"},"name":"param","in":"query","description":"Filter videos by metadata key (only when you added those params with the recording link type /urec/helpdesk?param=value). For example, use param=firstname to filter by the firstname metadata.","required":false},{"schema":{"type":"string"},"name":"value","in":"query","description":"The value for the metadata filter specified in param. For example, value=john.","required":false},{"schema":{"type":"string"},"name":"Authorization","in":"header","description":"Bearer authentication header of the form Bearer <token>.","required":true}],"responses":{"200":{"description":"A paginated list of video objects.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"links":{"type":"object","properties":{"first":{"type":"string","format":"uri"},"last":{"type":["string","null"],"format":"uri"},"prev":{"type":["string","null"],"format":"uri"},"next":{"type":["string","null"],"format":"uri"}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer"},"path":{"type":"string","format":"uri"},"per_page":{"type":"integer"},"to":{"type":"integer"}}}}}}}}}}}},"components":{"schemas":{"Video":{"type":"object","required":["id","way","recorded_by","bytes","comment","edited","created_at","duration","origin","metadata","processing_status","sharing_link","thumbnail_file","ticket","ai_summary","uuid","video_file","video_size_bytes","video_length_milliseconds"],"properties":{"id":{"type":"integer"},"way":{"type":"string","enum":["received","sent"],"description":"`received`: recorded by a customer through a recording link or the snippet. `sent`: recorded by a member of the workspace."},"recorded_by":{"type":["string","null"],"description":"Email of the person who recorded (a member, or a customer when known), else their name or identifier."},"requested_by":{"type":["string","null"],"description":"Email of the member who requested the recording, when it was requested."},"bytes":{"type":"integer","description":"Size of the video file in bytes."},"comment":{"type":["string","null"],"description":"Comment typed by the person when they recorded through a recording link, when the form had one. Null otherwise."},"edited":{"type":"boolean","description":"True when the recording was trimmed in Birdie. video_file, duration and transcription then describe the edited version."},"title":{"type":["string","null"]},"console_logs":{"type":["string","null"],"description":"Temporary URL of the console log file, when console capture was on."},"created_at":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Length of the video in milliseconds."},"network_logs":{"type":["string","null"],"description":"Temporary URL of the network log file, when network capture was on."},"origin":{"type":"string","description":"Where the recording came from: an integration name (intercom, zendesk, hubspot...), the name of the universal recording link it was made through, `uploaded video file`, `chrome extension`, or `inapp` for a recording made in Birdie."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Custom parameters attached to the recording: the query parameters of the recording link (/urec/helpdesk?param=value) or what the snippet passed. Null when there are none. Filterable on List Recordings with param and value."},"processing_status":{"type":"string","enum":["pending","processing","completed","failed"]},"request_link":{"type":["string","null"],"description":"The recording link this recording was made through, for received recordings.","format":"uri"},"sharing_link":{"type":"string","format":"uri"},"thumbnail_file":{"type":"string","format":"uri"},"ticket":{"type":["string","null"],"description":"Id of the helpdesk ticket or conversation this recording is attached to (via an integration or a `ticket` recording-link parameter). Null when there is none."},"transcription":{"description":"Transcript of the recording; null until transcription has run. (The `summary` key this object used to carry was removed on 1 October 2026; the recap of a recording is `ai_summary`.)","oneOf":[{"type":"object","properties":{"status":{"type":"string"},"language":{"type":"string"},"transcript":{"type":"string"},"raw_file":{"type":"string"}}},{"type":"null"}]},"ai_summary":{"description":"The AI Summary of the recording: what the person did, what went wrong, and the evidence behind it. Always present; `null` until a summary has been generated for this recording (the workspace has AI Summary switched off, or the run has not completed yet). When a new run completes, this is the latest one.","oneOf":[{"$ref":"#/components/schemas/AiSummary"},{"type":"null"}]},"uuid":{"type":"string"},"video_file":{"type":"string","format":"uri"},"video_size_bytes":{"type":"integer","description":"Same value as bytes, kept for compatibility."},"video_length_milliseconds":{"type":"integer","description":"Same value as duration, kept for compatibility."}}},"AiSummary":{"type":"object","required":["schema_version","analysed_at","provider","model","trigger","outcome","title","summary","steps","likely_cause","to_go_further","confidence","displayed_confidence","evidence","caveats","environment","usage","text"],"properties":{"schema_version":{"type":"integer","description":"Shape of this object. Currently 3."},"analysed_at":{"type":"string","format":"date-time","description":"When the summary was completed (ISO 8601)."},"provider":{"type":"string","description":"Model vendor the summary was produced with."},"model":{"type":"string","description":"Model identifier at the vendor."},"trigger":{"type":"string","enum":["automatic","manual"],"description":"`automatic` when the summary ran after processing; `manual` when someone pressed Generate or Regenerate."},"outcome":{"type":"string","enum":["failure_observed","no_failure_observed","describes_issue_only","not_enough_to_tell"],"description":"`failure_observed`: something on screen, in the logs or in speech contradicted what the person was doing. `no_failure_observed`: nothing went wrong in what was recorded. `describes_issue_only`: the recording shows someone describing a problem rather than the problem itself. `not_enough_to_tell`: the recording does not contain enough to say."},"title":{"type":"string","description":"One line, at most 12 words."},"summary":{"type":"string","description":"A short paragraph in plain language."},"steps":{"type":"array","description":"What the person did, in order, written as reproduction steps. Empty when steps could not be derived.","items":{"type":"object","required":["text","timecode"],"properties":{"text":{"type":"string"},"timecode":{"type":["string","null"],"description":"MM:SS in the recording, or null for a step with no captured moment."}}}},"likely_cause":{"type":["string","null"],"description":"Stated only when a console or network signal is tied to what went wrong. Null otherwise — the summary never guesses."},"to_go_further":{"type":["string","null"],"description":"One or two sentences specific to this recording: which signal to trace, what to record next. Null when there is nothing specific to say."},"confidence":{"type":"string","enum":["low","medium","high"],"description":"The model's own confidence in its outcome."},"displayed_confidence":{"type":["string","null"],"enum":["low","medium","high",null],"description":"Birdie's confidence rating, from how much first-party evidence backs the outcome. Only set when a failure was observed."},"evidence":{"type":"array","description":"The signals the summary rests on, each with where it came from.","items":{"type":"object","required":["timecode","signal","detail"],"properties":{"timecode":{"type":["string","null"],"description":"MM:SS.mmm, or null for a signal with no time."},"signal":{"type":"string","enum":["console","network","frame","speech","step","metadata"]},"detail":{"type":"string"}}}},"caveats":{"type":"array","description":"Limits of this run, in plain language (for example, frames were not examined because the model cannot read images).","items":{"type":"string"}},"environment":{"type":["object","null"],"description":"Browser, OS, page and viewport of the recording, when known.","properties":{"browser":{"type":["string","null"]},"os":{"type":["string","null"]},"url":{"type":["string","null"]},"viewport":{"type":["string","null"]}}},"usage":{"type":"object","description":"What the run consumed.","properties":{"model_calls":{"type":"integer"},"frames":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"elapsed_ms":{"type":"integer"}}},"text":{"type":"string","description":"The whole summary as one block of plain text (title, summary, numbered steps with timecodes, environment, cause, evidence) — for a consumer that maps a single field, such as a Zap or a helpdesk note."}}}}}}
```

{% hint style="info" %}
Note: If you are using [Folders](broken://spaces/ECPgvsGwy5oMz4WIZw3a/pages/Gd80Df246mMo1997cFGP), videos placed in a secure folder won't appear in the results.
{% endhint %}