Skip to main content
GET
/
api
/
agents
List agents
curl --request GET \
  --url https://api.example.com/api/agents
Returns all agents across the authenticated user’s organizations. Each agent includes run counts and last-run metadata, all excluding sandbox runs. Set include_relations=true to also include triggers and tools.

​
Query parameters

​
include_relations
string
default:"false"
Set to "true" to include triggers and tools in each agent. Defaults to "false" for a leaner payload.

​
Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "items": [
      {
        "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "organization_uid": "550e8400-e29b-41d4-a716-446655440000",
        "agent_type": "concierge",
        "name": "Communications Concierge",
        "description": "Handles inbound emails and triages based on intent",
        "instructions": "You are a communications concierge...",
        "status": "active",
        "created_by_uid": "660e8400-e29b-41d4-a716-446655440000",
        "notification_config": {
          "slack_channel_id": "C0123456789",
          "events": {
            "action_taken": true,
            "approval_required": true,
            "outcome": true,
            "error": true,
            "digest": false
          }
        },
        "runs_count": 42,
        "completed_count": 38,
        "failed_count": 4,
        "last_run": "2026-03-18T09:10:00Z",
        "last_run_status": "completed",
        "created_on": "2026-02-10T14:30:00Z",
        "updated_on": "2026-03-18T09:15:00Z",
        "triggers": [
          {
            "uid": "t1-uuid",
            "agent_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "trigger_type": "email_received",
            "configuration": null,
            "is_active": true,
            "created_on": "2026-02-10T14:30:00Z",
            "updated_on": "2026-02-10T14:30:00Z"
          }
        ],
        "tools": [
          {
            "uid": "tool1-uuid",
            "agent_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "tool_type": "send_email",
            "configuration": null,
            "is_active": true,
            "created_on": "2026-02-10T14:30:00Z",
            "updated_on": "2026-02-10T14:30:00Z"
          }
        ]
      }
    ]
  }
}

​
Agent fields

FieldTypeDescription
runs_countintegerTotal non-sandbox runs
completed_countintegerNon-sandbox runs that completed successfully
failed_countintegerNon-sandbox runs that failed
last_runstring | nullISO 8601 timestamp of the most recent non-sandbox run (completed_on, or created_on if still running). null when there are no non-sandbox runs.
last_run_statusstring | nullStatus of the most recent non-sandbox run: completed, failed, running, pending, or cancelled. A run with status completed but result.success = false is normalized to failed. null when there are no non-sandbox runs.
Triggers and tools arrays are only included when include_relations=true. Without it, the response omits these fields for faster loading.
All run counts and last-run metadata exclude sandbox runs, focusing on production execution only.