Runs

A run is one call of a function: a prompt and an optional input folder in, an output folder out. Every start is a new run with a new id (run_…).

Start a run

jinn run summarise --prompt "Summarise these notes." --in ./notes --out ./result

With the API, upload the input folder as one .tar, then start the run:

POST /v1/files
{ "bytes": 18432, "sha256": "9f2c41…" }
← 201 { "id": "file_3b8e0c5a9d2f41e7b6c08a13", "url": "https://…", "method": "PUT", "headers": { … } }

PUT <url>  (the .tar, with the returned headers)

POST /v1/functions/fnc_5d2a91c07e4b38f6a1d0c2e9/runs
{ "prompt": "Summarise these notes.", "input": "file_3b8e0c5a9d2f41e7b6c08a13" }
← 201 { "id": "run_7c41e0a9d2b35f8e61c09a4d", "state": "queued", … }

Field	What it is
`prompt`	The agent's first message, word for word. At most 128 KiB; put larger data in the input folder.
`input`	An uploaded `.tar` (`file_…`). Jinn unpacks it into `/workspace/in`. Uploads expire after 30 days.
`version`	A version number. Leave it out for the latest.
`webhook`	An HTTPS address for the result. See Webhooks.
`external_reference`	Your own id for the run. Jinn stores it and returns it.

States

A run is queued, then running, then succeeded or failed. A run is never cancelled or continued: start another.

A run starts within seconds when a machine is free. When Jinn must start a new machine, it takes about a minute and a half.

The result

A succeeded run has an output: its files, their sizes, and a link (url) to the output folder as one .tar. Each read of the run makes a fresh link, which works for 15 minutes.

jinn output run_7c41e0a9d2b35f8e61c09a4d --out ./result

A failed run has a failure and a detail:

Failure	What happened
`input`	The input folder did not match the input manifest, or was not a readable `.tar`.
`setup`	A setup command failed. The detail names it and shows its output.
`no_submission`	The agent stopped without delivering the output manifest.
`timeout`	The run worked past `timeout_minutes`.
`provider`	The model vendor refused the call, for example a wrong key or no quota.
`infrastructure`	Jinn could not start or finish the run. Start another.
`suspended`	The account was suspended while the run worked.

The log

The log shows everything the run did: setup commands and their output, the model's messages, each tool call and its result. A running run adds to it about every 30 seconds.

jinn logs run_7c41e0a9d2b35f8e61c09a4d --follow

With the API, GET /v1/runs/{id}/log returns links to the log's parts. Each part is JSON lines: {"at": "…", "kind": "tool_call", …}.

Limits and credit

Each account has a memory limit for its queued and running runs together. A start that would pass it gets 429.
A run starts only while the account has credit. A start without credit gets 402. A run that has started always finishes, even if the balance goes below zero.
A suspended account gets 403, and its running runs stop.

Jinn records the minutes and memory of every run in the account's usage. The console shows it.

What stays

Machines and their disks are destroyed after each run. Inputs, outputs and logs are deleted after 30 days.