# 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

```sh
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:

```http
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](/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.

```sh
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.

```sh
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.