Get a job

About

Call this to follow the work another call started. analyze_project (POST /v1/projects/{projectId}/analyze) and the build calls return their job, and so do the import of a video from a link and the story and voice calls of a fake text project; a tool run, an Editor Assistant turn and a composition's framing carry the id of their job. While the job 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 job that failed or stopped says what happened in errorMessage. A finished import job gives the new video in assetId. A tool job gives its run in toolRunId, to read with get_tool_run (GET /v1/tool-runs/{toolRunId}), and an assistant_turn job gives its turn in turnId, to read with get_assistant_turn (GET /v1/assistant/turns/{turnId}). An export is easier to follow with get_export (GET /v1/exports/{exportId}), which also gives its download link; an export id (rnd_) is not a job id here.

Example use

A script that started an analysis keeps the job id from analyze_project (POST /v1/projects/{projectId}/analyze), calls get_job (GET /v1/jobs/{jobId}) with ?wait= until the job ends, and then reads the clips with list_clips (GET /v1/projects/{projectId}/clips) or reads errorMessage when the job failed.

Endpoint

GET https://api.gpt-video.com/v1/jobs/{jobId}

• 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 analysis.

curl "https://api.gpt-video.com/v1/jobs/job_6c1e8b4a2f0d4a97e3b5" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

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

{
  "method": "tools/call",
  "params": {
    "name": "wait_for_job",
    "arguments": {
      "jobId": "job_6c1e8b4a2f0d4a97e3b5"
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Job object in job.

Fields to check

Response example

{
  "job": {
    "id": "job_6c1e8b4a2f0d4a97e3b5",
    "kind": "analysis",
    "status": "done",
    "progress": 1,
    "errorMessage": null,
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "compositionId": null,
    "exportId": null,
    "assetId": null,
    "toolRunId": null,
    "turnId": null,
    "createdAt": "2026-09-01T09:11:00.000Z",
    "startedAt": "2026-09-01T09:12:00.000Z",
    "finishedAt": "2026-09-01T09:40:00.000Z"
  }
}

{
  "job": {
    "id": "job_a3e9d05c7b1f4e2896d4",
    "kind": "export",
    "status": "done",
    "progress": 1,
    "errorMessage": null,
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "compositionId": "cmp_4e8c2a6f09d14b73a1e5",
    "exportId": "rnd_0f6b3e9d2c7a4158b4a3",
    "assetId": null,
    "toolRunId": null,
    "turnId": null,
    "createdAt": "2026-09-01T10:10:00.000Z",
    "startedAt": "2026-09-01T10:11:00.000Z",
    "finishedAt": "2026-09-01T10:15:00.000Z"
  }
}

{
  "job": {
    "id": "job_6c1e8b4a2f0d4a97e3b5",
    "kind": "analysis",
    "status": "done",
    "progress": 1,
    "errorMessage": null,
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "compositionId": null,
    "exportId": null,
    "assetId": null,
    "toolRunId": null,
    "turnId": null,
    "createdAt": "2026-09-01T09:11:00.000Z",
    "startedAt": "2026-09-01T09:12:00.000Z",
    "finishedAt": "2026-09-01T09:40:00.000Z"
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Job job_8d4b2f6a0e9c41b7d5f1 not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_4d8b1f6a3c0e7b2d9a5f1e63"
  }
}

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

• analyze_project (POST /v1/projects/{projectId}/analyze) Analyze a project
• get_export (GET /v1/exports/{exportId}) Get an export
• get_composition (GET /v1/compositions/{compositionId}) Get a composition
• get_project (GET /v1/projects/{projectId}) Get a project
• reframe_composition (POST /v1/compositions/{compositionId}/reframe) Frame a composition again
• create_export (POST /v1/compositions/{compositionId}/exports) Export a composition

Questions

Which jobs can I read?

The analysis of an Auto Clip project or the preparation of a Vibe Editing project (kind analysis), the build of a split screen, streamer or Reddit story video (kind build), the export of a composition (kind export), the face framing of a clip (kind framing), the import of a video from a link (kind import), the story of a fake text project (kind story) and its voices (kind voices), a voiceover, an audio separation or a brainstorm (kind tool), and a turn of the Editor Assistant (kind assistant_turn). Other work the GPT-Video app does in the background is not a job of the API.

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

Send ?wait=25. The request is held until the job ends or 25 seconds pass, whichever comes first, and then answers the job 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.

Can I pass an export id (rnd_) here?

No: the call answers 400, because only job ids (job_) are accepted, and the error names get_export (GET /v1/exports/{exportId}). Follow an export with get_export, which also gives its download link.

View as Markdown