---
title: "Get run details"
method: GET
path: "/agent/runs/{runId}"
tags: ["agent"]
---

# Get run details

`GET /agent/runs/{runId}`

Retrieve detailed information about a specific agent run, 
including the full prompt, session link, and resolved configuration.

## Path parameters

- `runId` string, required

## Response `200`

Run details

- RunItem
  - `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.
  - `source` 'LINEAR' | 'API' | 'SLACK' | 'LOCAL' | 'SCHEDULED_AGENT' | 'WEB_APP' | 'GITHUB_ACTION' | 'CLOUD_MODE' | 'CLI' — 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
  - `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 — Cost of LLM inference for the run
    - `compute_cost` number, double — Cost of compute resources for the run
    - `platform_cost` number, double — Cost of platform usage for the run
  - `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
    - `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 false.
    - `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.
      - `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
    - `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.
  - `conversation_id` string — UUID of the conversation associated with the run
  - `parent_run_id` string — UUID of the parent run that spawned this run
  - `is_sandbox_running` boolean — Whether the sandbox environment is currently running
  - `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
          - `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
  - `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

## Other responses

- `400` — Missing run ID
- `401` — Authentication required
- `403` — No permission to access run
- `404` — Run not found

---

[API](https://skmtc.net/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.net/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/warp/oz-agent-api/versions/97be876c33e3/schema)