> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/assistants/runs.md).

# Runs and the Cockpit

Following, checking and managing the work assistants do on their own. The **Cockpit** in the main menu shows the runs of every assistant; the **Runs** tab of an assistant shows that assistant's runs.

## What a run is

A run is one piece of work an assistant carries out by itself, started by a [trigger](https://docs.artific.nl/en/for-administrators/assistants/triggers.md). Because nobody is watching while it happens, everything a run does is recorded: what it was asked, which steps it took, who approved what, and what came out.

## The Cockpit

The tiles at the top count the runs that matter most:

| Tile               | What it counts                             |
| ------------------ | ------------------------------------------ |
| **waiting on you** | Runs that need your approval or an answer. |
| **failed**         | Runs that failed in the selected period.   |
| **running now**    | Runs in progress.                          |
| **completed**      | Runs that finished in the selected period. |

Select a tile to show only those runs. Below the tiles, the list shows each run with its status and time, and its cost when cost information is available to your organisation.

### Finding a run

| Filter        | Options                                                                              |
| ------------- | ------------------------------------------------------------------------------------ |
| **Period**    | **Today**, **This week**, **This month**, **Last 12 months**, or a **Custom range…** |
| **Assistant** | One assistant, or **All assistants**.                                                |
| **Status**    | One status, or **All statuses**.                                                     |
| **Search**    | Free text, such as an order number.                                                  |

**Clear filters** resets them.

### Statuses

| Status                           | Meaning                                                       |
| -------------------------------- | ------------------------------------------------------------- |
| **Running now**                  | The run is working.                                           |
| **Waiting on you**               | The run is waiting for approval or information from a person. |
| **Paused**                       | A person paused the run. **Resume** lets it continue.         |
| **Completed**                    | The run finished.                                             |
| **Failed**                       | The run stopped. The reason is shown on the run.              |
| **Failed: criteria not met**     | The result did not meet the trigger's criteria.               |
| **Failed: criteria not checked** | The result was not checked against the criteria.              |
| **Cancelled**                    | A person stopped the run.                                     |

A run waiting on a person shows **Review**. Opening it lets you approve, reject or answer straight away, after which the run carries on where it stopped.

## Actions on a run

The menu on each run offers:

| Action        | What it does                                                                                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Run again** | Starts a new attempt. It is marked as a retry of the earlier run.                                                                                                             |
| **Resume**    | Lets a paused run continue after the last completed step. Work already fetched and weighed is not redone. You can add a message, such as *Skip the supplier check this time*. |
| **Stop**      | Stops this run only.                                                                                                                                                          |
| **Delete**    | Removes the run, its steps and its answer.                                                                                                                                    |

**Stop** aborts the action in progress and sends nothing further; what has already been done is kept. The trigger itself stays on, so a next run still starts. Switch the trigger off if you do not want that.

{% hint style="danger" %}
Deleting a run removes its steps and answer for good. Keep runs you may need to account for later.
{% endhint %}

## Inside a run

Opening a run shows:

* **Instruction**: what the run was asked to do.
* **Answer**: the result, once the run has finished.
* **Run details**: the run ID, assistant, trigger, status, when it finished, its active time and the models it used.
* **Steps**: everything the run did, in order.

## Steps: what the assistant did

**Steps** is the record of the run. It lists, in order, every model call, every tool the assistant used, every knowledge base search, every check against the criteria, and every moment a person approved, rejected or answered, with who it was. When a connector was used, it shows whose connection. Select a step to see its full details, including what it cost.

This is what makes a run accountable. Afterwards you can always trace why it came to a result, which helps both when you improve the instruction and when you need to explain what the assistant did.

**Technical details** exports everything that explains the run: what each model call received and returned, the tools on offer, the run's settings, and every request to a person with its answer. Useful when you investigate a report in detail.

The same step-by-step view is available for ordinary conversations, in an assistant's [chat history](https://docs.artific.nl/en/for-administrators/assistants/session-logs.md).

{% hint style="info" %}
Steps show everything a run did, so they are only available to people who were given access to them. Without that access you still see the rest of the run.
{% endhint %}

## When a run fails

A failed run says why. The most common reasons, and what to do about them:

| Reason                                                                     | What to do                                                                                                             |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| ran past its time limit                                                    | Raise the time limit on the trigger, or narrow the instruction.                                                        |
| ran past its cost limit                                                    | Raise the cost limit, or narrow the instruction.                                                                       |
| ran past its step limit                                                    | Raise the maximum number of actions, or make the instruction more direct.                                              |
| kept repeating the same call                                               | Make the instruction say what to do when a tool does not return what is expected.                                      |
| nobody answered in time                                                    | A request expired unanswered. Check who receives the notifications.                                                    |
| the organisation budget was reached, or the assistant budget was reached   | See [Budgets](https://docs.artific.nl/en/for-administrators/organization/budgets.md).                                  |
| the service account is gone or disabled, or has no access to the assistant | Check **Act as** on the trigger.                                                                                       |
| the result ends with a question no one could answer                        | The assistant asked in its result instead of asking a person. Run it again, or make the instruction say how to decide. |
| the result did not meet its criteria                                       | Read the answer and the steps. Either the instruction or the criteria need work.                                       |
| stopped after too many tool errors                                         | Check the tool or connector the run uses.                                                                              |
| stopped by a person                                                        | Someone chose **Stop**.                                                                                                |

## Who sees what

| Screen                           | Who                                   |
| -------------------------------- | ------------------------------------- |
| **Cockpit** and the **Runs** tab | People with rights to view runs.      |
| **Steps** in a run               | People who were given access to them. |
| The **Triggers** tab             | People who may edit the assistant.    |

Rights come from user groups, as everywhere in the platform. See [Roles and rights](https://docs.artific.nl/en/for-administrators/access/roles.md).

## Keeping an eye on runs

* **Look at failed runs every day** in the first weeks after a trigger goes live. A failure pattern usually points at one sentence in the instruction.
* **Read the steps of a few successful runs** too. A run can finish and still take a detour you would rather it did not.
* **Do not let requests pile up.** A run waiting on a person holds up its own work, and an unanswered request eventually expires.
