---
title: "Activity & runs"
description: "What your agents are doing right now and whether the last piece of work reached its goal: the run, its step trail, the outcome rules, and why an outcome is never guessed."
canonical: "https://scalebrowser.net/docs/agents/runs"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://scalebrowser.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity & runs

> What your agents are doing right now and whether the last piece of work reached its goal: the run, its step trail, the outcome rules, and why an outcome is never guessed.

The question a fleet owner actually has is not how the machine is doing. It is **what are my agents doing, and did the last piece of work reach its goal?**

That is what the Activity screen answers, and this page is the layer behind it.

## Three things, kept apart
| Part        | What it is                                          | Who says so                       |
| ----------- | --------------------------------------------------- | --------------------------------- |
| **Intent**  | The run's goal, one sentence.                       | The agent, stated. Never invented. |
| **Trail**   | One entry per tool call.                            | The daemon, automatically.        |
| **Outcome** | Whether it worked.                                  | A claim, never a computed state.  |

Keeping them apart is the point. An outcome derived from "no errors in the trail" would call a run successful that clicked the wrong button forty times without failing once.

## What a run is
A **run** is one declared task on one profile. It begins when an agent calls `start_run`, or at the first tool call of an agent that declared nothing, or when a person opens a visible window. It ends at `release_profile`, at a second `start_run`, with the browser, or at the next daemon start.

<Note>

**The lease is not the bracket.** A reservation is a resource boundary: it can cover several tasks or none. It lives on as a session id that groups the runs of one reservation, which is a different question from what the agent was trying to do.

</Note>

## The outcome rules
| Value                  | Who may set it                                                     |
| ---------------------- | -------------------------------------------------------------------- |
| `reached` · `partial`  | **Only** an agent, a check, or a person.                            |
| `blocked`              | An agent, or derived when the last step ended at a wall.            |
| `interrupted`          | Derived: a crash or a daemon restart.                               |
| `unknown`              | Derived: it ended and nobody said how. **This is the default.**     |

`reached` and `partial` cannot be produced by derivation at all, and a write carrying one without naming its source is refused. Two independent locks on one rule, because this is the field the whole screen is worth reading for.

The practical consequence: **pass an outcome when you release a profile.** Left out, the work is filed as unknown rather than as success, which is the honest reading and also the less useful one.

## The trail
Every tool call with a profile behind it becomes exactly one step: the tool, the target, how long it took, whether it failed, and optionally a still.

Out of the trail stay `start_run`, whose goal and timestamp are the run's own header, and tools with no profile behind them at all, such as listing profiles or groups.

<Warning>

**A step never carries the lease handle, and never the arguments.** Neither is part of a stored step. A trail addressed by profile id would otherwise show one agent what another one typed.

</Warning>

The step is handed to a channel rather than written inline, so there is no disk access between an agent's action and its reply.

## Stills
The daemon can keep a picture per step, so a trail can be looked at rather than read.

It is a setting, not a given, because it costs disk. `[runs] shots` turns it on, with a size ceiling and an age limit. There is also a page watcher that follows what the bound tab is showing.

Both were measured against real detector pages before shipping, on the one question that matters: whether a page can tell that the dashboard is watching. See [Monitoring & metrics](/docs/ops/monitoring) for the settings.

## Reading it
| Call                             | What it answers                                     |
| -------------------------------- | ----------------------------------------------------- |
| `GET /v1/activity`               | The whole screen in one object: running, outstanding, recently finished. |
| `GET /v1/runs`                   | Runs, filtered and paged.                            |
| `GET /v1/runs/:id`               | One run.                                             |
| `GET /v1/runs/:id/steps`         | Its trail.                                           |
| `GET /v1/runs/:id/shots/:seq`    | The still of one step.                               |

Everything is also live on the [event stream](/docs/events): `run_started`, `run_step`, `run_finished`, plus `profile_activity_changed` and `profile_activity_gone` for the rows themselves.

An agent gets a read-only view of its own profile's history through `run_list`, in the `extended` set, so it can see what was already tried before it repeats it.

## Two tools shape what you see
`start_run` is one sentence about what this stretch of work is for. Call it again when the task changes, and pass the previous outcome, because nobody else can know it.

`release_profile` takes an outcome for the same reason.

Neither is required. Both are the difference between a screen that says "an agent did 47 things" and one that says "an agent was signing up for an account, and it worked".

## Retention
The newest **500 finished runs** are kept. Older ones are dropped when a run finishes, and their stills go with them, because the images are by far the bulkiest thing this layer writes.

An open run is never pruned, however old it is.

<Note>

**There is no event for a pruned run.** Unlike the profile, task, video and secret lists, a run trail is history rather than live state: nothing on screen goes stale because a run from three weeks ago was dropped.

</Note>

Stills have their own two caps on top of that, `[runs] shots_max_gb` and `shots_max_age_days`. Deleting a profile takes its runs with it.

## Next
- [Tasks & memory](/docs/agents/tasks): what is outstanding, as opposed to what happened.
- [Videos](/docs/agents/videos): the same work as a film rather than a list.
- [Events](/docs/events): the live frames this screen is built from.