Runs
Updated 2026-11-06
A run is one call of a function. Each start makes a new run with a new id (run_…). A run ends one time, as succeeded or failed. To continue the work of a run that ended, save its disk as an image. Then start a new run from that image.
Start a run
With the CLI:
$ jinn run support-triage --prompt "Ticket #4812: charged twice" --in ./in --out ./result
With the API:
- Make the input folder into one tar file with gzip compression:
tar -czf in.tar.gz -C in . - Start an upload with the size and the SHA-256 of the file.
- Upload the file to the URL in the response, with the headers in the response.
- Start the run with the id of the upload.
POST /v1/files
{"bytes": 691, "sha256": "ac314bcd4091f5729b608f5570ee5ac87dd0eb60a9313158163a74d8732da3f0"}
← 201 {"id": "file_dfa9f553357ebb946a5045a8", "url": "https://…", "method": "PUT", "headers": {"X-Amz-Checksum-Sha256": "rDFLzUCR9XKbYI9VcO5ayH3Q62CpMTFYFjp02HMto/A="}}
PUT <url> with the returned headers and the .tar.gz as the body
POST /v1/functions/fnc_a3b59df3be29992f250c2e1e/runs
{"prompt": "Ticket #4812: charged twice", "input": "file_dfa9f553357ebb946a5045a8"}
← 201 {"id": "run_90bdd4f8175861bad26e0e1b", "state": "queued", …}
| Field | Value |
|---|---|
prompt | The first message to the agent, without changes. Necessary if the function has an agent (prompt_required). Not permitted if the function has no agent (prompt_not_allowed). |
input | An uploaded .tar.gz file (file_…). Jinn unpacks it into /workspace/in. Necessary if the function has an input manifest. Not permitted if it has no input manifest. |
image | A disk to boot for this run, not the image of the function: an image of the account (img_…) or a base. |
environment | Variables for this run, as in a definition. If the function has a variable with the same name, the value from the run replaces it. |
version | A version number. If you do not set it, the run uses the latest version. |
webhook | An HTTPS address for the events of the run. See Webhooks. |
external_reference | Your own id for the run, a maximum of 256 bytes. Jinn returns it as you sent it. An image that the run saves also keeps it. |
A run can change only its image and its variables. Setup, size, timeout, the agent and the manifests are part of the version. To change them, publish a new version.
The input can contain only regular files and folders. Jinn refuses links. The unpacked input must not be larger than half of the disk of the run (see sizes). Jinn refuses a .tar file without compression.
Start a run one time
A request can fail before you receive the response. To send it again safely, send an Idempotency-Key header with the start:
POST /v1/functions/fnc_a3b59df3be29992f250c2e1e/runs
Idempotency-Key: ticket-4812
{"prompt": "Ticket #4812: charged twice", "input": "file_dfa9f553357ebb946a5045a8"}
- Use one key for one task, for example the id of the event that started the task.
- If a start of the same function used the key in the last 24 hours, Jinn does not start a run. It returns that run, as it is now, with the status 201 and the header
Idempotent-Replayed: true. - Jinn does not compare the two requests. The first start with the key sets the run.
- Each function has its own keys. The same key on a different function starts a different run.
- The key is 1 to 255 printable ASCII characters. Quotes around the key are optional.
States
queued → running → succeeded or failed.
A run starts in some seconds if a machine has space for it. If Jinn must start a new machine, the run waits approximately 30 seconds more. If a run does not start in 15 minutes, it fails with infrastructure.
At the start of a running run, Jinn does these steps. The log of the run shows each step.
- Jinn restores the disk from the image.
- The VM boots. This takes approximately 2 seconds.
- Jinn unpacks the input.
- Setup runs.
Then the run is ready. Jinn sets ready_at and sends the run.running event. The agent then starts its work, or your commands run. A command that you send before this time waits until the run is ready.
Finish a run
A run ends when a finish command ends it, or when Jinn stops it.
finishwithstate: succeededexamines the output manifest. If an entry is missing or too large, the command returns the problems, and the run continues. If the output agrees with the manifest, Jinn uploads/workspace/out. A function without an output manifest returns no files. If the function hasoutput_image, Jinn saves the disk. Then the run issucceeded.finishwithstate: failedends the run with the failureincomplete. If you send adetail, it becomes the detail of the run.- The
completeandgive_uptools of an agent are these two types of finish.
$ jinn finish run_5ab647d533bda87c1063b403
run_5ab647d533bda87c1063b403 succeeded
image img_1246e6c170ea4b93cf3ab52d
$ jinn finish run_3afd65eeb5fc5b3202c44d77 --failed "The tests do not build."
run_3afd65eeb5fc5b3202c44d77 failed incomplete
When a run ends, Jinn cancels the commands that did not end.
Results
A succeeded run has output. If the function has an output manifest and /workspace/out contains files, output lists them with their sizes. output.url is a link to the folder as one .tar.gz file. output.bytes and output.sha256 give its size and its SHA-256. Each read of the run makes a new link. You can use the link for 15 minutes.
Jinn uses the fastest level of gzip. Text files become much smaller. Media files stay almost the same size. If the function has output_image, output.image is the id of the saved image.
$ jinn output run_90bdd4f8175861bad26e0e1b --out ./result
result/actions.json 128 B
result/reply.md 557 B
A failed run has failure and detail:
| Failure | Cause | Image saved |
|---|---|---|
input | The input is not a readable .tar.gz file, or it contains a link. Or the unpacked input is larger than half of the disk, or it does not agree with the input manifest. Or the image is larger than the disk of the size, or it does not boot. Or someone deleted the image before the run started. | No |
setup | A setup command exited with a status other than 0. The detail shows its output. | No |
incomplete | A finish as failed. The agent used give_up, or the agent stopped its tool calls, or the agent did 200 steps without a command in the VM. Or your code finished the run as failed. | No |
timeout | The run continued after timeout_minutes. | With output_image |
provider | The model vendor refused a call, for example because the key is incorrect or the quota is empty. The detail quotes the vendor. | With output_image |
maintenance | Jinn had to replace the machine of the run. The run.maintenance event comes first, with maintenance_at. | With output_image |
suspended | Jinn suspended the account before the run started or while it worked. | With output_image |
credit | The balance of the account went more than $10 below its minimum before the run started or while it worked. Add credit to start runs again. | With output_image |
infrastructure | Jinn could not start or finish the run, or the machine of the run stopped. Or a step of the agent failed 6 times. Or someone deleted the function before the run started. Start the run again. | No |
The image of a failed run is the disk at the time when the run stopped. A run that fails before it is ready saves no image.
usage records the size of the VM and its seconds, its network bytes, and the model calls and tokens of the agent.
Logs
The log records each step of the run:
- the disk and the VM;
- each setup command, with its output and exit status;
- each command, with its result;
- the messages and tool calls of the agent.
While a run is running, Jinn adds new events to the log at intervals of 30 seconds.
$ jinn logs run_90bdd4f8175861bad26e0e1b --follow
GET /v1/runs/{id}/log returns links to the parts of the log, in sequence. Each part is JSON lines, for example {"at": "2026-10-14T11:43:46.089855126Z", "kind": "tool_call", "name": "bash", "id": "call_xnmZFjRli7jJyQikzQlewJtS", "arguments": "…"}. The response also contains media: a link to each image that a read command or the screenshot tool returned, by command id. A tool_output event with image_bytes gives the id of its command. You can use the links for 15 minutes.
A step_retry event shows that Jinn did an agent step again, because the first attempt of the step did not finish. first_attempt_at gives the time of the first attempt. waited_seconds gives the time that the step lost.
Credit
- An account can start an unlimited number of runs. If no machine has space, the runs wait for a machine. If a run does not start in 15 minutes, it fails with
infrastructure. - Jinn bills a run for each minute of compute that starts. The time starts when a machine takes the run, and stops when the run ends. See Pricing.
- A run starts only if the account has credit. A start without credit receives
402. - A run that started continues until the balance is more than $10 below the minimum of the account. Then the run stops in 5 minutes or less, and fails with
credit. Jinn bills the minutes that the run used. - If Jinn suspends an account, each start receives
403. The running runs of the account stop in 5 minutes or less.