Poll run status, read conversation, subscribe to events, and send input or session messages. Paths are relative to your API base URL; send X-API-Key and Content-Type: application/json unless noted.
Monotonic per run; not a global sort key (use ordinal).
ordinal
number
1-based order after the service merges and sorts the full session timeline.
type
string
Engine step type (for example UserTaskReq, Reasoning, …) or synthetic RunCompleted / SessionCompleted.
content
JSON or null
Step payload; shape depends on type. For synthetic rows, includes completion status / output / error style fields.
tokensUsed
number or null
Tokens for the step, when set.
error
string or null
Error on the step when set.
startedAt / finishedAt
string (ISO-8601) or null
Step timing.
stepContent=slim: For objectcontent values, the API omits these keys to reduce payload size: session_id, run_id, tenant_id, agent_id, agent_version_id, event_id. Other shapes are unchanged.Output-only (redacted) response: When the API trigger has Expose step timeline to API clients off, Phrony may return a redacted JSON body for this route. See Embedded agents — API redaction. In that mode, roughly:
Change
What you get
items
Only completion-style rows: SessionCompleted, and RunCompleted for the root run.
runs[] / items / session
input, startContext (on session), and per-run output / error on runs may be nulled to avoid exposing full detail.
Subscribe to Server-Sent Events for live session and run activity. Use a server or fetch with a stream reader so you can set X-API-Key.
Auth: Run-access key.
Response:text/event-stream — each SSE event’s data string is a single JSON object (line). Parse it with JSON.parse after decoding UTF-8.
Aspect
Description
Format
Server-Sent Events; each data line is one JSON value.
Client
Browsers’ EventSource cannot set X-API-Key; use a server or fetch + stream reader.
Event object schema (root fields on each data JSON):
Field
Type
Description
ts
string
ISO-8601 timestamp (when the hub emitted the event).
kind
step · session · run · user_task · aitl
Groups the event.
subject
string
Fine-grained name (for example engine.session.started, engine.run.completed, engine.subagent.spawned, engine.step.* — exact strings are engine/projection details).
data
object
Payload; fields depend on kind and subject (run ids, session ids, step bodies, and so on).
kind roles (at a glance):
kind
Role
session
Session started / completed / paused, etc.
run
Run started / completed, subagent spawn, HITL pause, etc.
Output-only (redacted) stream: When the same API trigger setting hides the full timeline, Phrony filters the SSE event stream. Events with kindstep, user_task, or aitl are dropped, and run events with subjectengine.subagent.spawned are also dropped, so the client only receives a safe subset. Unfiltered clients still receive the full set of kind values.
POST to /v1/runs/{runId}/input or /v1/runs/{runId}/messages accepts JSON with a runId that matches the path, plus either userTaskId (HITL), or text / message, and/or files, depending on how the run is paused. See Send input or messages below for field tables.
POST/v1/runs/{runId}/input and /v1/runs/{runId}/messages
Resume a run that is waiting for a human, conversation, or file attachments. Same body shape; pick either path.
These routes cover the usual ways to resume a run that is waiting for a human, including many approvals and follow-ups. Not every type of user task can be completed through the API—for example, some escalations to a person from multi-agent runs, and some anomaly or alert steps, must be completed in the Phrony dashboard. See User task — Phrony API.
Auth: Run-access key.
Status:202 Accepted on success.
Request body (JSON):runId must match {runId} in the path.
Field
Type
Required
Description
runId
string (UUID)
Yes
Same as {runId} in the path.
userTaskId
string (UUID)
No
For human-in-the-loop / approval flows: the pending user task to complete. When set, other completion fields may apply.
approved
boolean
No
For approval / HITL: whether to run pending HTTP tool calls (default true when applicable).
selectedOptionId
string
No
For multi-option tasks: chosen option from the task’s options list.
textValue
string
No
For text-kind tasks.
numberValue
number
No
For number-kind tasks.
metadata
object
No
Extra fields stored on the user task.
text
string
No
Preferred for conversational WaitingForResponse (alias: message).
message
string
No
Same role as text.
files
array
No
Workspace file attachments for a user turn. See File item below.
completedByEmail
string (email)
No
Set by the dashboard; do not rely on a client copy for untrusted clients.
Validation: You must provide userTaskId, or non-empty text/message, or at least one files entry, according to the pause type.Response (success, JSON):202 Accepted body, typically:
Field
Type
Description
status
string
Acceptance status from the service (work may still run asynchronously).
error
string
Optional error message if the service rejected the follow-up.
Use runId from the Start a runPOST response with GET /v1/runs/{runId} until the run reaches a finished state in your use case. (Start + poll example also appears on Agents API.)
Conversation returns JSON. Stream is Server-Sent Events: use curl -N for a quick look. In the browser, EventSource cannot set custom headers, so you typically call stream from a server with X-API-Key, or use a fetch-basedtext/event-stream reader in Node or Bun.
When the run is waiting for user text, POST to …/input or …/messages. The body must include runId, non-empty text, and/or files, or a userTaskId for human-in-the-loop flows.
