> 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/get-a-recording.md).

# Get a Recording

This is the method to request a single recording if you have its identifier or its sharing link code.

## Retrieve a video recording by ID

> Returns a video object if found, otherwise a 404 error.

```json
{"openapi":"3.1.1","info":{"title":"Birdie API","version":"1.0.0"},"servers":[{"url":"https://app.birdie.so/api/v1"}],"paths":{"/videos/{video_id}":{"get":{"summary":"Retrieve a video recording by ID","description":"Returns a video object if found, otherwise a 404 error.","operationId":"getVideoById","parameters":[{"schema":{"type":"string"},"name":"video_id","in":"path","description":"The unique identifier of the video, which can be the video id (integer), video uuid, or even the video sharing-link identifier.","required":true},{"schema":{"type":"string"},"name":"Authorization","in":"header","description":"Bearer API-KEY","required":true}],"responses":{"200":{"description":"Successful response containing the video object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Video"}}}},"403":{"description":"Resource is not accessible (e.g. the video is into a private folder).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"404":{"description":"Video not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"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."}}}}}}
```