---
title: "Get a clip | GPT-Video API reference"
description: "Returns one clip with its place in the source video, its score and the copy suggested for posting it."
url: "https://www.gpt-video.com/developers/api/get-clip"
operation: "get_clip"
method: "GET"
path: "/v1/clips/{clipId}"
scope: "clips:read"
---

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

# Get a clip

Operation id `get_clip`. Request `GET /v1/clips/{clipId}`.

Returns one clip with its place in the source video, its score and the copy suggested for posting it.

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

Use it to read a clip again after list_clips (`GET /v1/projects/{projectId}/clips`), for example to check its status before you accept or reject it. Analyzing the project again removes the proposed and rejected clips, so their ids then answer NOT_FOUND; accepted clips are kept with their ids.

## Example use

A review tool shows one clip in a detail view. Before it sends the accept or the reject, it reads the clip again and checks its status, in case a colleague decided on it in the meantime.

## Endpoint

```text
GET https://api.gpt-video.com/v1/clips/{clipId}
```

- 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 |
| --- | --- | --- | --- |
| `clipId` | string | Required | The id of the clip, as list_clips (`GET /v1/projects/{projectId}/clips`) returns it. Matches `^cnd_[0-9a-f]{20}$`. |

## Request

Get a clip.

```bash title="curl"
curl "https://api.gpt-video.com/v1/clips/cnd_2b7f4e91a0c84d35e6f0" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
```

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/clips/cnd_2b7f4e91a0c84d35e6f0", {
  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/clips/cnd_2b7f4e91a0c84d35e6f0",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
```

```json title="MCP (Full)"
{
  "method": "tools/call",
  "params": {
    "name": "get_clip",
    "arguments": {
      "clipId": "cnd_2b7f4e91a0c84d35e6f0"
    }
  }
}
```

## Response

A successful call answers HTTP 200. Returns a [Clip object](/developers/objects.md#clip) in `clip`.

### Fields to check

| Name | Type | Description |
| --- | --- | --- |
| `clip.id` | string | The clip id. It starts with cnd_. |
| `clip.status` | string | proposed is waiting for a decision, accepted has a composition, rejected was set aside and can be restored. |

### Response example

```json title="HTTP 200"
{
  "clip": {
    "id": "cnd_2b7f4e91a0c84d35e6f0",
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "summary": "The founder explains how the first customer paid before the product existed.",
    "reason": "A clear claim in the first seconds and a result at the end.",
    "tags": [
      "startups",
      "sales"
    ],
    "createdAt": "2026-09-01T09:40:00.000Z",
    "status": "proposed",
    "rank": 1,
    "startSec": 300,
    "endSec": 330,
    "durationSec": 30,
    "title": "The first customer",
    "hook": "Our first customer changed everything",
    "score": 81,
    "scoreBreakdown": [
      {
        "factor": "hook",
        "label": "Hook (first 3 seconds)",
        "score": 8,
        "note": "Opens on a concrete claim."
      },
      {
        "factor": "payoff",
        "label": "Payoff / ending",
        "score": 7,
        "note": "Ends on the result."
      },
      {
        "factor": "clarity",
        "label": "Clarity",
        "score": 6,
        "note": "One idea, said plainly."
      },
      {
        "factor": "emotion",
        "label": "Emotion",
        "score": 8,
        "note": "The speaker sounds surprised."
      },
      {
        "factor": "novelty",
        "label": "Novelty / surprise",
        "score": 7,
        "note": "Not the usual advice."
      },
      {
        "factor": "selfContained",
        "label": "Self-contained",
        "score": 6,
        "note": "Needs no context."
      },
      {
        "factor": "quotability",
        "label": "Quotability",
        "score": 8,
        "note": "Has a line people repeat."
      },
      {
        "factor": "dialogue",
        "label": "Dialogue (back-and-forth)",
        "score": 7,
        "note": "A single speaker."
      }
    ],
    "transcriptExcerpt": "before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that",
    "social": {
      "title": "The first customer",
      "caption": "How a first customer paid before there was a product.",
      "hashtags": [
        "#startup",
        "#founder"
      ]
    },
    "compositionId": null
  }
}
```

**All response fields**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `clip` | Clip object | Required | Described in [Clip object](/developers/objects.md#clip). |

**More examples**

#### A clip that does not exist

`GET /v1/clips/cnd_4c8e0a2f6d1b49e7a3c5`

```json title="HTTP 404"
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Clip cnd_4c8e0a2f6d1b49e7a3c5 not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_2c9f4a1e7b0d43c58e6a1f20"
  }
}
```

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| [`NOT_FOUND`](/developers/errors.md#NOT_FOUND) | 404 | A clip that does not exist | Change the request, then send it 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

- [`list_clips`](/developers/api/list-clips.md) (`GET /v1/projects/{projectId}/clips`) List the clips of a project
- [`accept_clip`](/developers/api/accept-clip.md) (`POST /v1/clips/{clipId}/accept`) Accept a clip
- [`reject_clip`](/developers/api/reject-clip.md) (`POST /v1/clips/{clipId}/reject`) Reject a clip
- [`delete_composition`](/developers/api/delete-composition.md) (`DELETE /v1/compositions/{compositionId}`) Delete a composition

## Questions

### Why does a clip I listed before answer NOT_FOUND now?

The project was analyzed again, and the new analysis replaced the proposed and rejected clips with new ones. List the clips again to get their new ids.

### Does reading a clip use credits?

No. Reading a clip uses no credits; it counts as one read against the rate limit of the key.