PacketChatDocs

Agent run API#

Start a published agent from a script or another service and collect its result. A run can execute inside the request, or be queued so that it survives the caller closing the page and the web application restarting.

Before you start#

  • Publish the agent and confirm you can run it in Agents.
  • Obtain an access token for the user the run belongs to. These endpoints accept an Authorization: Bearer token only; a browser session cookie is not enough.
  • Note the agent id from its page in Agents.
  • Keep the worker service running if you intend to queue runs. See Deploy.

Start a run inside the request#

POST /api/agents/{agentId}/runs executes the run and answers when it reaches a terminal state.

curl -fsS -X POST "$BASE_URL/api/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarise the latest release notes"}'

Request fields:

Field Required Purpose
inputText or input Yes The text the agent is run against
async No true queues the run instead of executing it in the request
conversation No true creates a conversation and records the exchange in it
conversationId No Records the exchange in an existing conversation you own

The response is 201 and carries runId, conversationId, status, and outputText. A run that stops for an approval also returns approvalId. A run that fails still returns 201 with status of failed and an error message, so read status rather than relying on the HTTP code alone.

This path runs in the web process, so the reverse proxy request timeout caps it. Use a queued run for work that may take minutes.

Queue a run#

Send "async": true in the body, or the header Prefer: respond-async.

curl -sS -i -X POST "$BASE_URL/api/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarise the latest release notes","async":true}'

The response is 202 with runId, conversationId, and a status of queued. The worker executes the run, so it continues after the response is sent and survives a restart of the web application. Exactly one executor takes ownership of a run, so a redelivered or retried job never runs it twice or charges the provider twice.

If Redis cannot accept the job, the attempt is abandoned after five seconds and the web process executes the run itself. The response is the same 202. That run is not durable: restarting the web application before it finishes leaves it unfinished. Polling recovers a run whose executor lease has expired as timed_out with run_abandoned. Older runs without a lease retain the twenty-minute recovery threshold.

Poll a run#

GET /api/agents/{agentId}/runs/{runId} returns the run with its steps, events, and usage totals.

curl -fsS "$BASE_URL/api/agents/$AGENT_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/agents/{agentId}/runs returns your 25 most recent runs for that agent, each with the same status and usage summary.

Statuses:

Status Meaning
queued Accepted, waiting for an executor
running Claimed and executing
waiting_input Stopped at an approval checkpoint
completed Finished with output
failed Ended with an error; error_message explains it
cancelled Cancelled by the caller or because an approval was rejected
timed_out Exceeded its execution limit, or the process running it ended

Approve or cancel a run#

PATCH /api/approvals/{approvalId} accepts {"decision":"approved"} or {"decision":"rejected"} with an optional note. An administrator, agent owner or user with editor/owner access can decide it. A resolved approval returns 409 if decided again. Approval queues continuation of the same run; poll that run for the action result and generated answer. Rejection cancels it before the gated actions execute.

DELETE /api/agents/{agentId}/runs/{runId} requests cancellation. Repeating it is safe; the response reports the resulting status. Cancellation is visible across executors, but an external action that has already completed remains an external side effect. Preserve the run timeline before starting replacement work.

Limits#

  • One run is allowed fifteen minutes of execution.
  • Active executors renew a thirty-second lease every five seconds. A status request marks an expired lease timed_out with run_abandoned. Legacy runs without a lease use twenty minutes from their start instead.
  • Time spent waiting in the queue does not count towards that limit. A run that is still queued is never failed for waiting, so a backlogged or briefly stopped worker delays runs rather than losing them.
  • Starting a run is limited to RATE_LIMIT_CHAT_PER_MINUTE requests per user over a sliding one-minute window. Agent runs get their own allowance of that size; they do not spend the chat allowance. An over-limit start returns 429 with Retry-After and the X-RateLimit-* headers.
  • Reading a run and listing runs are not rate limited, so polling does not return 429.
  • A run that reaches an approval checkpoint waits for a decision; approval resumes it through the same queue and fallback rules. See Agents and approvals.

Verify#

  1. Start a queued run and confirm the response is 202 with a run id.
  2. Poll the run and confirm it moves out of queued and reaches completed.
  3. Confirm the recorded usage names the provider and model you expected.
  4. Restart the web application during a queued run and confirm the run still completes.

If it does not work#

Symptom Check
404 on a valid agent id The agent must have a published version and be shared with the caller.
400 naming providerAccountId or model Re-select the provider account and model on the agent, then publish again.
Run stays queued Confirm the worker service is running and consuming its queues.
Queued run reports timed_out without output The process that held it ended. Check whether the web application restarted while running the fallback path, then start the run again.
401 on every request Use a current access token in the Authorization header; these endpoints do not read the session cookie.