Run Agent (Async)

POST /api/v1/agents/:agentId/run-async — queue an agent run and poll for the result.

Queues an agent run and returns immediately with a job ID, instead of blocking for up to 30 seconds like /run. Use this for anything that might run long, or when you'd rather not hold a connection open.

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

Path parameters

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

Request body

Identical to /run: message (required), session_id, user_id, tag, tool_context.

Response

202 Accepted

{
  "jobId": "9c4e2a1b-...",
  "agentId": "3f9c...",
  "status": "queued",
  "createdAt": 1732550123
}

Lifecycle

POST /agents/:agentId/run-async → receive a jobId, status queued.
GET /jobs/:jobId (poll) → status moves through queued → running → a terminal state.
A terminal state is reached: completed, failed, timeout, or cancelled.
Optionally, POST /jobs/:jobId/cancel at any point before it reaches a terminal state.

Terminal state	Meaning
`completed`	Finished successfully — `result` is populated on the job.
`failed`	The run errored — `error` is populated on the job.
`timeout`	The run didn't finish in time.
`cancelled`	Cancelled via `/jobs/:jobId/cancel` before it finished.

See Agent jobs for the full job response shape and cancellation.

Recommended polling interval

Poll every 2 seconds for the first 30 seconds — most jobs finish inside that window.
After 30 seconds, back off to every 5 seconds until you see a terminal state.
Don't poll more than once per second — it burns your rate limit budget for no benefit.

Python example

import asyncio
import httpx

async def run_and_poll(agent_id: str, message: str, api_key: str) -> dict:
    base = "https://api.elizon.com/api/v1"
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}

    async with httpx.AsyncClient() as client:
        # Submit async job
        r = await client.post(f"{base}/agents/{agent_id}/run-async",
                              headers=headers, json={"message": message})
        job_id = r.json()["jobId"]

        # Poll until terminal
        interval, elapsed = 2, 0
        while True:
            await asyncio.sleep(interval)
            elapsed += interval
            if elapsed > 30:
                interval = 5
            r = await client.get(f"{base}/jobs/{job_id}", headers=headers)
            job = r.json()
            if job["status"] in ("completed", "failed", "timeout", "cancelled"):
                return job

Errors

Status	`error`	When
`400`	validation error (`{ "errors": [...] }`)	`message` missing/empty, or another field fails validation
`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
`502`	`enqueue_failed`	The job couldn't be queued (transient infrastructure error) — safe to retry

Example

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

Run Agent (Async)

On this page