Get a run's current state

Returns the run’s current state — status, iterations used so far, token usage, submitted inference job IDs, the model’s final answer (if completed), pending tool calls (if requires_action), or the error (if failed).

Polling

Runs are asynchronous. After POST /agents/conversations/{id}/runs you poll this endpoint until you see a terminal status (completed, requires_action, or failed). A reasonable polling cadence:

• Start with 2-second polls — most simple runs complete in a single iteration (5–15 seconds wall-clock).
• Back off to 4–8 seconds for longer-running runs (multi-iteration tool loops).
• Hard-cap at maybe 5 minutes — if a run hasn’t terminated by then either something is wrong (check submitted_inference_job_ids in the data plane’s jobs table) or the workflow timed out and will land failed shortly.

Which fields are populated when

effective_config is always populated — it’s the fully-merged config used for this run (conversation defaults + this run’s config_override). Helpful for confirming the model saw what you expected.

Run vs. inference iteration

Each run runs N iterations, where N ≤ effective_config.max_iterations. Each iteration is one inference job submitted to the data plane (one Bedrock or Cortex API call). submitted_inference_job_ids carries the platform’s jobs.id for each iteration — use those to drill into the raw model request/response in the data plane’s logs / job table.

iterations_used and submitted_inference_job_ids.length match for any terminal state.

Error structure

On status: "failed" the error field carries:

• type — opaque incident code (e.g. AgentLoopMaxIterationsExceeded, AgentLoopInvalidEffectiveConfig, UnknownTool). Stable across versions, used for log correlation.
• message — human-readable detail.
• title and docs_url — caller-facing presentation looked up from the platform’s error catalog. Absent if the API doesn’t recognize the type (usually because the workflow workers have been upgraded ahead of the API); in that case rely on type and message.

Note: this endpoint always returns 200 for a known run — even one with status: "failed". The HTTP-level error path (RFC 7807) only applies when the call itself fails (token invalid, run not found, etc.).

Scope: per-user, not per-company

Runs are scoped to the (company_id, user_id) pair that created them. Returns 404 for “run does not exist”, “run belongs to a different company”, and “run was created by a different user in the same company” alike — the API does not distinguish them to avoid leaking existence.

Permission

agent_conversations resource with read verb.

Example: completed run

{
  "id": "82eb9cb7-619e-46bb-ac1c-8a32b0112c1c",
  "conversation_id": "bc2505b7-068d-44ed-8055-a6f6ffe54ab1",
  "company_id": 1,
  "user_id": 407,
  "client_op_id": "696b022c-e86d-4b3e-b6d7-ceb7eb1a495e",
  "status": "completed",
  "tool_choice": null,
  "effective_config": { "...": "..." },
  "iterations_used": 1,
  "usage": { "prompt_tokens": 169, "completion_tokens": 8, "total_tokens": 177 },
  "submitted_inference_job_ids": ["e94c6eab-019f-4e96-bb47-049fa60e7988"],
  "pending_tool_calls": [],
  "final_text": "4",
  "final_structured_output": null,
  "error": null,
  "started_at": "2026-05-18T13:21:30.355180Z",
  "completed_at": "2026-05-18T13:21:51.983952Z"
}

Example: completed structured-output run

{
  "id": "8dda70ab-9f81-4613-a3c9-68b3b584e82d",
  "status": "completed",
  "iterations_used": 1,
  "final_text": null,
  "final_structured_output": {
    "event": {
      "type": "login",
      "user_id": "u-123",
      "session_duration_seconds": 1800
    }
  },
  ...
}

Example: requires_action run

{
  "id": "19082f49-0280-4e32-a8b4-7df8dea9dbed",
  "status": "requires_action",
  "iterations_used": 1,
  "pending_tool_calls": [{
    "tool_use_id": "tooluse_DWXPKZ50JDGib5GmShyUgJ",
    "name": "confirm_booking",
    "arguments": { "proposed_slot": "tomorrow afternoon" }
  }],
  "final_text": null,
  "final_structured_output": null,
  ...
}

Resume by posting a new run with payload.kind: "tool_outputs" carrying the same tool_use_id.

Example: failed run

{
  "id": "...",
  "status": "failed",
  "iterations_used": null,
  "usage": null,
  "final_text": null,
  "final_structured_output": null,
  "error": {
    "type": "AgentLoopMaxIterationsExceeded",
    "message": "max iterations exceeded after 5 iterations",
    "title": "Max Iterations Exceeded",
    "docs_url": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/max-iterations-exceeded"
  },
  ...
}