Skip to Content
DocumentationIntegrationCursorList Agents

List Agents

Retrieves a list of all background agents for the authenticated user. This allows you to monitor active agents, check their status, and retrieve agent IDs for follow-up actions.

Overview

  • Purpose: Get a comprehensive list of all your background agents with their current status and details.
  • Use Cases: Monitoring agent progress, finding agent IDs for follow-ups or deletion, tracking completed work, auditing agent activity.
  • API Method: GET /v0/agents

Input Fields

No Input Required: This action does not require any input parameters. It returns all agents associated with your authenticated account.

Output

Returns an array of agent objects, each containing:

  • Agent ID: Unique identifier for the agent.
  • Name: Human-readable name of the agent.
  • Status: Current status - CREATING, RUNNING, FINISHED, ERROR, or EXPIRED.
  • Source: Repository URL and ref (branch/tag/commit) the agent is working on.
  • Target: Branch name, Cursor Web URL, PR URL (if created), and PR configuration settings.
  • Summary: Brief description of the agent’s task and progress.
  • Created At: Timestamp when the agent was created (ISO 8601 format).

Agent Status Meanings

  • CREATING: Agent is being initialized and will start working soon.
  • RUNNING: Agent is actively working on the task.
  • FINISHED: Agent has completed its work successfully.
  • ERROR: Agent encountered an error and stopped. Check the summary for details.
  • EXPIRED: Agent session has expired and can no longer be used.

Pagination

Next Cursor: If present in the response, indicates there are more agents to retrieve. Use this cursor value in subsequent requests to fetch the next page of results.

Tips

[!TIP] Use this action regularly to monitor the progress of your agents

[!TIP] Filter agents by status in your workflow logic to handle different states appropriately

[!TIP] Save agent IDs from the list to use in follow-up or delete actions

[!TIP] Check the ‘prUrl’ field to quickly access pull requests created by agents

[!TIP] Use the ‘target.url’ field to view the agent’s work in Cursor Web interface

[!TIP] Monitor for ERROR status agents and review their summaries to understand what went wrong

Need help? Have feedback?
Delete AgentList Models