Jobs

Every tool or Run FFmpeg request creates a job and returns it right away with status 202, even when the job has already finished.

Waiting and polling

Add ?wait=<seconds> to hold the request open while the job runs. The value is capped at 25, and anything else counts as 0. The response returns as soon as the job finishes, or when the wait ends, whichever comes first.

Without wait, or if the job takes longer than the wait, you get the job while it is still queued or running. Check again with its id:

curl "https://api.mediatofu.com/v1/jobs/job_0123456789abcdef01234567" \
  -H "Authorization: Bearer $MEDIATOFU_API_KEY"

Poll every few seconds until the status is succeeded or failed, or use a webhook on a paid plan. You can only read your own jobs: any other id returns 404 with Job not found.

Statuses

Status	Meaning
`queued`	Accepted, waiting for a container.
`running`	Files are being copied in, or FFmpeg is running.
`succeeded`	FFmpeg exited with code 0. Outputs are ready, except for `probe`, which has none.
`failed`	The job did not finish. `error` says why.

Jobs are not retried automatically, because a job may already have used compute. A job still queued or running after 20 minutes is marked failed and isn't charged.

Response fields

Field	Type	Description
`id`	string	The job id.
`tool`	string	The tool name, or `ffmpeg` for Run FFmpeg.
`status`	string	One of the statuses above.
`compute_seconds`	number	Billed compute, rounded up to a whole second, at least 1. `0` until the job finishes, or if it isn't charged.
`compute_ms`	number or null	How long FFmpeg ran, in milliseconds. `null` until it has run.
`outputs`	array	`name`, `size` in bytes, and a download `url` for each output. Empty until the job succeeds.
`result`	any	Present when the tool produced data, such as `probe`'s JSON.
`error`	string	Present when the job failed.
`exit_code`	number	FFmpeg's exit code, once it has run.
`log`	string	The last 16 KB of FFmpeg's log. Present only when the job failed.
`created_at`	string	ISO 8601 time the job was accepted.
`finished_at`	string	ISO 8601 time the job ended. Absent until then.

Sample responses

These are examples. Ids and tokens are placeholders.

A job that succeeded:

{
  "id": "job_0123456789abcdef01234567",
  "tool": "ffmpeg",
  "status": "succeeded",
  "compute_seconds": 7,
  "compute_ms": 6412,
  "outputs": [
    {
      "name": "small.mp4",
      "size": 18350412,
      "url": "https://api.mediatofu.com/o/0123456789abcdef0123456789abcdef/job_0123456789abcdef01234567/small.mp4"
    }
  ],
  "exit_code": 0,
  "created_at": "2026-01-15T10:42:03Z",
  "finished_at": "2026-01-15T10:42:13Z"
}

A job still waiting:

{
  "id": "job_0123456789abcdef01234567",
  "tool": "compress",
  "status": "queued",
  "compute_seconds": 0,
  "compute_ms": null,
  "outputs": [],
  "created_at": "2026-01-15T10:44:51Z"
}

A job that failed:

{
  "id": "job_0123456789abcdef01234567",
  "tool": "ffmpeg",
  "status": "failed",
  "compute_seconds": 1,
  "compute_ms": 86,
  "outputs": [],
  "error": "ffmpeg exited with code 1. See log.",
  "exit_code": 1,
  "log": "Unrecognized option 'crfx'.\nError splitting the argument list: Option not found\n",
  "created_at": "2026-01-15T10:50:11Z",
  "finished_at": "2026-01-15T10:50:12Z"
}

Why a job fails

`error`	Charged?
`ffmpeg exited with code <n>. See log.`	Yes, for the compute used.
`Stopped at your plan's <n> second limit.`	Yes, for the compute used.
`FFmpeg finished but didn't write <name>.`	Yes, for the compute used.
`File <id> not found, or it has expired.`	No
`Couldn't download <url>: ...`	No
`Input is larger than your plan allows.`	No
`This account is suspended and can't run jobs.`	No
`Something went wrong on our side. You weren't charged.`	No

How a job runs

Each job runs alone in a container that is started for that job:

A new container starts for the job.
Your input files are copied in.
FFmpeg runs with no internet access and no secrets.
Your output files are saved.
The container is destroyed.

Compute is measured only while FFmpeg runs, so queueing and copying files aren't counted. See Plans and limits.

Waiting and pollingCopy Anchor Link

StatusesCopy Anchor Link

Response fieldsCopy Anchor Link

Sample responsesCopy Anchor Link

Why a job failsCopy Anchor Link