---
title: "List agent runs"
method: GET
path: "/agent/runs"
tags: ["agent"]
---

# List agent runs

`GET /agent/runs`

Retrieve a paginated list of agent runs with optional filtering.
Results default to `sort_by=updated_at` and `sort_order=desc`.

## Query parameters

- `limit` integer
- `cursor` string
- `sort_by` 'updated_at' | 'created_at' | 'title' | 'agent'
- `sort_order` 'asc' | 'desc'
- `state` RunState[]
- `name` string
- `model_id` string
- `creator` string
- `executor` string
- `source` 'LINEAR' | 'API' | 'SLACK' | 'LOCAL' | 'SCHEDULED_AGENT' | 'WEB_APP' | 'GITHUB_ACTION' | 'CLOUD_MODE' | 'CLI' | 'JIRA' | 'SELF_IMPROVEMENT' | 'GITHUB_WEBHOOK' | 'GITLAB_WEBHOOK' | 'AUTOFIX' | 'RUN_SCORER' | 'ORCHESTRATION' — Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API - SLACK: Created from Slack 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 - 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)
- `execution_location` 'LOCAL' | 'REMOTE' — Where the run executed: - LOCAL: Executed in the user's local Oz environment - REMOTE: Executed by a remote/cloud worker
- `created_after` string, date-time
- `created_before` string, date-time
- `updated_after` string, date-time
- `environment_id` string
- `skill` string
- `skill_spec` string
- `schedule_id` string
- `ancestor_run_id` string
- `metadata` object
- `artifact_type` 'PLAN' | 'PULL_REQUEST' | 'SCREENSHOT' | 'FILE' | 'EXTERNAL_REFERENCE'
- `q` string

## Response `200`

List of runs

- ListRunsResponse
  - `runs` 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' — Where the run executed: - LOCAL: Executed in the user's local Oz environment - REMOTE: Executed by a remote/cloud worker
    - `prompt` string, required — The prompt/instruction for the agent
    - `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)
    - `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' | '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) - `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.
    - `source` 'LINEAR' | 'API' | 'SLACK' | 'LOCAL' | 'SCHEDULED_AGENT' | 'WEB_APP' | 'GITHUB_ACTION' | 'CLOUD_MODE' | 'CLI' | 'JIRA' | 'SELF_IMPROVEMENT' | 'GITHUB_WEBHOOK' | 'GITLAB_WEBHOOK' | 'AUTOFIX' | 'RUN_SCORER' | 'ORCHESTRATION' — Source that created the run: - LINEAR: Created from Linear integration - API: Created via the Warp API - SLACK: Created from Slack 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 - 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)
    - `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
    - `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 — inference_cost in US dollars, converted at a fixed rate. An approximate cost, not a billed amount.
      - `compute_cost_usd` number, double — compute_cost in US dollars, converted at a fixed rate. An approximate cost, not a billed amount.
      - `platform_cost_usd` number, double — platform_cost in US dollars, converted at a fixed rate. An approximate cost, not a billed amount.
    - `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
      - `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. Format: "{owner}/{repo}:{skill_path}" Example: "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.
      - `idle_timeout_minutes` integer — Number of minutes to keep the agent environment alive 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 non-oz type here requires the agent's base_model to be empty, since the two describe mutually exclusive default models.
        - `type` 'oz' | 'claude' | 'gemini' | 'codex' — The harness type identifier. - oz: Warp's built-in harness (default) - claude: Claude Code harness - gemini: Gemini CLI harness - codex: Codex CLI harness
        - `model_id` string — Model to use with a third-party harness (e.g. "claude-haiku-4-5"). Only applies when type is a non-oz harness; the top-level config model_id targets the built-in Oz harness instead. When omitted or empty, the harness uses its own default model.
        - `reasoning_level` string — Reasoning effort for harnesses that support it (e.g. Codex). Only applies when type is a non-oz harness. 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".
      - `session_sharing` SessionSharingConfig — Configures sharing behavior for the run's shared session. When set, the worker emits `--share public:<level>` 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 the conversation 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. - VIEWER: link viewers can read the session and conversation. - EDITOR: link viewers can also interact with the session. Anonymous (unauthenticated) reads are not supported in this release; link viewers must still be authenticated Warp users.
      - `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.
          - `disabled` boolean — If true, opt out of Bedrock at this layer.
          - `role_arn` string — IAM role ARN to assume when calling Bedrock.
          - `region` string — AWS region used for STS when assuming the Bedrock inference role.
      - `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. For agent principals this produces a GitHub App installation token; for user principals this produces their personal OAuth token. - 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 human who triggered it. When unset, behavior is identical to EXECUTOR and no additional pre-flight validation is performed.
    - `conversation_id` string — UUID of the conversation associated with the run
    - `parent_run_id` string — UUID of the parent run that spawned this run
    - `metadata` RunMetadata — Custom key/value metadata attached to a run at creation time and immutable afterward. At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain 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.
    - `artifacts` ArtifactItem[] — Artifacts created during the run (plans, pull requests, etc.)
      - union
        - PlanArtifact
          - `artifact_type` 'PLAN', required — Type of the artifact
          - `created_at` string, date-time, required — Timestamp when the artifact was created (RFC3339)
          - `data` PlanArtifactData, required
            - `artifact_uid` string — Unique identifier for the plan artifact, usable with the artifact retrieval endpoint
            - `document_uid` string, required — Unique identifier for the plan document
            - `notebook_uid` string — Unique identifier for the associated notebook
            - `url` string, uri — URL to open the plan in Warp Drive
            - `title` string — Title of the plan
        - PullRequestArtifact
          - `artifact_type` 'PULL_REQUEST', required — Type of the artifact
          - `created_at` string, date-time, required — Timestamp when the artifact was created (RFC3339)
          - `data` PullRequestArtifactData, required
            - `url` string, uri, required — URL of the pull request
            - `branch` string, required — Branch name for the pull request
        - ScreenshotArtifact
          - `artifact_type` 'SCREENSHOT', required — Type of the artifact
          - `created_at` string, date-time, required — Timestamp when the artifact was created (RFC3339)
          - `data` ScreenshotArtifactData, required
            - `artifact_uid` string, required — Unique identifier for the screenshot artifact
            - `mime_type` string, required — MIME type of the screenshot image
            - `description` string — Optional description of the screenshot
        - FileArtifact
          - `artifact_type` 'FILE', required — Type of the artifact
          - `created_at` string, date-time, required — Timestamp when the artifact was created (RFC3339)
          - `data` FileArtifactData, required
            - `artifact_uid` string, required — Unique identifier for the file artifact
            - `filepath` string, required — Conversation-relative filepath for the uploaded file
            - `filename` string, required — Last path component of filepath
            - `title` string — Short, badge-visible label for the artifact. For recording artifacts, this is the agent-authored title shown in Oz web and blocklist badges. Distinct from description, which is longer and shown in detail views.
            - `description` string — Optional description of the file
            - `mime_type` string, required — MIME type of the uploaded file
            - `size_bytes` integer — Size of the uploaded file in bytes
        - ExternalReferenceArtifact
          - `artifact_type` 'EXTERNAL_REFERENCE', required — Type of the artifact
          - `created_at` string, date-time, required — Timestamp when the artifact was created (RFC3339)
          - `data` ExternalReferenceArtifactData, required — Data for a generic external reference artifact.
            - `reference_type` string, required — Free-form category identifier for this reference (e.g. "linear_issue", "spec_link", "jira_ticket"). Used for filtering and display.
            - `url` string, required — Canonical URL for the reference. Used as the key for reverse lookups ("which run produced this URL?").
            - `title` string — Optional human-readable label for the reference.
            - `metadata` object — Optional category-specific extra fields.
    - `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
  - `page_info` PageInfo, required
    - `has_next_page` boolean, required — Whether there are more results available
    - `next_cursor` string — Opaque cursor for fetching the next page

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication required
- `403` — Metadata filtering is not enabled for this environment

---

[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-service-production.skmtc.workers.dev/v1/apis/warp/oz-agent-api/revisions/a0daf9e59774/schema)