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

# Runs

> Executions of an Agent, with status, outputs, files, and logs.

A **Run** is a single execution of an [Agent](/concepts/agents). Runs are where you monitor work in progress, collect extracted records, inspect output files, and handle failures.

You can start a Run manually, from a [Schedule](/concepts/schedules), through MCP, or from the API.

## Start and monitor a Run

<Steps>
  <Step title="Start the Agent">
    Call [`POST /agent/{agentId}/start`](/api-reference/agents/start-run), run the Agent from Control Center, or let a Schedule trigger it.
  </Step>

  <Step title="Track the runId">
    Async starts return a `runId` immediately. Keep it with the `agentId`; together they identify the Run in status and output-file endpoints.
  </Step>

  <Step title="Poll until finished">
    Poll [`GET /agent/{agentId}/run/{runId}/status`](/api-reference/agents/run-status) until the Run reaches a finished status.
  </Step>

  <Step title="Fetch outputs">
    List files with [`GET /agent/{agentId}/run/{runId}/files`](/api-reference/agents/run-files), then download the records, logs, screenshots, or other output files you need.
  </Step>
</Steps>

<Note>
  Spaces contain Agents; each Run belongs to the Agent that started it. Depending on the Agent's run settings, that Agent can allow multiple active Runs at once or run exclusively with only one active Run at a time.
</Note>

<Tip>
  For quick tests, `isRunSynchronously: true` returns extracted records inline when the Run finishes. For production, use the async pattern: start the Run, store the `runId`, poll status, then fetch outputs.
</Tip>

## Run phases

A Run usually moves through these phases:

<CardGroup cols={2}>
  <Card title="Accepted" icon="clock">
    The Run is `Queuing` or `Waiting`. Sequentum accepted the request and is waiting to start the run.
  </Card>

  <Card title="Executing" icon="play">
    The Run is `Starting` or `Running`. The runtime is booting, the browser is open, or commands are executing.
  </Card>

  <Card title="Delivering outputs" icon="file-arrow-down">
    The Run may enter `Exporting` after records are extracted while an Export command delivers them.
  </Card>

  <Card title="Finished" icon="circle-check">
    The Run ends as `Completed`, `Success`, `Failure`, `Stopped`, or `Skipped`. Stop polling when you see one of these.
  </Card>
</CardGroup>

## Polling for completion

When polling `GET /agent/{agentId}/run/{runId}/status`, stop when the status means the Run is finished:

* `Failure` (`6`) — execution failed or success criteria did not pass. The Run is restartable while it remains in the active Runs table.
* `Stopped` (`8`) — the Run was stopped or killed.
* `Completed` (`9`) — commands finished and the Agent has no success criteria configured.
* `Success` (`10`) — commands finished and configured success criteria passed.
* `Skipped` (`11`) — the Run was skipped, for example because a Schedule fired while the Agent was archived.

<Note>
  Treat `Completed` and `Success` as equivalent for downstream data consumers. Which one you see depends on whether the Agent defines success criteria.
</Note>

## Outputs

Every Run can produce:

* **Records** — the structured data the Agent extracted, available through the run-files endpoints.
* **Files** — downloaded assets, screenshots, raw HTML, and other artifacts.
* **Logs** — timing, execution traces, failures, and blocked-page signals.

<CardGroup cols={2}>
  <Card title="List run output files" icon="folder-open" href="/api-reference/agents/run-files">
    See which records, logs, screenshots, and files the Run produced.
  </Card>

  <Card title="Download a run output file" icon="download" href="/api-reference/agents/run-file-download">
    Download a specific output file by `fileId`.
  </Card>
</CardGroup>

<Tip>
  For high-volume use cases, configure an [Export](/agents/commands/overview) so records land directly in Snowflake or S3 instead of being polled out of the API.
</Tip>

## Status reference

The API returns `RunStatus` as an integer. These are the canonical values.

<AccordionGroup>
  <Accordion title="Active statuses">
    * `1` `Running` — the browser is open and commands are executing.
    * `2` `Exporting` — records have been extracted and an Export command is delivering them.
    * `3` `Starting` — the Run was accepted and the runtime is booting.
    * `4` `Queuing` — accepted but waiting for a free worker.
    * `5` `Stopping` — a stop was requested and the Run is shutting down gracefully.
    * `12` `Waiting` — the Run is paused, waiting on an external condition.
  </Accordion>

  <Accordion title="Finished statuses">
    * `6` `Failure` — execution finished with an error or failed success criteria. Restartable while it remains in the active Runs table.
    * `8` `Stopped` — stopped or killed.
    * `9` `Completed` — commands finished and no success criteria were configured.
    * `10` `Success` — commands finished and success criteria passed.
    * `11` `Skipped` — skipped before execution, such as when a Schedule fires for an archived Agent.
  </Accordion>

  <Accordion title="History-only and reserved statuses">
    * `7` `Failed` — once a `Failure` Run is archived to run history, its status is rewritten to `Failed`. By the time you see `Failed`, the Run can no longer be resumed.
    * `0` `Invalid` — reserved for malformed records and should never appear on a real Run.
  </Accordion>
</AccordionGroup>

## Stop vs. kill

Prefer [`stop`](/api-reference/agents/stop-run). It waits for the current command to finish, persists what has been extracted so far, and ends the Run cleanly as `Stopped` (`8`).

Use [`kill`](/api-reference/agents/kill-run) only when `stop` is not responding. The first `kill` call initiates a graceful stop; a second call within the stopping window forces immediate termination and may discard in-flight work. The Run still ends as `Stopped` (`8`).

## Related API references

<CardGroup cols={2}>
  <Card title="Start a run" icon="play" href="/api-reference/agents/start-run">
    Trigger an Agent and optionally return records synchronously.
  </Card>

  <Card title="Get run status" icon="circle-play" href="/api-reference/agents/run-status">
    Poll a Run until it is finished.
  </Card>

  <Card title="List run output files" icon="folder-open" href="/api-reference/agents/run-files">
    See which records, logs, screenshots, and files the Run produced.
  </Card>

  <Card title="Stop a run" icon="square" href="/api-reference/agents/stop-run">
    Ask a Run to stop cleanly.
  </Card>
</CardGroup>