Ejecutar un agente por API

Tus agentes se pueden llamar por HTTP con una API key tipo bearer. Esta página es un recorrido corto y concreto del ciclo de ejecución/polling para un solo agente — para cada ruta, la forma de sus requests/respuestas, scopes y códigos de error, mirá la referencia de la API REST.

Autenticación

Creá una clave en Settings → API keys del dashboard, con al menos el scope run. La clave se muestra una sola vez, al crearla — guardala en un lugar seguro. Pasala como bearer token:

Authorization: Bearer $API_KEY

Iniciar una ejecución

curl -X POST https://tu-dominio.com/api/v1/agents/$AGENT_ID/run \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"topic": "Últimos papers de IA"}}'

$AGENT_ID puede ser el UUID del agente o su slug — ambos resuelven de la misma forma, scopeados a tu cuenta.

Tu payload tiene que ir anidado bajo una clave input, exactamente como se muestra arriba. Un body sin el wrapper input (por ejemplo, {"topic": "..."} suelto) se acepta pero ejecuta el agente en silencio con un input vacío {} — input es el único campo que lee esta ruta.

Respuesta — 202 Accepted

La ejecución es asincrónica. La llamada retorna apenas se encola:

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

Obtener el resultado

Hacé GET a pollUrl hasta que el status sea un valor terminal (completed o failed):

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

Mientras la ejecución está pending o running, la respuesta incluye un eventsUrl al que te podés suscribir para recibir server-sent events en vez de hacer polling. Una vez completed, la respuesta incluye output, trace y metrics; una vez failed, incluye error y trace en su lugar.

Límites de tasa

Las ejecuciones consumen del presupuesto de escritura + ejecución: 60 peticiones por hora, por API key, compartido con cualquier otra llamada con scope de escritura o ejecución que haga la clave (no por agente). Mirá Límites de tasa en la referencia para el detalle completo, incluido el presupuesto de lectura, separado y más amplio.

Cada respuesta trae el estado de la ventana actual:

Header	Significado
X-RateLimit-Limit	Peticiones permitidas por ventana
X-RateLimit-Remaining	Peticiones que quedan en la ventana actual
X-RateLimit-Reset	Segundos hasta que se reinicie la ventana

Superar el límite devuelve 429 con error: "rate_limited".

Respuestas de error

Mirá la tabla de códigos de error en la referencia para la lista completa. Los que más probablemente te encuentres ejecutando un agente:

error	Estado	Significado
unauthorized	401	API key faltante o inválida
forbidden_scope	403	La clave no tiene el scope run
not_found	404	El agente no existe, o es de otra persona
insufficient_credits	402	Sin créditos — recargá en Dashboard → Billing
rate_limited	429	Límite de tasa superado

nota

El límite de tasa se verifica después de la autenticación y el scope, así que una clave inválida o sin el scope necesario devuelve 401/403 en vez de revelar algo sobre la clave mediante un 429.