Agents API runs

POST /v1/agents/runs is asynchronous. The trigger returns immediately with a runId; the result lands on GET /v1/runs/{runId} when the run finishes.

GET /v1/runs/{runId}

curl https://api.kindo.ai/v1/runs/7a7ced7d-95a8-416f-95bb-5c0ff3599f53 \
  -H "Authorization: Bearer $KINDO_API_KEY"

Response:

{
  "runId": "7a7ced7d-95a8-416f-95bb-5c0ff3599f53",
  "agentId": "18d20df4-d9b3-4cb0-a009-9f11ec9c5d3d",
  "createdAtUtc": "2026-03-12T15:00:00.000Z",
  "endedAtUtc": "2026-03-12T15:00:08.000Z",
  "result": "{\"role\":\"assistant\",\"parts\":[{\"type\":\"text\",\"text\":\"Security scan complete. No critical findings.\"}]}",
  "status": "success"
}

Field	Type	Notes
runId	string	Matches the runId returned by the trigger.
agentId	string | null	The agent that produced this run. null when the underlying agent has been soft-deleted; the run record remains visible but no longer resolves to a live agent.
createdAtUtc	string	ISO-8601 timestamp when the trigger was accepted.
endedAtUtc	string | null	ISO-8601 timestamp when the run reached a terminal status, or null while status is in_progress.
result	string | null	A JSON-encoded string of the final assistant message payload — parse with JSON.parse to recover { role, parts, ... }. null while in_progress, always null on failure or cancelled, and also null on success when the run produced no assistant payload.
status	string	One of in_progress, success, failure, cancelled.

Status lifecycle

in_progress  ──▶  success
             ──▶  failure
             ──▶  cancelled

• in_progress — the only non-terminal status. Continue polling.
• success — the run completed; result holds the JSON-encoded final assistant payload, or is null if the run produced no assistant payload.
• failure — the run errored. result is null; inspect the Kindo Terminal or the underlying conversation for diagnostics.
• cancelled — the run was cancelled (manually or by a timeout). result is null.

Polling cadence

Runs are typically long-running (seconds to minutes), so a short poll-then-back-off works well in practice:

• Wait 1–2 seconds before the first poll.
• Back off to 5–10 seconds for subsequent polls.
• Treat any non-in_progress status as terminal and stop.

Kindo does not currently push webhooks for run completion; polling is the only delivery mechanism for the result.

Runs and conversations

A run executed by an agent that uses the Responses API internally will produce its own conversation server-side. The runId itself is not a conversation_id — to inspect the underlying conversation history, fetch it via the Conversations API using the conversation ID surfaced in the Kindo Terminal or in the agent’s configured outputs. For most use cases, result on GET /v1/runs/{runId} is the only field you need.

See also

• Quickstart — end-to-end discover → trigger → poll flow.
• Request shape — the trigger and discovery bodies.
• Errors — 404 Not found, 422 Unprocessable Entity, etc.