Skip to main content
GET
/
v1
/
runs
List and search runs
curl --request GET \
  --url https://agent.tinyfish.ai/v1/runs \
  --header 'X-API-Key: <api-key>'
{
  "data": [
    {
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "COMPLETED",
      "goal": "Find all pricing information",
      "created_at": "2026-01-14T10:30:00Z",
      "started_at": "2026-01-14T10:30:05Z",
      "finished_at": "2026-01-14T10:31:30Z",
      "num_of_steps": 5,
      "result": {},
      "error": {
        "message": "Browser crashed during execution",
        "category": "SYSTEM_FAILURE",
        "code": "service_busy",
        "retry_after": 60,
        "help_url": "https://docs.tinyfish.ai/prompting-guide",
        "help_message": "Need help? Check out our goal prompting guide for tips and examples."
      },
      "streaming_url": "https://stream.agent.tinyfish.ai/session/xyz",
      "browser_config": {
        "proxy_enabled": false,
        "proxy_country_code": "US"
      }
    }
  ],
  "pagination": {
    "total": 142,
    "next_cursor": "eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=",
    "has_more": true
  }
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Get your key from the API Keys page.

Query Parameters

​
status
enum<string>

Filter by run status

Available options:
PENDING,
RUNNING,
COMPLETED,
FAILED,
CANCELLED
Example:

"COMPLETED"

​
goal
string

Filter runs by goal text (case-insensitive partial match)

Maximum string length: 500
Example:

"linkedin"

​
created_after
string<date-time>

Filter runs created after this ISO 8601 timestamp

Example:

"2026-01-01T00:00:00Z"

​
created_before
string<date-time>

Filter runs created before this ISO 8601 timestamp

Example:

"2026-02-01T00:00:00Z"

​
sort_direction
enum<string>
default:desc

Sort order by created_at

Available options:
asc,
desc
Example:

"desc"

​
cursor
string

Cursor for pagination (from previous response)

Example:

"eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0="

​
limit
integer
default:20

Maximum number of results to return (1-100)

Required range: 1 <= x <= 100
Example:

20

Response

Paginated list of runs

Paginated list of runs

​
data
object[]
required

Array of runs

​
pagination
object
required

Pagination information