WAwarp
Agents

List agent runs

Changed on

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

get/agent/runs

Request

  • Base URL
    https://app.warp.dev/api/v1
  • Auth
    HTTP bearer

Query parameters

limitinteger

Maximum number of runs to return

cursorstring

Pagination cursor from previous response

sort_by'updated_at' | 'created_at' | 'title' | 'agent'

Sort field for results.

  • updated_at: Sort by last update timestamp (default)
  • created_at: Sort by creation timestamp
  • title: Sort alphabetically by run title
  • agent: Sort alphabetically by skill. Runs without a skill are grouped last.
sort_order'asc' | 'desc'

Sort direction

stateRunState[]

Filter by run state. Can be specified multiple times to match any of the given states.

task_statusstring[]

Filter by high-level task status. Can be specified multiple times to match any value. running matches when the root or any descendant is queued, pending, claimed, or in progress. failed, blocked, cancelled, and complete match the root state only.

namestring

Filter by agent config name

model_idstring

Filter by model ID

creatorstring

Filter by creator UID (user or service account)

executorstring

Filter by the user or agent that executed the run. This will often be the same as the creator, but not always: users may delegate tasks to agents.

sourceRunSourceType[]

Filter by run source type. Can be specified multiple times to match any of the given sources.

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.

Filter by where the run executed

created_afterstring date-time

Filter runs created after this timestamp (RFC3339 format)

created_beforestring date-time

Filter runs created before this timestamp (RFC3339 format)

updated_afterstring date-time

Filter runs updated after this timestamp (RFC3339 format)

environment_idstring

Filter runs by environment ID. Passing the literal value empty-environment matches runs with no environment configured, rather than omitting the parameter, which applies no environment filter at all. empty-environment can never collide with a real environment ID: every environment ID is exactly 22 characters drawn from [A-Za-z0-9], while this sentinel contains a hyphen and is a different length.

skillstring

Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md"). Alias for skill_spec.

skill_specstring

Filter runs by skill spec (e.g., "owner/repo:path/to/SKILL.md")

schedule_idstring

Filter runs by the scheduled agent ID that created them

string
OR
string[]

Filter runs by one or more factories. Repeating this parameter matches runs executed by an agent from any selected factory. A UID outside the caller's accessible factories matches nothing.

ancestor_run_idstring

Filter runs by ancestor run ID. The referenced run must exist and be accessible to the caller.

metadataobject

Filter by exact metadata key/value pairs using object notation (e.g. metadata[ticket_id]=ACME-238), combining multiple pairs with AND semantics, up to 5 per request. Returns feature_not_available when metadata filtering is not enabled.

artifact_type'PLAN' | 'PULL_REQUEST' | 'SCREENSHOT' | 'FILE' | 'EXTERNAL_REFERENCE'

Filter runs by artifact type

qstring

Search by full run ID or run URL, or fuzzy match across run title, prompt, and skill_spec

Headers

X-Warp-Team-Uidstring

UID of the team to use as the request's active team. Ignored for service-account callers, which always act as their bound team.

Response

List of runs

as_ofstring date-time required

Time the runs were read (RFC3339). Data can lag live activity by a few minutes.

team_uidstring nullable required

UID of the team the request was scoped to: the team selected by the X-Warp-Team-Uid header, or the API key's team. Null when a user request has no team selected and the list spans every team the user belongs to.

Changes

  • 4b5d145669beRevision changes
    • info

      added the optional property // to the response with the status

    • info

      added the optional property /// to the response with the status

  • 2c45dcc0a13eRevision changes
    • breaking

      response property runs/items/agent_config/credential_strategy list-of-types was widened by adding types null to media type application/json of response 200

    • breaking

      added subschema #1 to the //// response property oneOf list for the response status

    • breaking

      the //// response's property type changed from string to no type for status

    • breaking

      removed the required property ////////// from the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property ///////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      removed the CREATOR enum value from the /// response property for the response status

    • info

      removed the EXECUTOR enum value from the /// response property for the response status

    • info

      removed the claude enum value from the //// response property for the response status

    • info

      removed the codex enum value from the //// response property for the response status

    • info

      removed the gemini enum value from the //// response property for the response status

    • info

      removed the oz enum value from the //// response property for the response status

    • info

      added the required property ///// to the response with the status