> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riverside.fm/llms.txt
> Use this file to discover all available pages before exploring further.

# Download Timeline File

> Downloads a generated editing-timeline (XML or AAF) export as a ZIP.

**HTTP Method**: GET

**URL**: `/api/v3/download/timeline/{timelineId}`

**Authentication**: Requires API Key in the request header.

**Authorization**: The edit (clip) referenced by the timeline export must belong to the account associated with the API token.

**Path Parameters**:

| Parameter    | Type   | Description                                                                                                                                                                                                                                           |
| ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `timelineId` | string | The timeline export job identifier returned by [Create Timeline Export](/endpoints-reference/v3/create-timeline-export). It is also the value embedded in the `download_url` returned by [Get Timeline Export](/endpoints-reference/v3/get-timeline). |

**Response**: Redirects (301) to a short-lived **signed** storage URL for the timeline ZIP file.

This is a stable Riverside route that wraps the underlying signed storage link. The signed URL it redirects to is time-limited, so always request this endpoint fresh rather than persisting the redirect target. The `download_url` returned by [Get Timeline Export](/endpoints-reference/v3/get-timeline) points to this endpoint.

**Rate limit**: Once every 1 second.

**Status Codes**:

* `301 Moved Permanently` Redirects to the signed timeline ZIP download URL.
* `401 Unauthorized` Authentication failed (missing or invalid API token).
* `403 Forbidden` The edit does not belong to this account.
* `404 Not Found` Timeline export not found (unknown or malformed `timelineId`).
* `409 Conflict` Timeline export is not ready for download (still `queued` or `processing`, or it `failed`). Poll [Get Timeline Export](/endpoints-reference/v3/get-timeline) until `status` is `done`.
* `410 Gone` Timeline export no longer exists; the export was re-triggered and the prior `timelineId` is stale. Create a new export and use its `timelineId`.
* `429 Too Many Requests` Rate limit exceeded.

### **Sample Request**

```bash theme={null}
GET /api/v3/download/timeline/NjYxOGMyZTRmMmE5YjgwMDEyMzRhYmNkOnByZW1pZXJlOmV4cF8xMjM6MQ HTTP/1.1
Host: platform.riverside.fm
Authorization: Bearer YOUR_API_KEY
```

### **Sample Response**

```
HTTP/1.1 301 Moved Permanently
Location: https://storage.riverside.fm/timeline-exports/.../timeline.zip?signature=...
```

### **Usage Example**

Most HTTP clients will automatically follow the redirect. If you're using curl:

```bash theme={null}
curl -L -H "Authorization: Bearer YOUR_API_KEY" \
  "https://platform.riverside.fm/api/v3/download/timeline/NjYxOGMyZTRmMmE5YjgwMDEyMzRhYmNkOnByZW1pZXJlOmV4cF8xMjM6MQ" \
  -o timeline.zip
```

The `-L` flag tells curl to follow redirects.

<Note>
  The `timelineId` is an opaque token — it already encodes the edit, the target editing application, and the export job, so no other path parameters are needed. Pass it through exactly as returned; do not construct or modify it.
</Note>