Jobs

The job tools let an assistant follow the work Nodaro does for it. Almost every generation tool starts a job and returns its id at once. get_job and wait_for_job report when the job finishes and where the result is. list_jobs lists and filters your recent jobs, rate_job rates a result, and diagnose_run explains a failure. None of them costs credits.

Job statuses

A held job ends as completed when the reviewer approves it, or as failed with a policy reason when the reviewer rejects it. A client that follows the job through the MCP tasks API sees a held job as input_required: the decision belongs to the reviewer, so do not ask the user for new parameters.

The job envelope

get_job and wait_for_job return the same structured result, the job envelope. get_asset returns it too, without input and without the two credit figures.

creditsCharged can be lower than credits. It includes the steps the job ran: a job that runs other jobs for you, such as a Nodaro Motion run's reference preparation, mask and video, is charged for each step once the step settles. When the job's own hold was refunded, it is 0 plus any settled steps. For example, a refunded Nodaro Motion run whose reference and mask steps were charged reads credit_status: "refunded" with creditsCharged: 165. It is null while the job's own hold is still open, when nothing in the run was reserved, or when its steps could not be read for a moment. That null means unknown, never a lower figure.

creditsHeld is the run's hold, the steps' holds included. creditsReleased is what went back once every hold in the run settled, and it is null until then. For example, a job that held 888 credits and settled at 444 reads credits: 888, creditsCharged: 444, creditsHeld: 888 and creditsReleased: 444.

width and height are present on image jobs completed after Nodaro began to record the size, and on Image Overlay, Video Overlay, Video Mask and Mask Composite jobs. For an image, they are the size of outputUrl as stored, with its EXIF rotation applied. Read them to choose an aspect ratio for the next step. A job that made several images also has outputData.images, with { url, width, height } for each image.

input is a safe subset of the request, enough to check what the model received. Nothing outside this list is included:

• prompt, the prompt as rendered, after pickers, subjects and references were folded in, and userPrompt, your own words.
• negativePrompt, and the direction and subject picker ids.
• provider, model, duration, resolution and aspectRatio.
• imageUrl, endFrameUrl, and the reference image, video and audio URLs.
• The job type.

get_job

Returns one of your jobs by id, as the job envelope. Use it to check a job every 5 to 10 seconds until it finishes.

Permission: jobs:read. Credits: free.

Returns: the job envelope.

wait_for_job

Blocks until one of your jobs finishes, then returns the job envelope. Use it instead of a tight loop of get_job calls.

Permission: jobs:read. Credits: free.

Returns: the job envelope. Each call answers within 45 seconds, because MCP clients end a tool call on their own clock, often at 60 seconds. When the job is still running then, the status is timeout, with the job's progress, jobType, createdAt and startedAt. That is not an error: call wait_for_job again with the same job_id. The wait goes on where it stopped, and the job is not affected, so never run the generation again. A video can take 2 to 10 minutes, so expect several calls, or poll get_job every 5 to 10 seconds. A held job answers pending_review at once.

list_jobs

Lists your recent jobs as structured data: status, type, output URL, error, credits and timestamps. Use it for questions such as "how many generations failed yesterday". When the user wants to see the results, use browse_gallery, which shows a grid.

Permission: jobs:read. Credits: free.

Returns: a page of jobs and a next_cursor for the next page.

The public scope lists what the public gallery shows, with the same moderation as browse_gallery, and never carries another creator's id. In either scope, a page can hold fewer jobs than limit and still carry a next_cursor. Keep following it until it is null.

On a deployment that does not allow public work (outputs.allowPublic: false), the public scope lists nothing: { "data": [], "next_cursor": null }.

On your own jobs, the filters work as on GET /v1/jobs and combine with AND. types lifts the default kinds, so a job with no media, such as an llm-structured draft, is listed. Pass kinds as well to keep only media. types, sources, favorited, rating, project_id, in_session and with_sessions are refused with scope: "public". A deleted job is never listed: it is in list_trash.

Each of your own jobs carries favorited (true or false) and rating ("good", "bad" or null). Both are left out when they cannot be read for a moment, which means unknown, not false. Rows in the public scope carry neither.

Each of your own jobs carries credits, the amount the job itself held when it was accepted, which never changes, and credits_charged, what it cost once the hold settled, the steps it ran included. A job can settle below its hold, and the rest goes back to your balance. credits_charged is 0 plus any settled steps when the run's own hold was refunded. It is null while the job's own hold is still open, when nothing in the run was reserved, or when its steps could not be read for a moment. credits_held is the run's hold with its steps' holds, and credits_released is what went back once every hold in the run settled (null until then). To total what jobs cost, add up credits_charged, not credits. Rows in the public scope carry none of the three.

Your own jobs include your Apply EDL renders, under the kind of their output: video for a cut and audio for a mix. A Preview carries preview: true. The public scope never lists an Apply EDL render.

rate_job

Rates one of your jobs good or bad, or clears its rating. A job has one rating, and only its owner can rate it. Another person's job, or an id that is not a job, answers "not found".

Permission: assets:write. Credits: free.

Returns: { data: { jobId, rating } }. The rating shows on list_jobs, which can filter by it, and on GET /v1/jobs.

diagnose_run

Explains why a workflow run or a single job failed. Pass either id: the tool tries a workflow run first and falls back to a job.

Permission: jobs:read. Credits: free.

Returns: for a workflow run, every node with its job id, type and status (nodes). This is the only tool that maps the nodes of a run to their job ids. Each failed node also carries its error message, its model, the credits actually charged (creditsActual), a failure class and a hint on how to fix it. It also carries the model service's own words as providerReason, when it gave any and you may read them. A failed run that run_workflow can continue also carries resumeHint, the run_workflow call that continues it from where it stopped. A failed app run carries the retry_app_run call instead, as in get_app_run.

Whose words a failure carries

The model service's words for a failure belong to the job's owner. errorDetail and providerReason are left out, or null, in these cases:

• get_asset on another user's public job, and list_jobs with scope: "public". Neither returns that user's id either.
• A job of a workflow run whose workflow you cannot open, such as someone else's share link or published app that you ran. This holds on get_job, wait_for_job, list_jobs, get_asset and diagnose_run.
• A deployment that keeps these words for its administrators. An MCP session never reads as an administrator's.

The class is a best guess from the error text, so treat it as guidance. Reserved credits are refunded automatically for every class except post_processing, because in that case the model already delivered its work.

A completed run also reports its outcome, "succeeded" or "nothing_new", as get_app_run does. A node the run skipped because nothing reached its input carries skipReason: "empty_input". A run that found nothing new has no failure to explain: nothing went wrong, and there was nothing to work on.

When a job fails

1. Read retryable. false means the same request will fail again unchanged. That happens after a content policy block, or when the model refused the combination of settings and input media. A refusal where the model gave no reason is retryable: true.
2. Follow suggestedProvider. When a safety filter blocked the result and the catalog has a fallback model, the job names it. Run the same prompt and references on that model instead of guessing another one.
3. Change the request when the model refused it. An error that says the model rejected these settings means the duration, aspect ratio, resolution or a reference file does not fit that model. Change them, or pick a model whose capability sheet in list_models allows the combination. An error that says the model gave no reason can be temporary, or caused by the input media, such as its size or format. Run it again once, and change the input media if it fails again.
4. Retry the rest. A temporary error from the model's service stays retryable, even when its wording sounds like a validation problem.

More fixes are in Troubleshooting.