Skip to main content
GET
/
api
/
agent
/
chat
/
{runId}
Poll an agent chat run
curl --request GET \
  --url https://app.puffle.ai/api/agent/chat/{runId} \
  --header 'Authorization: Bearer <token>'
{ "runId": "run_abc", "status": "queued" }

​
Overview

Returns the state of an agent chat run previously started via startAgentChat. While the run is executing, status is queued or running. Once it transitions to completed, failed, or cancelled, polling can stop — text, messages, and toolCalls are populated on success; error is populated on failure.

​
AI agent notes

Admin-only, ownership-checked. The endpoint verifies the run’s payload userId matches the caller’s effectiveUserId. A mismatch returns 404 (not 403) to avoid leaking that a run exists.Polling cadence. Poll every 1–2 s. Runs typically complete within 10–60 s depending on tool chain length; the Trigger.dev task has a generous timeout so don’t give up too early.Terminal signals — stop polling when:
  • status === "completed" — success. Read text, messages, toolCalls.
  • status === "failed" — terminal failure. Read error for the reason.
  • status === "cancelled" — the run was cancelled (manual or system).
Run ID format. Must start with run_. Anything else returns 400 immediately without hitting Trigger.dev.Related: Start an agent chat run, Stream an agent chat run.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
runId
string
required

Trigger.dev run id, starts with run_. Returned by startAgentChat.

Response

Current run status.

​
runId
string
required
​
status
enum<string>
required
Available options:
queued,
running,
completed,
failed,
cancelled
​
text
string

Final assistant message text. Present only when status === 'completed'.

​
messages
object[]

Full message log (user + assistant + tool turns). Present only when completed.

​
toolCalls
object[]

Tools the agent invoked during the run. Present only when completed.

​
error
string

Error message. Present only when status === 'failed'.