Skip to main content
POST
/
api
/
agents
/
{agent_uid}
/
run
Manual run
curl --request POST \
  --url https://api.example.com/api/agents/{agent_uid}/run \
  --header 'Content-Type: application/json' \
  --data '
{
  "trigger_payload": {}
}
'
Triggers a manual agent run. The run executes asynchronously via the agent’s Temporal workflow. Poll the activities endpoint to track progress.

​
Path parameters

​
agent_uid
string
required
UUID of the agent to run.

​
Request body

​
trigger_payload
object
Payload simulating the trigger event. Structure depends on the agent’s trigger type.For an invoice trigger:
{
  "trigger_payload": {
    "invoice_uid": "inv-uuid-here"
  }
}
For an email trigger:
{
  "trigger_payload": {
    "message_uid": "msg-uuid-here"
  }
}

​
Response

Returns 202 (accepted) with the run details: 
{
  "status": "success",
  "status_code": 202,
  "message": "Agent run started",
  "data": {
    "uid": "run-uuid-here",
    "sandbox": false,
    "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": "pending",
    "trigger_type": "invoice",
    "trigger_payload": {
      "invoice_uid": "inv-uuid-here"
    },
    "result": null,
    "token_usage": null,
    "error": null,
    "started_on": null,
    "completed_on": null,
    "created_on": "2026-03-20T10:00:00Z"
  }
}

​
Errors

StatusReason
404Agent not found
409Agent is already running (concurrent run conflict)
422Invalid trigger payload