---
title: "Get an Editor Assistant turn | GPT-Video API reference"
description: "Returns a turn of the Editor Assistant: its status, its reply and the actions it took."
url: "https://www.gpt-video.com/developers/api/get-assistant-turn"
operation: "get_assistant_turn"
method: "GET"
path: "/v1/assistant/turns/{turnId}"
scope: "clips:read"
---

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

# Get an Editor Assistant turn

Operation id `get_assistant_turn`. Request `GET /v1/assistant/turns/{turnId}`.

Returns a turn of the Editor Assistant: its status, its reply and the actions it took.

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 this to follow a turn. While it is queued or running, add ?wait= with up to 25 seconds to hold the request until it ends, then call again if it is still working. A finished turn has its reply and its actions in order; an action that can be undone has undoable set to true, for undo_assistant_action (`POST /v1/assistant/turns/{turnId}/actions/{actionId}/undo`). When outcome is needs_input, the Editor Assistant asks a question: answer it with a new create_assistant_turn (`POST /v1/projects/{projectId}/assistant/turns`). A failed or cancelled turn says what happened in errorMessage.

## Example use

A tool that sent a request to the Editor Assistant calls this with ?wait= until the turn is done. It shows the reply to the user, lists the actions the Editor Assistant took, and offers an undo for each action whose undoable is true.

## Endpoint

```text
GET https://api.gpt-video.com/v1/assistant/turns/{turnId}
```

- 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 |
| --- | --- | --- | --- |
| `turnId` | string | Required | The id of the turn, as create_assistant_turn (`POST /v1/projects/{projectId}/assistant/turns`) or list_assistant_turns (`GET /v1/projects/{projectId}/assistant/turns`) returned it. It starts with agm_. Matches `^agm_[0-9a-f]{20}$`. |

### Query

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `wait` | integer | Optional | Seconds to hold the request while the work is still running, up to 25. Leave it out to answer at once. If many requests of the account are already waiting, it answers at once; wait a few seconds before you read again. From 0 to 25. |

## Request

Get a finished turn.

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

```ts title="TypeScript"
const res = await fetch("https://api.gpt-video.com/v1/assistant/turns/agm_1e3d5feef4076b4329cf", {
  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/assistant/turns/agm_1e3d5feef4076b4329cf",
    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_assistant_turn",
    "arguments": {
      "turnId": "agm_1e3d5feef4076b4329cf"
    }
  }
}
```

## Response

A successful call answers HTTP 200. Returns a [Assistant turn object](/developers/objects.md#assistant-turn) in `turn`.

### Fields to check

| Name | Type | Description |
| --- | --- | --- |
| `turn.id` | string | The turn id. It starts with agm_. |
| `turn.status` | string | queued and running are still working; done, failed and cancelled are final. |
| `turn.actions[].id` | string | The action id. It starts with tc_. |
| `turn.actions[].status` | string |   |
| `turn.jobId` | string or null | The job that runs the turn; null once it is gone. |

### Response example

```json title="HTTP 200"
{
  "turn": {
    "id": "agm_1e3d5feef4076b4329cf",
    "projectId": "prj_b9c1f9c7873dcef51a57",
    "status": "done",
    "message": "Make the captions bolder.",
    "reply": "I switched the captions to the bold karaoke style.",
    "outcome": "done",
    "question": null,
    "options": [],
    "actions": [
      {
        "id": "tc_6c98ac1c068fc322b284",
        "tool": "set_captions",
        "status": "done",
        "summary": "Captions: bold karaoke",
        "undoable": true,
        "creditsReturned": 0
      }
    ],
    "jobId": "job_0724f7cc56c41f889a0c",
    "errorMessage": null,
    "createdAt": "2026-08-31T22:31:00.000Z",
    "finishedAt": "2026-08-31T22:32:00.000Z"
  }
}
```

**All response fields**

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

**More examples**

#### Wait for a turn to finish

`GET /v1/assistant/turns/agm_1e3d5feef4076b4329cf?wait=25`

```json title="HTTP 200"
{
  "turn": {
    "id": "agm_1e3d5feef4076b4329cf",
    "projectId": "prj_b9c1f9c7873dcef51a57",
    "status": "done",
    "message": "Make the captions bolder.",
    "reply": "I switched the captions to the bold karaoke style.",
    "outcome": "done",
    "question": null,
    "options": [],
    "actions": [
      {
        "id": "tc_6c98ac1c068fc322b284",
        "tool": "set_captions",
        "status": "done",
        "summary": "Captions: bold karaoke",
        "undoable": true,
        "creditsReturned": 0
      }
    ],
    "jobId": "job_0724f7cc56c41f889a0c",
    "errorMessage": null,
    "createdAt": "2026-08-31T22:31:00.000Z",
    "finishedAt": "2026-08-31T22:32:00.000Z"
  }
}
```

#### A turn that does not exist

`GET /v1/assistant/turns/agm_d9b2bd74e63ed17b84bb`

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

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| [`NOT_FOUND`](/developers/errors.md#NOT_FOUND) | 404 | A turn 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

- [`create_assistant_turn`](/developers/api/create-assistant-turn.md) (`POST /v1/projects/{projectId}/assistant/turns`) Send a message to the Editor Assistant
- [`list_assistant_turns`](/developers/api/list-assistant-turns.md) (`GET /v1/projects/{projectId}/assistant/turns`) List the Editor Assistant turns of a project
- [`undo_assistant_action`](/developers/api/undo-assistant-action.md) (`POST /v1/assistant/turns/{turnId}/actions/{actionId}/undo`) Undo an action of the Editor Assistant

## Questions

### How do I wait for a turn without polling in a tight loop?

Send ?wait=25. The request is held until the turn ends or 25 seconds pass, whichever comes first, and then answers the turn as it is. If many requests of the account are already waiting, it answers at once instead; wait a few seconds before you read again.

### What do the outcomes mean?

done means the Editor Assistant did what was asked, partial that it did part of it, blocked that it could not, and needs_input that it asks a question, with the answers it offers in options.