# Runs and approvals

Every time an <Term id="agent">agent</Term> starts, it makes a <Term id="run">run</Term>: one pass through its steps, with its own log, files, result and cost. Use runs to check the work, answer approvals and fix failures without starting over.

## Before you start [#before-you-start]

| To | You need to be able to |
| --- | --- |
| See an agent's runs | Open its <Term id="project">project</Term> |
| Answer an approval | Change the project |
| Run again from a step | Edit the project |

## Find a run [#find-a-run]

<ForEveryone>

Open the agent. The **Runs** panel shows the latest; **View all** opens the full list with each **Run**, when it **Started**, how long it **Took** and its **Credits**. Filter by **All**, **Running**, **Done** or **Failed**, and select **Load more** to go further back.

Each run says how it started: **On schedule**, **Started by a table load**, **Started by new files**, **Started by new webhook** or **Started by an agent**.

</ForEveryone>

<ForDevelopers>

```bash
klarety agent runs daily-summary --project PROJECT_ID
```

The CLI shows the latest few runs. In Python, `runs` reads further back a page at a time, newest first:

```python
from itertools import islice
from klarety import Nexus

nx = Nexus.connect()
for run in islice(nx.agents.runs("PROJECT_ID", agent="daily-summary"), 50):
    print(run)

for day in nx.agents.stats("PROJECT_ID", days=7):
    print(day)
```

`stats` returns runs per day, newest first: how many, how they ended and what they cost. To resume paging from another process, use `runs_page` and pass its `next` back as `after`.

</ForDevelopers>

## Read a run [#read-a-run]

A run shows the agent's flow with each step's state: **Waiting**, **Running**, **Waiting for you**, **Done**, **Reused**, **Failed**, **Declined**, **Stopped** or **Skipped**. A step that runs once per item shows its progress, for example "12 of 40 items".

Select a step for its settings, then **Log and files** to read what it printed and download what it made. **Result** shows what the run produced: rows (with "Showing X of Y rows" for a long result), text or files.

<Screenshot src="/docs/_media/demp-bakery-business-data-agent-flow-page.png" alt="A run page with a step selected and its Log and files panel open" />

<ForDevelopers>

```python
run = nx.agents.run("PROJECT_ID", RUN_ID)
result = nx.agents.result("PROJECT_ID", RUN_ID)
print(nx.agents.log("PROJECT_ID", RUN_ID, "summary"))
for name in nx.agents.outputs("PROJECT_ID", RUN_ID, "summary"):
    data = nx.agents.output("PROJECT_ID", RUN_ID, "summary", name)
```

`result` holds the result step, its value (up to 1 MiB) and the files the run left. For a step that runs once per item, pass `item=` to `log`, `outputs` or `output`.

</ForDevelopers>

## Approve the next step [#approve-the-next-step]

An **Asks you first** step pauses the run and asks a question, such as "Save these scores to the ai_scores table?". The run shows **Waiting for you**, and the agent moves to **Needs you** on <AppLink to="agents" />.

<ForEveryone>

<Steps>
<Step>
### Open the waiting run [#open-the-waiting-run]
Open the agent from **Needs you** and select the waiting run.
</Step>
<Step>
### Check what it is about to do [#check-what-it-is-about-to-do]
Read the earlier steps' output, such as the scores it wants to save.
</Step>
<Step>
### Answer [#answer]
Select **Yes, continue**, or **No, stop here** to end it as **Declined**; nothing after the approval step happens.
</Step>
</Steps>

<Screenshot src="/docs/_media/demp-bakery-business-data-agent-flow-page.png" alt="A run waiting at an approval step with Yes, continue and No, stop here" />

</ForEveryone>

<ForDevelopers>

```python
nx.agents.answer("PROJECT_ID", RUN_ID, "approve", yes=True)
```

`step_id` is the approval step's `id` in the agent's file. `yes=False` stops the run there.

</ForDevelopers>

<Callout type="warn" title="No cannot be undone">
  A declined run ends there. To do the work after all, start the agent again or use **Run again from here** on a later run.
</Callout>

## Stop a run [#stop-a-run]

Select **Stop** on a run in progress. It ends as **Stopped**; finished steps keep their output.

<ForDevelopers>

```bash
klarety agent stop RUN_ID --project PROJECT_ID
```

</ForDevelopers>

## Run again from a step [#run-again-from-a-step]

<Callout type="success" title="Saves time and credits">
  Steps before the one you pick are reused, not run again.
</Callout>

When a run fails partway or a step was interrupted, open the run, select the step to start from and select **Run again from here**. The new run reuses the earlier outputs (shown as **Reused**) and runs that step and everything after it.

<ForDevelopers>

```bash
klarety agent rerun RUN_ID --from-step summary --project PROJECT_ID
```

```json
{
  "run_id": "..."
}
```

</ForDevelopers>

## What runs cost [#what-runs-cost]

Each run uses <Term id="credits">credits</Term> from your <Term id="workspace">workspace</Term>, shown in the **Credits** column. The Agents page shows **Credits today** and runs for this week; balance and spend are in <AppLink to="settings.usage" />. A paused or deleted agent starts no new runs, so it stops using credits.

## If something goes wrong [#if-something-goes-wrong]

- **A run failed**: open it, find the step marked **Failed** and read **Log and files**. If the cause has passed (for example, a web address that was down), use **Run again from here** on that step.
- **"This step was retried after an interruption"**: a service the step called may have been called twice. Check it if a duplicate would matter.
- **A run waits for a long time**: it is probably at an **Asks you first** step. Look under **Needs you**.
- **"This run ended before it produced a result"**: it failed, was stopped or was declined before the result step. Check which step ended it.

## Where to go next [#where-to-go-next]

- [Try, go live and pause](/docs/agents/go-live)
- [What agents do](/docs/agents)
- [Credits](/docs/workspace/credits)