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

Request

  • Base URL: https://agent.tinyfish.ai
  • URL: https://agent.tinyfish.ai/v1/runs
  • Auth: API key in header X-API-Key

Query parameters

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

Filter by run status

Example:COMPLETED
goalstring

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

Example:linkedin
created_afterstring date-time

Filter runs created after this ISO 8601 timestamp

Example:2026-01-01T00:00:00Z
created_beforestring date-time

Filter runs created before this ISO 8601 timestamp

Example:2026-02-01T00:00:00Z
sort_direction'asc' | 'desc'

Sort order by created_at

Example:desc
cursorstring

Cursor for pagination (from previous response)

Example:eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0=
limitinteger

Maximum number of results to return (1-100)

Example:20

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
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.