v1

latestOpenAPI 3.0.02026-07-26300209.6 KB

Runs

Get multiple runs by IDs

Retrieve multiple runs by their IDs in a single request. Returns found runs and lists any IDs that were not found or not owned. Maximum 100 IDs per request.

post/v1/runs/batch

Request body

run_idsstring[] required

Array of run IDs (1-100)

Example request

{
  "run_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  ]
}

Response

Request succeeded. Returns found runs in data and any missing IDs in not_found.

not_foundstring[] nullable required

Run IDs that were not found or not owned. Null if all found.

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"
      },
      "video_url": "https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?...",
      "steps": [
        {
          "id": "evt_abc123",
          "timestamp": "2026-01-14T10:30:05Z",
          "status": "COMPLETED",
          "action": "Click the login button",
          "screenshot": "https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/screenshot",
          "html": "https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/html",
          "duration": "1.2s"
        }
      ]
    }
  ]
}