Run Agent (Synchronous)

POST /api/v1/agents/:agentId/run — execute an agent and wait for the full response.

Runs an agent and blocks until it finishes, up to 30 seconds. For anything that might take longer, use /run-async instead.

POST /api/v1/agents/{agentId}/run

Path parameters

Parameter	Type	Description
`agentId`	string (UUID)	The agent to run.

Request body

Field	Type	Required	Description
`message`	string (min 1 char)	Yes	The input message to send the agent.
`session_id`	string	No	Continue an existing conversation. Omit to start a new session — a new `session_id` is generated and returned.
`user_id`	string	No	Your own identifier for the end user. Omit to have one generated.
`tag`	string, `^[a-zA-Z0-9\-_]{1,30}$`	No	Free-form label, accepted and validated but not currently used in execution. Reserved for future observability.
`tool_context`	string (JSON)	No	A JSON-encoded string passed through to the agent's tools. Must parse as valid JSON — an invalid value returns `400 invalid_tool_context`, not the generic validation error shape.
`include_messages`	boolean	No	Default `false`. When `true`, the response's `messages` field is populated with the full message history for the run instead of `null`.

Response

200 OK

{
  "runId": "b7e1...",
  "agentId": "3f9c...",
  "agentName": "Support Bot",
  "content": "Hello! How can I help you today?",
  "sessionId": "a1c4...",
  "userId": "d92e...",
  "createdAt": 1732550123,
  "success": true,
  "metrics": {
    "inputTokens": 12,
    "outputTokens": 9,
    "latencyMs": 842,
    "model": null,
    "failoverUsed": false
  },
  "messages": null
}

content — the agent's full reply text.
metrics.model is currently always null — the underlying runtime doesn't report a model identifier yet.
metrics.failoverUsed — true if the primary model failed and the secondary model (if configured) handled the run instead.
messages — null unless you passed include_messages: true.

Timeout behaviour

If the agent hasn't finished within 30 seconds, the request is aborted and the in-flight run is cancelled upstream:

504 Gateway Timeout
{
  "error": "execution_timeout",
  "message": "Agent execution exceeded the 30 s limit. Use /run-async for long-running tasks."
}

If you're hitting this regularly, switch that call to POST /run-async and poll for the result instead.

Cancelling a run

DELETE /api/v1/agents/{agentId}/runs/{runId}

Cancels an in-progress run by the runId returned in the response above (or, for streaming, in the RunStarted event). Returns 200 either way — { "cancelled": true, "runId": "..." } if it was still running, or { "cancelled": false, "runId": "...", "message": "Run already completed." } if it had already finished.

Errors

Status	`error`	When
`400`	validation error (`{ "errors": [...] }`)	`message` missing/empty, or another field fails validation
`400`	`invalid_tool_context`	`tool_context` isn't valid JSON
`403`	`forbidden`	The agent belongs to a different project than your project-scoped key
`404`	`agent_not_found`	No agent with that ID exists in your organization
`404`	`run_not_found` (cancel only)	No run with that ID
`502`	`bad_gateway` / `upstream_error`	The agent runtime is unreachable or returned an error mid-run
`504`	`execution_timeout`	The run didn't finish within 30 seconds

Example

curl -X POST https://api.elizon.com/api/v1/agents/{agentId}/run \
  -H "X-API-Key: elz_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarise the Q3 report"}'