Get movie status

GET https://api.json2video.com/v2/movies

Retrieves the status and metadata of a single project, or lists all projects for the authenticated account.

Request

Headers

Header	Required	Value
`x-api-key`	yes	API key issued from the dashboard.

Query parameters

Parameter	Type	Description
`project`	string	16-character project identifier. When present, returns a single movie.
`id`	string	Alias for `project`.
`format`	string	`simple` removes the original `json` payload from the response.
`date_start` / `from`	ISO-8601	List mode: start of date range. Default: first day of current month.
`date_end` / `to`	ISO-8601	List mode: end of date range. Default: end of current day. Maximum range: 93 days.
`limit`	integer	List mode: page size, 1–100. Default: 100.
`next_token`	string	List mode: pagination cursor returned in the previous response.

Body

None.

Response

200 OK — single project

{
  "success": true,
  "movie": {
    "success": true,
    "status": "done",
    "message": "",
    "project": "JkGxEoPRF9EgRb32",
    "url": "https://assets.json2video.com/clients/xxxxxxxx/renders/2026-05-12-36066.mp4",
    "thumbnail": "https://assets.json2video.com/clients/xxxxxxxx/renders/2026-05-12-36066.jpg",
    "ass": "https://assets.json2video.com/clients/xxxxxxxx/renders/2026-05-12-36066.ass",
    "created_at": "2026-05-12T07:41:41.946Z",
    "ended_at": "2026-05-12T07:44:57.108Z",
    "duration": 108.2,
    "size": 6876189,
    "width": 1080,
    "height": 1920,
    "rendering_time": 195,
    "client-data": {},
    "consumed_credits": []
  },
  "remaining_quota": { "movies": 0, "drafts": 0, "time": 1807 }
}

200 OK — list of projects

{
  "success": true,
  "from": "2026-05-01T00:00:00.000Z",
  "to":   "2026-05-12T23:59:59.999Z",
  "count": 25,
  "limit": 100,
  "has_next": false,
  "has_prev": false,
  "next_token": null,
  "movies": [ { "...": "movie object as above" } ],
  "remaining_quota": { "time": 1807 }
}

Status enum

Status	Meaning
`pending`	Job is queued. No worker has picked it up yet.
`running`	Render is in progress.
`done`	Render finished successfully. `url` is the final MP4.
`error`	Render failed. `message` carries the reason.
`timeout`	Computed client-side when `status=running` and `created_at` is older than 15 minutes. The server still keeps `status=running` internally; clients should treat `timeout` the same as a fatal error.

Movie object fields

Field	Type	Notes
`success`	boolean	`true` iff the render itself succeeded.
`status`	string	See status enum.
`message`	string	Error message when `success=false`; informational otherwise.
`project`	string	16-character project ID.
`url`	string\|null	Public URL of the rendered MP4. `null` until done, and again once the video file is gone.
`thumbnail`	string\|null	Public URL of the movie thumbnail — a single frame taken 2 seconds in, or at the timecode set by the movie's `thumbnail` property. JPEG, or PNG for movies with a transparent background. `null` until done, and again once the file is gone.
`ass`	string\|boolean	Public URL of the generated `.ass` subtitle file, if any; `false` if none.
`created_at`	string	ISO-8601 submission time.
`ended_at`	string\|null	ISO-8601 completion time. `null` until done.
`deleted_at`	string\|null	ISO-8601 time the video file was deleted through `DELETE /v2/movies`; `null` otherwise. The entry itself, including `consumed_credits`, is kept.
`duration`	number	Output duration in seconds.
`size`	number	Output size in bytes.
`width` / `height`	integer	Output pixel dimensions.
`rendering_time`	integer\|null	Seconds between `created_at` and `ended_at`.
`client-data`	object	The `client-data` from the submitted Movie JSON, returned verbatim.
`consumed_credits`	array	Per-step credit consumption breakdown. Present for movies created after 2025-07-27.

Errors

Status	Message	Cause
`400`	`Project ID must be a 16-character string. Received ID: '…' (length: N)`	`project` / `id` is wrong shape.
`400`	`Invalid start date`	`date_start` / `from` is not parseable.
`400`	`Invalid end date`	`date_end` / `to` is not parseable.
`400`	`Maximum date range is 3 months.`	Range exceeds 93 days.
`403`	`Invalid token`	Admin-only query parameter without a valid token.

A project that has not been found by the database returns a 200 with movie.status = "error" and a descriptive message.

Examples

Poll a single project

curl --location --request GET \
  'https://api.json2video.com/v2/movies?project=JkGxEoPRF9EgRb32' \
  --header 'x-api-key: YOUR_API_KEY'

List the last 50 projects

curl --location --request GET \
  'https://api.json2video.com/v2/movies?limit=50&date_start=2026-04-12&date_end=2026-05-12' \
  --header 'x-api-key: YOUR_API_KEY'

Paginate

# First page
curl 'https://api.json2video.com/v2/movies?limit=100' -H 'x-api-key: …'
# Subsequent pages: pass the previous response's `next_token`
curl 'https://api.json2video.com/v2/movies?limit=100&next_token=AAA…' -H 'x-api-key: …'

Get movie status#

Request#

Headers#

Query parameters#

Body#

Response#

200 OK — single project#

200 OK — list of projects#

Status enum#

Movie object fields#

Errors#

Examples#

Poll a single project#

List the last 50 projects#

Paginate#