Get an Editor Assistant turn

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

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.
• No Idempotency-Key.

Parameters

Path

Query

Request

Get a finished turn.

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

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);

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)

{
  "method": "tools/call",
  "params": {
    "name": "get_assistant_turn",
    "arguments": {
      "turnId": "agm_1e3d5feef4076b4329cf"
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Assistant turn object in turn.

Fields to check

Response example

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

Related operations

• create_assistant_turn (POST /v1/projects/{projectId}/assistant/turns) Send a message to the Editor Assistant
• list_assistant_turns (GET /v1/projects/{projectId}/assistant/turns) List the Editor Assistant turns of a project
• undo_assistant_action (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.

View as Markdown