---
title: "Request a download"
method: POST
path: "/recordings/{recording_id}/download"
tags: ["Recordings"]
---

# Request a download

`POST /recordings/{recording_id}/download`

## Request

- Base URL: `https://api.fathom.ai/external/v1`
- URL: `https://api.fathom.ai/external/v1/recordings/{recording_id}/download`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Starts async generation of a downloadable file and returns a `download_id` to poll. Video is generated in the background; audio-only recordings complete immediately, so the response may already return `status: completed` with the file payload.

Downloads are private to the API client that created them, and URLs expire ~24 hours after generation—request a new one when it expires.

Only the owner, teammates who can view the recording, and people it was shared with at standard or admin level can download it. Limited-access shares get `403 Forbidden`.

## Path parameters

- `recording_id` integer, required

## Request body

- object
  - `destination_url` string, uri: URL Fathom POSTs the completed download payload to when it is ready. If omitted, poll the status endpoint.

## Response `202`

The download request was accepted. Poll the download status endpoint until it completes.

- RecordingDownload
  - `download_id` string, required
  - `recording_id` integer, required
  - `status` 'processing' | 'completed' | 'failed' | 'expired', required
  - `video` RecordingDownloadFile
    - `url` string, uri, required: Short-lived signed URL for the generated file. Valid until `expires_at`.
    - `content_type` string, required
    - `file_size_bytes` integer, required
    - `expires_at` string, date-time, required: When the download and its URL expire. Request a new download after this time.
  - `audio` RecordingDownloadFile
    - `url` string, uri, required: Short-lived signed URL for the generated file. Valid until `expires_at`.
    - `content_type` string, required
    - `file_size_bytes` integer, required
    - `expires_at` string, date-time, required: When the download and its URL expire. Request a new download after this time.
  - `failure_reason` 'generation_failed' | 'generation_timeout': Present when the download failed.

## Other responses

- `401`: Unauthorized - missing or invalid `Authorization` header.
- `403`: Forbidden - the authenticated user is not permitted to perform this request.
- `404`: Not found - the resource was not found.
- `422`: Unprocessable - the recording has no downloadable media.
- `429`: Rate limited - you have exceeded the rate limit for the requested endpoint. Check our [rate limiting](/api-reference#rate-limiting) documentation for more information.

## Changes

- **2026-11-03** `acb2fb1e3af8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fathom/apis/fathom-external-api/changes/recordings/:recording_id/download/post.md)

---

[API](https://skmtc.dev/fathom/apis/fathom-external-api.md) - [All operations](https://skmtc.dev/fathom/apis/fathom-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fathom/apis/fathom-external-api/revisions/acb2fb1e3af8?raw)