v1

latestOpenAPI 3.0.02026-07-26300209.6 KB

Runs

List and search runs

List automation runs with optional filtering by status, goal text, and date range. Returns paginated results with total count. Default sort order is newest first.

get/v1/runs

Query parameters

status'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED'

Filter by run status

Example:COMPLETED

Filter by run status

goalstring

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

Example:linkedin

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

created_afterstring date-time

Filter runs created after this ISO 8601 timestamp

Example:2026-01-01T00:00:00Z

Filter runs created after this ISO 8601 timestamp

created_beforestring date-time

Filter runs created before this ISO 8601 timestamp

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

Filter runs created before this ISO 8601 timestamp

sort_direction'asc' | 'desc'

Sort order by created_at

Example:desc

Sort order by created_at

cursorstring

Cursor for pagination (from previous response)

Example:eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=

Cursor for pagination (from previous response)

limitinteger

Maximum number of results to return (1-100)

Example:20

Maximum number of results to return (1-100)

Response

Paginated list of runs

Example response

{
  "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,
      "output_schema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "price": {
            "type": "number"
          }
        },
        "required": [
          "title",
          "price"
        ]
      },
      "profile_attached": true,
      "profile_id": "prof_abc123",
      "error": {
        "code": "service_busy",
        "message": "Browser crashed during execution",
        "category": "SYSTEM_FAILURE",
        "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.",
        "profile_hint": {
          "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
          "reason": "auth_wall"
        }
      },
      "profile_hint": {
        "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
        "reason": "auth_wall"
      },
      "streaming_url": "https://stream.agent.tinyfish.ai/session/xyz",
      "browser_config": {
        "proxy_country_code": "US"
      }
    }
  ],
  "pagination": {
    "total": 142,
    "next_cursor": "eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=",
    "has_more": true
  }
}