--- title: "Get multiple runs by ID" method: POST path: "/agent/runs/batch-get" tags: ["Agents"] --- # Get multiple runs by ID `POST /agent/runs/batch-get` ## Request - Base URL: `https://app.warp.dev/api/v1` - URL: `https://app.warp.dev/api/v1/agent/runs/batch-get` - Auth: HTTP bearer Retrieve run details for 1–100 run IDs. Returns a top-level array in input order, preserving duplicates with one result per input occurrence. Each result contains the requested run_id and exactly one of `run`, the same run object returned by getRun, or `error`, the standard API error getRun would return for that ID. Authorization and per-run errors follow getRun semantics. Completed batches return HTTP 200 even when every result is an error; shared infrastructure failures fail the request with HTTP 500. ## Request body - BatchGetRunsRequest - `run_ids` string[], required: Run IDs to retrieve, in result order. Duplicates are preserved. ## Response `200` One run or error per requested ID - BatchGetRunResult[] - union: Result for one requested run ID. Exactly one of `run` or `error` is present. - BatchGetRunSuccess - `run_id` string, required: Requested run ID, echoed from the request. - `run` RunItem, required - `run_id` string, required: Unique identifier for the run - `task_id` string, required: Unique identifier for the task (typically matches run_id). Deprecated - use run_id instead. - `title` string, required: Human-readable title for the run - `state` 'QUEUED' | 'PENDING' | 'CLAIMED' | 'INPROGRESS' | 'SUCCEEDED' | 'FAILED' | 'BLOCKED' | 'ERROR' | 'CANCELLED', required: Current state of the run: - QUEUED: Run is waiting to be picked up - PENDING: Run is being prepared - CLAIMED: Run has been claimed by a worker - INPROGRESS: Run is actively being executed - SUCCEEDED: Run completed successfully - FAILED: Run failed - BLOCKED: Run is blocked (e.g., awaiting user input or approval) - ERROR: Run encountered an error - CANCELLED: Run was cancelled by user - `execution_location` 'LOCAL' | 'REMOTE': Execution location of the run's latest execution, including ended executions: - LOCAL: The latest execution is assigned to the machine running Warp or Oz, or to the same process as its cloud parent. - REMOTE: The latest execution is remote or unassigned, or the run has no executions. This is not a liveness indicator. A newer execution can change the classification; the task's legacy worker assignment is ignored. - `prompt` string, required: The prompt/instruction for the agent - `submitted_prompt` string: The prompt exactly as it was submitted, without any extra context added by Warp. Includes any follow-up messages sent before the run started, separated by blank lines. - `created_at` string, date-time, required: Timestamp when the run was created (RFC3339) - `updated_at` string, date-time, required: Timestamp when the run was last updated (RFC3339) - `run_time` string, duration: Total runtime as an ISO 8601 duration (e.g. "PT2M30S"), computed server-side from run executions. - `started_at` string, date-time, nullable: Timestamp when the agent started working on the run (RFC3339) - `finished_at` string, date-time, nullable, required: Timestamp when the run last reached a terminal state (RFC3339). Null while the run is still active, and for terminal runs with no recorded finish time (runs executed locally, and runs that finished before finish times were recorded). - `status_message` RunStatusMessage: Status message for a run. For terminal error states, includes structured error code and retryability info from the platform error catalog. - `message` string, required: Human-readable status message - `error_code` 'insufficient_credits' | 'feature_not_available' | 'external_authentication_required' | 'not_authorized' | 'invalid_request' | 'resource_not_found' | 'budget_exceeded' | 'integration_disabled' | 'integration_not_configured' | 'operation_not_supported' | 'environment_setup_failed' | 'content_policy_violation' | 'conflict' | 'authentication_required' | 'resource_unavailable' | 'agent_stream_network_error' | 'agent_stream_failure' | 'internal_error': Machine-readable error code identifying the problem type. Used in the `type` URI of Error responses and in the `error_code` field of RunStatusMessage. User errors (run transitions to FAILED): - `insufficient_credits` — Team has no remaining add-on credits - `feature_not_available` — Required feature not enabled for user's plan - `external_authentication_required` — User hasn't authorized a required external service - `not_authorized` — Principal lacks permission for the requested operation - `invalid_request` — Request is malformed or contains invalid parameters - `resource_not_found` — Referenced resource does not exist - `budget_exceeded` — Spending budget limit has been reached - `integration_disabled` — Integration is disabled and must be enabled - `integration_not_configured` — Integration setup is incomplete - `operation_not_supported` — Requested operation not supported for this resource/state - `environment_setup_failed` — Client-side environment setup failed - `content_policy_violation` — Prompt or setup commands violated content policy - `conflict` — Request conflicts with the current state of the resource Warp errors (run transitions to ERROR): - `authentication_required` — Request lacks valid authentication credentials - `resource_unavailable` — Transient infrastructure issue (retryable) - `agent_stream_network_error` — MAA response stream terminally failed because of a transport or EOF error - `agent_stream_failure` — MAA server explicitly reported a terminal response stream failure - `internal_error` — Unexpected server-side error (retryable) - `retryable` boolean: Whether the error is transient and the client may retry by submitting a new run. Only present on terminal error states. When false, retrying without addressing the underlying cause will not succeed. - `session_debug_until` string, date-time: When a failed run's shared session stops being held open for debugging. Only present while that window is open. The window is an idle window owned by the agent process: activity in the session pushes this deadline out. The agent republishes it periodically rather than on every keystroke, so the value can lag the true deadline by up to a throttle interval, and always in the conservative direction. - `debug_agent_active` boolean: Whether a setup-failure debug turn is actively pinning the idle timer open right now. While true, session_debug_until can lag behind the real deadline; clients should show an active-debugging state instead of a countdown. - `source` 'LINEAR' | 'API' | 'MCP' | 'SLACK' | 'TEAMS' | 'LOCAL' | 'SCHEDULED_AGENT' | 'WEB_APP' | 'GITHUB_ACTION' | 'CLOUD_MODE' | 'CLI' | 'JIRA' | 'SELF_IMPROVEMENT' | 'GITHUB_WEBHOOK' | 'GITLAB_WEBHOOK' | 'AZURE_DEVOPS_WEBHOOK' | 'AUTOFIX' | 'RUN_SCORER' | 'ORCHESTRATION' | 'BENCHMARK_TRIAL' | 'CREATE_BENCHMARK_TASK' | 'CUSTOM_WEBHOOK': Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API - MCP: Created through the Factory MCP server's send_task tool - SLACK: Created from Slack integration - TEAMS: Created from Microsoft Teams integration - LOCAL: Created from local CLI/app - SCHEDULED_AGENT: Created by a scheduled agent - WEB_APP: Created from the Warp web app - GITHUB_ACTION: Created from a GitHub action - CLOUD_MODE: Created from a Cloud Mode - CLI: Created from the CLI - JIRA: Created from Jira integration - SELF_IMPROVEMENT: Created by Warp's self-improvement pipeline - GITHUB_WEBHOOK: Created from a GitHub webhook event - GITLAB_WEBHOOK: Created from a GitLab webhook event - AZURE_DEVOPS_WEBHOOK: Created from an Azure DevOps webhook event - AUTOFIX: Created by Warp's autofix pipeline - RUN_SCORER: Created by Warp's run-scoring judge - ORCHESTRATION: Created as a child run by the orchestration layer (parent_run_id set) - BENCHMARK_TRIAL: Created as a factory benchmark trial - CREATE_BENCHMARK_TASK: Created by a Factory foreman authoring a benchmark task from a completed run - CUSTOM_WEBHOOK: Created by a factory automation subscribed to a custom webhook source - `schedule` ScheduleInfo: Information about the schedule that triggered this run (only present for scheduled runs) - `schedule_id` string, required: Unique identifier for the schedule - `schedule_name` string, required: Name of the schedule at the time the run was created - `cron_schedule` string, required: Cron expression at the time the run was created - `session_id` string: UUID of the shared session (if available) - `session_link` string, uri: URL to view the agent session - `trigger_url` string, uri: URL to the run trigger (e.g. Slack thread, Linear issue, schedule) - `creator` RunCreatorInfo - `type` 'user' | 'service_account': Type of the creator principal - `uid` string: Unique identifier of the creator - `display_name` string: Display name of the creator - `email` string: Email address of the creator - `photo_url` string, uri: URL to the creator's photo - `executor` RunCreatorInfo - `type` 'user' | 'service_account': Type of the creator principal - `uid` string: Unique identifier of the creator - `display_name` string: Display name of the creator - `email` string: Email address of the creator - `photo_url` string, uri: URL to the creator's photo - `factory_uid` string: UID of the factory whose agent executed the run. Absent for runs not executed by a factory agent. - `request_usage` RequestUsage: Resource usage information for the run - `inference_cost` number, double: Credits consumed by LLM inference for the run - `compute_cost` number, double: Credits consumed by compute resources for the run - `platform_cost` number, double: Credits consumed by platform usage for the run - `inference_cost_usd` number, double: What the run's LLM inference was billed at, in US dollars. Runs that predate billed-amount tracking fall back to an estimated cost. - `compute_cost_usd` number, double: What the run's hosted compute was billed at, in US dollars. Runs that predate billed-amount tracking fall back to an estimated cost. - `platform_cost_usd` number, double: What the run's platform usage was billed at, in US dollars. Runs that predate billed-amount tracking fall back to an estimated cost. - `platform_duration_seconds` number, double: Recorded billable platform runtime for this run, in seconds. Omitted when unavailable; zero when recorded as zero. - `total_tokens` integer: Total LLM token count (summed across every usage category and model) for the run's conversation. Omitted when the data is not available. - `usage_by_category` object: Full-granularity token and charged-cost breakdown for the run's conversation, keyed by usage category (for example, primary_agent or conversation_compaction) and model id. Omitted when the data is not available. - `model_token_usage` ModelTokenUsage[]: The models that actually served inference for the run, with the tokens each consumed. Used to discover what an auto-routing model resolves to. If a run is terminated before inference is complete, output a zero-token entry for that model. Omits runs that use a third-party harness, whose per-model usage is not tracked by Warp. - `model_id` string, required: Identifier of the model that served the inference. For `warp` and `byok` usage this is a model id drawn from the same set as `agent_config.model_id`. For `custom_endpoint` usage this is the caller's own configuration key for the endpoint. - `total_tokens` integer, required: Total tokens this model consumed, across every usage category. - `usage_type` 'warp' | 'byok' | 'custom_endpoint', required: How a model's inference was accessed: - warp: through Warp-provided model access - byok: through the caller's own provider API key - custom_endpoint: through a caller-configured model endpoint - `tokens_by_category` object: total_tokens split by the kind of work the tokens were spent on, keyed by usage category (e.g., primary_agent, tool_summarization, etc). - `agent_config` AmbientAgentConfig: Configuration for a cloud agent run - `name` string: Human-readable label for grouping, filtering, and traceability. Automatically set to the skill name when running a skill-based agent. Set this explicitly to categorize runs by intent (e.g., "nightly-dependency-check") so you can filter and track them via the name query parameter on GET /agent/runs. - `model_id` string: LLM model to use (uses team default if not specified) - `base_prompt` string: Custom base prompt for the agent - `environment_id` string: UID of the environment to run the agent in - `secrets` SecretRef[]: Optional run-specific managed secret allowlist. Omission and an empty array both add no generic secrets. Secret references from the resolved environment and execution principal are still unioned into the run's secret scope. - `name` string, required: Name of the managed secret. - `runner_id` string: UID of the runner providing the run's compute (platform, instance shape, and setup commands). When omitted on a request, the runner is resolved at run creation from the agent's default runner, then the environment's default runner, and the resolved UID is recorded on the run. - `skill_spec` string: Skill specification identifying the primary agent skill to use, in `{owner}/{repo}:{skill_path}` format (e.g. `warpdotdev/warp-server:.claude/skills/deploy/SKILL.md`); mutually exclusive with `skills` in create/update requests. Responses include the first `skills` entry here for backward compatibility; use the list agents endpoint to discover available skills. - `skills` string[]: Ordered skill specifications to attach to the run. Format: "{owner}/{repo}:{skill_path}" Example: "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md" Mutually exclusive with skill_spec in create/update requests. - `mcp_servers` object: Map of MCP server configurations by name - `computer_use_enabled` boolean: Controls whether computer use is enabled for this agent. If not set, defaults to true. - `computer_use_model_id` string: Model the computer use subagent runs on; if omitted, the subagent picks its own model automatically. Only applies to the built-in Warp harness — the value is accepted but has no effect under a third-party harness or when computer use is disabled. Requires an agent CLI version that supports the --computer-use-model flag. - `idle_timeout_minutes` integer: Number of minutes to keep the agent environment alive after task completion. Set to 0 to shut down immediately after task completion. If not set, defaults to 10 minutes. Maximum allowed value is min(60, floor(max_instance_runtime_seconds / 60) for your billing tier). - `worker_host` string: Self-hosted worker ID that should execute this task. If not specified or set to "warp", the task runs on Warp-hosted workers. - `harness` Harness: Specifies which execution harness to use for the agent run. Default (nil/empty) uses Warp's built-in harness. When stored as a named agent's default (create/update agent identity), this field replaces the deprecated base_harness/base_model pair: a harness other than `oz` here requires the agent's base_model to be empty, since the two describe mutually exclusive default models. - `type` union: The harness type identifier: `oz` for Warp's built-in harness (default), or any third-party harness. - … - `model_id` string: Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a harness other than `oz`; the top-level config model_id targets the built-in Warp harness instead. When omitted or empty, the harness uses its own default model. For an individual Warp-managed Factory Claude Code agent, send an explicit empty string to use the environment's model. Omitting model_id when replacing that agent's harness is invalid. - `reasoning_level` string: Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a harness other than `oz`. Ignored by harnesses that do not support reasoning levels. - `harness_auth_secrets` HarnessAuthSecrets: Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment. - `claude_auth_secret_name` string: Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude". - `codex_auth_secret_name` string: Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex". - `pi_auth_secret_name` string: Name of a managed secret for Pi harness authentication. The secret must exist within the caller's personal or team scope and must be a credential for the model provider named by the provider prefix of harness.model_id. Only applicable when harness type is "pi". - `session_sharing` SessionSharingConfig: Configures sharing behavior for the run's shared session; when set, the worker emits `--share public:` and the bundled Warp client applies an anyone-with-link ACL to the shared session once it has bootstrapped. The same ACL is mirrored onto the backing conversation so link viewers can read it without being on the run's team, subject to the workspace-level anyone-with-link sharing setting. - `public_access` 'VIEWER' | 'EDITOR': Grants anyone-with-link access at the specified level to the run's shared session and backing conversation; link viewers must still be authenticated Warp users (anonymous reads are not supported in this release). - VIEWER: link viewers can read the session and conversation. - EDITOR: link viewers can also interact with the session. - `memory_stores` MemoryStoreRef[]: Memory stores to attach to this run. - `uid` string, required: UID of the memory store. - `access` 'read_write' | 'read_only', required: Access level for the store. - `instructions` string, required: Instructions for how the agent should use this memory store. Must not be empty. - `inference_providers` InferenceProvidersConfig: Inference provider settings used for LLM calls. - `aws` AwsInferenceProviderConfig: Configures AWS Bedrock as the LLM inference provider for this agent or run. - … - `credential_strategy` 'CREATOR' | 'EXECUTOR', nullable: Controls which principal's credentials are used when the platform mints tokens (e.g. GitHub or GitLab OAuth tokens) on behalf of this run. - EXECUTOR (default when unset): credentials are sourced from the run's execution principal — a GitHub App installation token for agent principals, a personal OAuth token for user principals. - CREATOR: credentials are always sourced from the run creator regardless of the execution principal, useful when a service account executes the run but Git operations should authenticate as the triggering human. - `conversation_id` string: UUID of the conversation associated with the run - `parent_run_id` string: UUID of the parent run that spawned this run - `root_run_id` string, required: UUID of the top-level run of this run's orchestration tree. Equals `run_id` for a top-level run. - `metadata` RunMetadata: Custom key/value metadata attached to a run at creation time and immutable afterward; at most 20 keys, with keys 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive) and values 0-256 bytes of UTF-8 with no NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs). - `is_sandbox_running` boolean: Whether the sandbox environment is currently running - `is_run_type_cancellable` boolean: Whether the run's type is eligible for cancellation via the API. State-independent: false for GitHub Action and local runs; true for all other run types (including self-hosted). Clients should still gate the control on the run's current state. - `debug_agent_available` boolean: Whether a debug agent can currently be started inside this run's retained setup-failure session. Only true for a run that failed during environment setup, whose retained execution is still reachable, and whose debug window has not closed. See `POST /agent/runs/{runId}/followups`. - `artifacts` ArtifactItem[]: Artifacts created during the run (plans, pull requests, etc.) - union - PlanArtifact - … - PullRequestArtifact - … - ScreenshotArtifact - … - FileArtifact - … - ExternalReferenceArtifact - … - `diagnostics` RunDiagnostic[]: Diagnostics for this run, only included on request. - `message` string, required - `code` string, required - `data` object - `timestamp` string, date-time - `created_at` string, date-time: When the diagnostic was recorded. - `agent_skill` AgentSkill: Information about the agent skill used for the run. Either full_path or bundled_skill_id will be set, but not both. - `name` string: Human-readable name of the skill - `description` string: Description of the skill - `full_path` string: Path to the SKILL.md file (for file-based skills) - `bundled_skill_id` string: Unique identifier for bundled skills - `scope` Scope: Ownership scope for a resource (team or personal) - `type` 'User' | 'Team', required: Type of ownership ("User" for personal, "Team" for team-owned) - `uid` string: UID of the owning user or team - BatchGetRunError - `run_id` string, required: Requested run ID, echoed from the request. - `error` Error, required: Error response following RFC 7807 (Problem Details for HTTP APIs), using the `application/problem+json` content type. Includes backward-compatible extension members; additional ones (e.g., `auth_url`, `provider`) may be present depending on the error code. - `type` string, uri, required: A URI reference that identifies the problem type (RFC 7807). Documentation: `https://docs.warp.dev/factories/api-and-sdk/troubleshooting/errors/{error_code}` See PlatformErrorCode for the list of possible error codes. - `title` string, required: A short, human-readable summary of the problem type (RFC 7807) - `status` integer, required: The HTTP status code for this occurrence of the problem (RFC 7807) - `detail` string: A human-readable explanation specific to this occurrence of the problem (RFC 7807) - `instance` string: The request path that generated this error (RFC 7807) - `error` string, required: Human-readable error message combining title and detail. Backward-compatible extension member for older clients. - `retryable` boolean: Whether the request can be retried. When true, the error is transient and the request may be retried. When false, retrying without addressing the underlying cause will not succeed. - `trace_id` string: OpenTelemetry trace ID for debugging and support requests - `provider` string: External provider that requires authorization, such as `linear`. - `auth_url` string, uri: URL where the caller can reconnect the external provider. ## Other responses - `400`: Malformed body or invalid run_ids list - `401`: Authentication required - `500`: Internal server error ## Changes - **2026-11-04** `4b5d145669be`: 1 info - endpoint added [Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/agent/runs/batch-get/post.md) --- [API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)