List conversation messages (delta read by version cursor)

Returns the messages in this conversation with sequence_no > since, plus the conversation’s current_version at the moment the response was generated. The messages list is ordered by sequence_no ascending and is gap-free — if the response contains messages with sequence_no 3, 4, 5, you have all three.

Polling pattern

since = 0
loop forever:
  r = GET /agents/conversations/{id}/messages?since={since}
  process r.messages       # may be empty
  since = r.current_version # use the head, not r.messages.last.sequence_no
  wait briefly

current_version is the conversation’s head at the moment the response was generated — using it as the next request’s since is the only way to ensure gap-free reads even when new messages land between the time the response was generated and the time your client processed it.

When messages get added

Messages are persisted in a single transaction by the workflow’s finalize step (when a run reaches a terminal state). You won’t see partial reads — a run that produces 4 messages either lands all 4 or none.

A run’s id appears in messages[].run_id, so you can correlate messages to the runs that produced them.

What’s in content_blocks

Three discriminated variants:

• text — plain text. The dominant variant.
• tool_use — the model requesting a tool call. Carries tool_use_id, the aliased name, and the model’s arguments.
• tool_result — the result of a tool call, nested as content_blocks inside the tool_result block. Carries the original tool_use_id plus an is_error flag.

The same tool_use_id appears on the assistant’s tool_use block and on the subsequent tool (or user, for resume payloads) turn’s tool_result block — that’s how a UI matches them up.

Permission

agent_conversations resource with read verb.

Example: paging from scratch

curl "$API/agents/conversations/{id}/messages?since=0" \
  -H "Authorization: Bearer $TOKEN"
# → { "current_version": 4, "messages": [ <4 entries> ] }

Then later:

curl "$API/agents/conversations/{id}/messages?since=4" \
  -H "Authorization: Bearer $TOKEN"
# → { "current_version": 4, "messages": [] }   # nothing new