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

# TinyAgent Reference — Runs

> List, retrieve, and cancel TinyAgent runs; fetch step screenshots and HTML

List, retrieve, and cancel runs created via the [Agent](https://docs.tinyfish.ai/agent/api/agent) endpoints, and fetch
per-step screenshots and HTML snapshots. All requests require the `X-API-Key` header unless noted
otherwise. See [Authentication](https://docs.tinyfish.ai/authentication.md).

## Endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/runs` | `GET` | List and search runs |
| `/v1/runs/{id}` | `GET` | Get run by ID |
| `/v1/runs/{id}/cancel` | `POST` | Cancel run by ID |
| `/v1/runs/batch` | `POST` | Get multiple runs by IDs |
| `/v1/runs/batch/cancel` | `POST` | Cancel multiple runs by IDs |
| `/v1/runs/{id}/steps/{stepId}/screenshot` | `GET` | Get a step's screenshot |
| `/v1/runs/{id}/steps/{stepId}/html` | `GET` | Get a step's HTML snapshot |

## List and Search Runs

`GET /v1/runs`

**status** `string`

Filter by run status.

**goal** `string`

Text search over the goal field.

**created\_after** `string`

ISO 8601 timestamp lower bound.

**created\_before** `string`

ISO 8601 timestamp upper bound.

**sort\_direction** `string` (default: desc)

`asc` or `desc`.

**cursor** `string`

Pagination cursor from a previous response.

**limit** `integer` (default: 20)

Results per page, 1–100.

```json theme={null}
{
  "data": [{ "run_id": "run_abc123", "status": "COMPLETED", "goal": "...", "created_at": "..." }],
  "pagination": { "total": 42, "next_cursor": null, "has_more": false }
}
```

## Get a Run by ID

`GET /v1/runs/{id}`

Use this endpoint to retrieve the current or final state of an async or streaming run.

In an organization, a workflow key reads only runs started by its team's workflow keys, never its creator's own; see [Who sees what](https://docs.tinyfish.ai/key-concepts/organizations.md#who-sees-what).

**id** `string` *required*

The run's `run_id`.

**screenshots** `string` (default: url)

`url`, `base64`, or `none` — controls how each step's `screenshot` field is delivered.

**html** `string` (default: url)

`url` or `none` — controls how each step's `html` field is delivered.

**run\_id** `string`

Unique run identifier.

**status** `string`

`PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, or `CANCELLED`.

**goal** `string`

Original goal text.

**created\_at** `string | null`

ISO 8601 timestamp.

**started\_at** `string | null`

ISO 8601 timestamp.

**finished\_at** `string | null`

ISO 8601 timestamp.

**num\_of\_steps** `integer | null`

Number of steps taken.

**result** `object | null`

Extracted JSON result.

**output\_schema** `object | null`

Schema originally requested, if any.

**profile\_attached** `boolean`

Whether a Browser Context Profile was attached to the run.

**profile\_id** `string | null`

ID of the attached Browser Context Profile, if any. Both profile fields are omitted when an
organization workflow key reads a run that used a profile.

**error** `object | null`

**error**

**code** `string`

Machine-readable error code.

**message** `string`

Human-readable failure description.

**category** `string`

`SYSTEM_FAILURE`, `AGENT_FAILURE`, `BILLING_FAILURE`, or `UNKNOWN`.

**retry\_after** `number | null`

Suggested retry delay in seconds.

**help\_url** `string`

Troubleshooting link.

**help\_message** `string`

Human-readable guidance.

**streaming\_url** `string | null`

Live browser stream URL while running.

**browser\_config** `object | null`

Proxy settings used for the run.

**video\_url** `string | null`

Presigned run recording URL, if available.

**steps** `array`

Recorded step events for the run.

## Cancel a Run by ID

`POST /v1/runs/{id}/cancel`

Runs created via `/run-async`, `/run-sse`, or `/run-batch` can be cancelled — this route resolves
the batch ID for you, so cancelling a batch run works the same way. Only synchronous `/run`
requests can't be cancelled, since they block until the run finishes. Idempotent — calling it on
an already-cancelled or completed run returns the current state without error.

A run your key can read but not cancel returns 403 [`FORBIDDEN`](https://docs.tinyfish.ai/error-codes#forbidden) with the message `You can view this run but not cancel it`.

**id** `string` *required*

The run's `run_id`.

**run\_id** `string`

**status** `string`

`CANCELLED`, `COMPLETED`, or `FAILED` — actual status after the cancel attempt.

**cancelled\_at** `string | null`

**message** `string | null`

Idempotency or terminal-state message, e.g. `"Run already cancelled"`.

## Get Multiple Runs by ID

`POST /v1/runs/batch`

Get multiple runs by ID in one call.

**run\_ids** `string[]` *required*

**data** `array`

The found run objects.

**not\_found** `string[]`

Any IDs that didn't match a run.

## Cancel Multiple Runs by ID

`POST /v1/runs/batch/cancel`

Cancel multiple runs by ID in one call.

**run\_ids** `string[]` *required*

**results** `array`

A cancel outcome per run, same shape as the single-cancel response.

**not\_found** `string[]`

Any IDs that didn't match a run.

## Get a Step's Screenshot

`GET /v1/runs/{id}/steps/{stepId}/screenshot`

Returns the raw screenshot image for one recorded step. Only populated when the run was created
with `capture_config.screenshots` enabled.

**id** `string` *required*

The run's `run_id`.

**stepId** `string` *required*

The step's `id`, from the run's `steps` array.

## Get a Step's HTML Snapshot

`GET /v1/runs/{id}/steps/{stepId}/html`

Returns the raw HTML snapshot for one recorded step. Only populated when the run was created with
`capture_config.html` enabled.

**id** `string` *required*

The run's `run_id`.

**stepId** `string` *required*

The step's `id`, from the run's `steps` array.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.