Skip to main content
POST
/
v1
/
agents
/
{name}
/
run
Run Agent
curl --request POST \
  --url https://api.example.com/v1/agents/{name}/run

​
Request

POST /v1/agents/{name}/run
Content-Type: application/json

{
  "input": {
    "query": "Your input here"
  }
}

​
Headers

HeaderDescription
Content-Typeapplication/json
X-Session-IDOptional. Route to same worker
Accepttext/event-stream for SSE streaming

​
cURL Example

curl -X POST http://localhost:7777/v1/agents/my-agent/run \
  -H "Content-Type: application/json" \
  -d '{"input": {"query": "hello"}}'
With session: 
curl -X POST http://localhost:7777/v1/agents/my-agent/run \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: user-123" \
  -d '{"input": {"query": "hello"}}'

​
Response

Success (200): 
{
  "request_id": "abc-123-def",
  "result": {
    "response": "Hello!",
    "status": "success"
  },
  "duration_ms": 45,
  "worker_id": "my-agent-worker-1"
}
Error (500): 
{
  "request_id": "abc-123-def",
  "error": "Handler raised exception",
  "duration_ms": 12
}

​
CLI Equivalent

orpheus run my-agent '{"query": "hello"}'

# With session
orpheus run my-agent '{"query": "hello"}' --session user-123

Next: ExecLog API

Query execution history →