> ## 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. # 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. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/main post /v1/runs/batch openapi: 3.0.0 info: title: TinyFish Web Agent Automation API version: 1.0.0 description: >- REST API for running AI-powered browser automations. Execute tasks on any website using natural language instructions. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://agent.tinyfish.ai description: Production security: [] tags: - name: Automation description: Browser automation endpoints for executing tasks on websites - name: Runs description: Endpoints for retrieving automation run data - name: Browser description: Remote browser session endpoints - name: Fetch description: Fetch URLs and extract clean page content - name: Search description: Web search endpoints - name: Browser Context Profiles description: >- Saved browser context endpoints for managing reusable login state, cookies, storage, and profile setup sessions - name: Vault description: >- Vault credential management endpoints for connecting password managers and managing stored credentials paths: /v1/runs/batch: post: tags: - Runs summary: Get multiple runs by IDs description: >- 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. operationId: batchGetRuns requestBody: description: Array of run IDs to fetch content: application/json: schema: type: object properties: run_ids: type: array items: type: string minItems: 1 maxItems: 100 description: Array of run IDs (1-100) example: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 - b2c3d4e5-f6a7-8901-bcde-f23456789012 required: - run_ids description: Batch runs request responses: '200': description: >- Request succeeded. Returns found runs in `data` and any missing IDs in `not_found`. content: application/json: schema: type: object properties: data: type: array items: type: object properties: run_id: type: string description: Unique identifier for the run example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - CANCELLED description: Current status of the run example: COMPLETED goal: type: string description: Natural language goal for this automation run example: Find all pricing information created_at: type: string description: ISO 8601 timestamp when run was created example: '2026-01-14T10:30:00Z' started_at: type: string nullable: true description: ISO 8601 timestamp when run started executing example: '2026-01-14T10:30:05Z' finished_at: type: string nullable: true description: ISO 8601 timestamp when run finished example: '2026-01-14T10:31:30Z' num_of_steps: type: integer nullable: true minimum: 0 description: >- Number of steps taken during the automation run. Null while the run is still in progress. example: 5 result: type: object nullable: true additionalProperties: nullable: true description: Extracted data from the automation run output_schema: type: object nullable: true properties: {} additionalProperties: nullable: true description: >- Provider-supported structured-output schema subset originally requested for this run. Null when no output_schema was provided. example: type: object properties: title: type: string price: type: number required: - title - price profile_attached: type: boolean description: >- Whether this run attached a Browser Context Profile internally. example: true profile_id: type: string nullable: true description: >- Browser Context Profile ID attached to this run, or null when no profile attached. example: prof_abc123 error: type: object nullable: true properties: code: type: string description: >- Machine-readable error code for programmatic handling example: service_busy message: type: string description: Error message describing why the run failed example: Browser crashed during execution category: type: string enum: - SYSTEM_FAILURE - AGENT_FAILURE - BILLING_FAILURE - UNKNOWN description: >- Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable). example: SYSTEM_FAILURE retry_after: type: number nullable: true description: >- Suggested retry delay in seconds (null if not retryable) example: 60 help_url: type: string description: URL to documentation for troubleshooting example: https://docs.tinyfish.ai/prompting-guide help_message: type: string description: Human-readable help message with guidance example: >- Need help? Check out our goal prompting guide for tips and examples. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. required: - message - category description: >- Error details. Null if the run succeeded or is still running. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. streaming_url: type: string nullable: true description: >- URL to watch live browser session (available while running) example: https://stream.agent.tinyfish.ai/session/xyz browser_config: type: object nullable: true properties: proxy_enabled: type: boolean nullable: true description: Whether proxy was enabled example: false proxy_country_code: type: string nullable: true description: Country code for proxy example: US required: - proxy_enabled - proxy_country_code description: Browser configuration used for the run video_url: type: string nullable: true description: >- Presigned URL to the video recording of this run. Null if no recording is available. URL expires after 15 minutes. example: >- https://s3.amazonaws.com/bucket/eva-traces/run-id/video/recording.webm?... steps: type: array items: type: object properties: id: type: string description: Unique identifier for this step example: evt_abc123 timestamp: type: string description: ISO 8601 timestamp when this step occurred example: '2026-01-14T10:30:05Z' status: type: string enum: - PENDING - RUNNING - COMPLETED - FAILED - CANCELLED description: Current status of the run example: COMPLETED action: type: string nullable: true description: Description of the action taken in this step example: Click the login button screenshot: type: string nullable: true description: >- Screenshot for this step. Format depends on the screenshots query param: base64 returns a data URI (data:image/jpeg;base64,...), url returns an absolute URL to the screenshot. Null if screenshots=none or no screenshot available. example: >- https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/screenshot html: type: string nullable: true description: >- URL to the full-page HTML snapshot captured at this step. Null if html=none or no HTML was captured. Requires capture_config.html: true when starting the run. example: >- https://agent.tinyfish.ai/runs/a1b2c3d4/steps/evt_abc123/html duration: type: string nullable: true description: Time taken for this step example: 1.2s required: - id - timestamp - status - action - screenshot - html - duration description: A single automation step description: Steps the agent took during this run. required: - run_id - status - goal - created_at - started_at - finished_at - num_of_steps - result - output_schema - profile_attached - profile_id - error - streaming_url - browser_config - video_url - steps description: A single automation run description: Found runs not_found: type: array nullable: true items: type: string description: >- Run IDs that were not found or not owned. Null if all found. required: - data - not_found description: Batch get runs response example: data: - run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: COMPLETED goal: Find all pricing information created_at: '2024-01-01T00:00:00Z' started_at: '2024-01-01T00:00:05Z' finished_at: '2024-01-01T00:00:30Z' result: product: iPhone 15 price: $799 error: null not_found: - b2c3d4e5-f6a7-8901-bcde-f23456789012 '400': description: Invalid request - empty array, exceeds 100 IDs, or malformed input content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message required: - error description: Standard error response format '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message required: - error description: Standard error response format '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message required: - error description: Standard error response format security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Get your key from the API Keys page. ````