Skip to main content
GET
/
api
/
agents
/
{agent_uid}
/
activities
List activities
curl --request GET \
  --url https://api.example.com/api/agents/{agent_uid}/activities
Returns a paginated list of runs for a specific agent. Supports filtering by status, date ranges, and grouping.

​
Path parameters

​
agent_uid
string
required
UUID of the agent.

​
Query parameters

​
Filtering

​
status
string
Filter by run status. Comma-separated for multiple values.Values: pending, running, completed, failed, cancelled, stopped.
GET /api/agents/{agent_uid}/activities?status=completed,failed
​
started_on_from
string
Filter runs started on or after this ISO 8601 datetime. Must include timezone.
GET /api/agents/{agent_uid}/activities?started_on_from=2026-03-01T00:00:00Z
​
started_on_to
string
Filter runs started on or before this ISO 8601 datetime.
​
completed_on_from
string
Filter runs completed on or after this ISO 8601 datetime.
​
completed_on_to
string
Filter runs completed on or before this ISO 8601 datetime.
​
created_on_from
string
Filter runs created on or after this ISO 8601 datetime.
​
created_on_to
string
Filter runs created on or before this ISO 8601 datetime.
​
has_started
boolean
If true, only runs that have started. If false, only runs that haven’t started yet.
​
has_completed
boolean
If true, only completed runs. If false, only in-progress or pending runs.

​
Grouping and pagination

​
group_by
string
default:"none"
Grouping mode. One of: none, trigger.
​
sort
string
default:"-started_on"
Sort field. Prefix with + (ascending) or - (descending).Supported fields: started_on, completed_on, created_on, status.
​
page
integer
default:"1"
Page number.
​
per_page
integer
default:"10"
Items per page.

​
Sparse fields

​
fields[agent-runs]
string
Comma-separated list of fields to include on each run. Use to request token_usage (requires permission) or limit payload size.

​
Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "items": [
      {
        "id": "run-uuid-here",
        "type": "agent-runs",
        "attributes": {
          "agent_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "agent_version_uid": "ver-uuid-here",
          "scratchpad_uid": "sp-uuid-here",
          "workflow_id": "agent-loop-a1b2c3d4",
          "approach": "loop",
          "status": "completed",
          "sandbox": false,
          "trigger_type": "email_received",
          "started_on": "2026-03-19T14:30:00Z",
          "completed_on": "2026-03-19T14:31:15Z",
          "created_on": "2026-03-19T14:30:00Z"
        }
      }
    ],
    "_meta": {
      "page": 1,
      "per_page": 10,
      "total_pages": 5,
      "total_items": 42
    }
  }
}
The token_usage field is only returned when explicitly requested via fields[agent-runs]=token_usage and the user has the required permission.