Skip to main content
A Run is a single execution of an Agent. 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, through MCP, or from the API.

​
Start and monitor a Run

1

Start the Agent

Call POST /agent/{agentId}/start, run the Agent from Control Center, or let a Schedule trigger it.
2

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.
3

Poll until finished

Poll GET /agent/{agentId}/run/{runId}/status until the Run reaches a finished status.
4

Fetch outputs

List files with GET /agent/{agentId}/run/{runId}/files, then download the records, logs, screenshots, or other output files you need.
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.
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.

​
Run phases

A Run usually moves through these phases:

Accepted

The Run is Queuing or Waiting. Sequentum accepted the request and is waiting to start the run.

Executing

The Run is Starting or Running. The runtime is booting, the browser is open, or commands are executing.

Delivering outputs

The Run may enter Exporting after records are extracted while an Export command delivers them.

Finished

The Run ends as Completed, Success, Failure, Stopped, or Skipped. Stop polling when you see one of these.

​
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.
Treat Completed and Success as equivalent for downstream data consumers. Which one you see depends on whether the Agent defines success criteria.

​
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.

List run output files

See which records, logs, screenshots, and files the Run produced.

Download a run output file

Download a specific output file by fileId.
For high-volume use cases, configure an Export so records land directly in Snowflake or S3 instead of being polled out of the API.

​
Status reference

The API returns RunStatus as an integer. These are the canonical values.
  • 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.
  • 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.
  • 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.

​
Stop vs. kill

Prefer stop. 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 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).

Start a run

Trigger an Agent and optionally return records synchronously.

Get run status

Poll a Run until it is finished.

List run output files

See which records, logs, screenshots, and files the Run produced.

Stop a run

Ask a Run to stop cleanly.