Execution API

Execution is async-only via the external API. Trigger a run and then poll events for status.

GET /v1/agents, GET /v1/agents/{agentId}, and the event listing endpoints are read-only. They do not create execution events. New event records are created only when an agent is actually executed, such as via POST /v1/agents/{agentId}/execute or a scheduled run.

If you are just getting started, begin with API Overview to verify your API key with a simple GET /v1/agents request first.

Execute Agent (Manual Run)

POST /v1/agents/{agentId}/execute

Triggers a background run of the agent using the same path as a scheduled run. Returns 202 Accepted immediately; the actual run happens asynchronously.

Response:


{
  "data": {
    "message": "Execution started. Poll events for status.",
    "requestId": "abc123",
    "agentId": "agent-123"
  }
}

After calling this endpoint, poll GET /v1/agents/:agentId/events or GET /v1/events to track progress and retrieve results.

Get Agent Events

GET /v1/agents/{agentId}/events

Retrieve the execution history for a specific agent, newest first.

Query params (optional):

Param	Type	Description
`status`	string	Filter: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`
`startedAfter`	ISO 8601	Only events started after this timestamp
`startedBefore`	ISO 8601	Only events started before this timestamp
`limit`	integer	Max results (default 50, max 200)
`nextToken`	string	Pagination cursor

Response:


{
  "data": [
    {
      "id": "event-456",
      "agentId": "agent-123",
      "userId": "user-789",
      "status": "COMPLETED",
      "startedAt": "2025-01-01T09:00:00.000Z",
      "completedAt": "2025-01-01T09:01:30.000Z",
      "error": null,
      "finalModel": "claude-3-7-sonnet",
      "browserStepCount": 5,
      "browserSessionSeconds": 90,
      "createdAt": "2025-01-01T09:00:00.000Z",
      "updatedAt": "2025-01-01T09:01:30.000Z"
    }
  ],
  "nextToken": null
}

Get All Events

GET /v1/events

Retrieve execution events across all agents. Supports the same query params as the agent-scoped endpoint plus:

Param	Type	Description
`agentId`	string	Optionally scope to one agent

Polling Pattern


# 1. Trigger run
RESPONSE=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  "$EXTERNAL_API_ENDPOINT/v1/agents/$AGENT_ID/execute")
 
REQUEST_ID=$(echo $RESPONSE | jq -r '.data.requestId')
 
# 2. Poll until done
while true; do
  STATUS=$(curl -s \
    -H "Authorization: Bearer $API_KEY" \
    "$EXTERNAL_API_ENDPOINT/v1/agents/$AGENT_ID/events?limit=1" \
    | jq -r '.data[0].status')
 
  echo "Status: $STATUS"
  if [[ "$STATUS" == "COMPLETED" || "$STATUS" == "FAILED" ]]; then break; fi
  sleep 5
done