---
title: "List the revisions of an edit | GPT-Video API reference"
description: "Lists the revisions of an edit that can be restored, newest first, with who wrote each one and what it did."
url: "https://www.gpt-video.com/developers/api/list-timeline-revisions"
operation: "list_timeline_revisions"
method: "GET"
path: "/v1/projects/{projectId}/timeline/revisions"
scope: "clips:read"
---

Do not assume endpoints have parameters other than the ones explicitly specified.

# List the revisions of an edit

Operation id `list_timeline_revisions`. Request `GET /v1/projects/{projectId}/timeline/revisions`.

Lists the revisions of an edit that can be restored, newest first, with who wrote each one and what it did.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

## About

Call it to find a revision to go back to with restore_timeline (`POST /v1/projects/{projectId}/timeline/restore`). Only the recent revisions of an edit are kept, for a limited time: a revision that is not in this list cannot be restored. The list is newest first and paged with cursor and limit.

## Example use

A reviewer who dislikes the last round of changes lists the revisions of the edit, finds the one from before them by who wrote it and what it did, and keeps its number for restore_timeline (`POST /v1/projects/{projectId}/timeline/restore`).

## Endpoint

```text
GET https://api.gpt-video.com/v1/projects/{projectId}/timeline/revisions
```

- Scope `clips:read`.
- Rate limit 120 requests a minute for each key and 240 for each account, shared by every `read` call. See [rate limits](/developers/rate-limits.md).
- No `Idempotency-Key`.

## Parameters

### Path

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Required | The project id. It starts with prj_. Matches `^prj_[0-9a-f]{20}$`. |

### Query

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | How many items to return, from 1 to 100. Defaults to 20. From 1 to 100. Default `20`. |
| `cursor` | string | Optional | The nextCursor value from the previous page. Leave it out to get the first page. From 1 to 512 characters. |

## Request

List the revisions of an edit.

```bash title="curl"
curl "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);
```

```python title="Python"
import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline/revisions",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
```

```json title="MCP (Full)"
{
  "method": "tools/call",
  "params": {
    "name": "list_timeline_revisions",
    "arguments": {
      "projectId": "prj_b9c1f9c7873dcef51a57"
    }
  }
}
```

## Response

A successful call answers HTTP 200.

### Fields to check

| Name | Type | Description |
| --- | --- | --- |
| `hasMore` | boolean | true when there are more items after this page. |
| `nextCursor` | string or null | Send it as cursor to get the next page. It is null on the last page. |

### Response example

```json title="HTTP 200"
{
  "data": [
    {
      "revision": 3,
      "createdAt": "2026-09-01T11:20:00.000Z",
      "source": "api",
      "summary": "Captions on."
    },
    {
      "revision": 2,
      "createdAt": "2026-09-01T11:15:00.000Z",
      "source": "api",
      "summary": "Captions off."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

**All response fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of objects | Required | The items of this page. |
| `data[].revision` | integer | Required | The revision, to restore with restore_timeline (`POST /v1/projects/{projectId}/timeline/restore`). |
| `data[].createdAt` | string | Required | When the revision was written, in UTC (ISO 8601). |
| `data[].source` | string | Required | Who wrote it: app is someone in the GPT-Video app, api a call of the public API, assistant the Editor Assistant. One of `app`, `api`, `assistant`. |
| `data[].summary` | string | Required | What the change did, in short. |
| `hasMore` | boolean | Required | true when there are more items after this page. |
| `nextCursor` | string or null | Required | Send it as cursor to get the next page. It is null on the last page. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| [`NOT_FOUND`](/developers/errors.md#NOT_FOUND) | 404 | See the error reference. | Change the request, then send it again. |
| [`CONFLICT`](/developers/errors.md#CONFLICT) | 409 | The project is not a Vibe Editing project, or its edit was never prepared. Prepare it with prepare_timeline (`POST /v1/projects/{projectId}/timeline/prepare`) first. | Read the resource again, then decide. Do not send the same request again. |
| [`NOT_READY`](/developers/errors.md#NOT_READY) | 409 | See the error reference. | Wait for Retry-After, then send the same request again. |

Every call can also answer these errors. [`VALIDATION_FAILED`](/developers/errors.md#VALIDATION_FAILED), [`UNKNOWN_PARAMETER`](/developers/errors.md#UNKNOWN_PARAMETER), [`UNAUTHORIZED`](/developers/errors.md#UNAUTHORIZED), [`SCOPE_MISSING`](/developers/errors.md#SCOPE_MISSING), [`RATE_LIMITED`](/developers/errors.md#RATE_LIMITED), [`INTERNAL`](/developers/errors.md#INTERNAL), [`UNAVAILABLE`](/developers/errors.md#UNAVAILABLE).

## Cost

No credits are used.

## Related operations

- [`restore_timeline`](/developers/api/restore-timeline.md) (`POST /v1/projects/{projectId}/timeline/restore`) Restore a revision of an edit
- [`get_timeline`](/developers/api/get-timeline.md) (`GET /v1/projects/{projectId}/timeline`) Get an edit
- [`apply_timeline_operations`](/developers/api/apply-timeline-operations.md) (`POST /v1/projects/{projectId}/timeline/operations`) Change an edit

## Questions

### Why is an older revision missing?

Only the recent revisions of an edit are kept, for a limited time. A revision that is not listed cannot be restored; read the edit with get_timeline (`GET /v1/projects/{projectId}/timeline`) and change it with apply_timeline_operations (`POST /v1/projects/{projectId}/timeline/operations`) instead.

### Are changes made in the GPT-Video app listed too?

Yes. Every change of the edit is listed, with source app for someone in the GPT-Video app, api for a call of the public API and assistant for the Editor Assistant.