Run an agent via API

Your agents are callable over HTTP with a bearer API key. This page is a short, worked walkthrough of the run/poll cycle for a single agent — for every route, its request/response shape, scopes and error codes, see the REST API reference.

Authentication

Create a key at Settings → API keys in the dashboard, with at least the run scope. The key is shown once, at creation — store it somewhere safe. Pass it as a bearer token:

Authorization: Bearer $API_KEY

Start a run

curl -X POST https://your-domain.com/api/v1/agents/$AGENT_ID/run \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"topic": "Latest AI papers"}}'

$AGENT_ID can be the agent's UUID or its slug — both resolve the same way, scoped to your account.

Your payload must be nested under an input key, exactly as shown above. A top-level body without the input wrapper (e.g. {"topic": "..."} on its own) is accepted but silently runs the agent with an empty {} input — the input field is the only one this route reads.

Response — 202 Accepted

Execution is asynchronous. The call returns as soon as the run is queued:

{
  "runId": "0fb7…",
  "status": "PENDING",
  "pollUrl": "/api/v1/runs/0fb7…"
}

Getting the result

GET the pollUrl until status is a terminal value (completed or failed):

curl https://your-domain.com/api/v1/runs/0fb7... \
  -H "Authorization: Bearer $API_KEY"

While the run is pending or running, the response includes an eventsUrl you can subscribe to for server-sent events instead of polling. Once completed, the response includes output, trace, and metrics; once failed, it includes error and trace instead.

Rate limits

Runs draw from the write + run budget: 60 requests per hour, per API key, shared with every other write- or run-scoped call the key makes (not per-agent). See Rate limits in the reference for the full breakdown, including the separate, larger read budget.

Every response carries the current window state:

Header	Meaning
X-RateLimit-Limit	Requests allowed per window
X-RateLimit-Remaining	Requests left in the current window
X-RateLimit-Reset	Seconds until the window resets

Exceeding the limit returns 429 with error: "rate_limited".

Error responses

See the error codes table in the reference for the full list. The ones you're most likely to hit running an agent:

error	Status	Meaning
unauthorized	401	Missing or invalid API key
forbidden_scope	403	The key doesn't have the run scope
not_found	404	Agent doesn't exist, or belongs to someone else
insufficient_credits	402	Out of credits — top up at Dashboard → Billing
rate_limited	429	Rate limit exceeded

note

Rate limiting is checked after authentication and scope, so an invalid or underscoped key returns 401/403 rather than revealing anything about the key via a 429.