Guide
Jobs & files
Job statuses, long-running jobs, canceling, downloads, reading text outputs and chaining one job into the next.
Statuses
Every run is a job. Creating one returns 202 with the job; a job whose status is succeeded, failed, canceled or expired is final and does not change again.
- queued
- Accepted, waiting to start.
- running
- Being processed.
- succeeded
- Done: result.files has the download URLs.
- failed
- Stopped with an error: see error.code, error.message and error.hint.
- canceled
- Canceled. Cleanup or a credit refund may still be pending.
- expired
- The queued job was not picked up before its start deadline. Output retention is separate.
The job object
GET /v1/jobs/{id} (MCP get_job) returns the job. Its fields, in the order the API sends them:
- id, tool, status
- The job's id (j_…), the tool it runs, and where it is in its life.
- input
- The input file's name and bytes, and how it was sent (source).
- input_kind
- file or parameters. Present on long-running jobs and on jobs that take only parameters.
- workflow, capabilities
- Progress and cancellation, on long-running jobs (below).
- options
- The options the job runs with, defaults filled in and capped by your plan.
- error
- null, or {code, message, hint} when the job failed.
- result
- null until the job succeeds; then files and the tool's summary.
- compute_ms
- Processing time in milliseconds.
- credits_charged
- What the job cost: null until known, 0 once a failed job's charge went back.
- created_at, started_at, finished_at
- Timestamps (ISO 8601).
- outputs_expire_at
- When the job's results are deleted.
Waiting for a job
Poll GET /v1/jobs/{id} every few seconds until the status is final. Over MCP, the tool call and get_job wait up to wait_seconds (at most 45) for you. Keep the job id: it stays valid until the outputs expire. GET /v1/jobs lists your recent jobs, newest first: ?tool= keeps one tool's, and ?status= the jobs in the listed statuses (comma-separated, e.g. queued,running).
Don't start the same job again while one runs: each job is charged. Retry with the same idempotency key instead.
Long-running jobs
Some jobs take minutes and must finish within an hour of being created, queueing included: Create a 3D model, Create an image, Create a 3D model from an image, Optimize a 3D model. Their job adds:
- workflow.stage
- What is happening now, in a few words.
- workflow.deadline
- When the job must have finished.
- workflow.cancel_pending
- A cancellation was requested and cleanup is still running.
- workflow.refund_pending
- The charge is being returned.
- capabilities.can_cancel
- Whether the job can be canceled now.
Canceling
Cancel with POST /v1/jobs/{id}/cancel or MCP cancel_job. For long-running jobs, check capabilities.can_cancel first. Cancellation prevents later work, but work already running may take time to stop: workflow.cancel_pending and workflow.refund_pending show what is left. A canceled long-running job is refunded. Other jobs omit that capability field and can be canceled only while queued.
Repeating a cancellation is safe and never deletes completed results. DELETE /v1/jobs/{id} cancels a queued job, or deletes a finished job and its files.
Results and downloads
A succeeded job lists its files in result.files, each with a download url. URLs are valid for up to 24 hours; fetch the job again for fresh ones. outputs_expire_at is the result-retention deadline, and an output's url_expires_at, when present, is its download-link deadline. Delete results sooner with DELETE /v1/jobs/{id}.
Reading text outputs
Text outputs (.txt .json .md .csv) can be read in chunks without downloading them: GET /v1/jobs/{id}/files/{name}?offset=&limit= (MCP read_job_file) returns text and the next_offset to continue from, until eof. A chunk is up to 20,000 bytes by default and 100,000 at most, and never splits a character. Other files are downloaded from their url.
Chaining jobs
Some tools take job_file: an output of one of your own completed jobs, passed as {job_id, name} while it has not expired. It is copied into the new job, with no download in between. These tools take it: Create a 3D model from an image, Optimize a 3D model. For the other file tools, download the output and upload it.
Each tool's page lists the tools that feed it or take its outputs, under Related tools.
Output files by tool
- create_3d_model
- model.glb · model.web.glb · reference.png · generation.json
- create_image
- image.png · generation.json
- create_3d_model_from_image
- model.glb · model.web.glb · generation.json
- optimize_3d_model
- model.glb · generation.json
- simplify_3d_model
- model.glb · simplify.json · model.web.glb
- split_3d_model
- manifest.json · segmented.glb · meshes/part_NNN.glb · collision/part_NNN.glb · metadata/face_to_part.bin · <model>_parts.zip
- inspect_3d_model
- summary.txt · inspection.json
- extract_pdf
- text.txt · pages.json
- get_random_numbers
- numbers.json · numbers.txt