Skip to main content
GET
/
v1
/
v2
/
conversations
/
{conversation_id}
/
messages
Poll a v2 conversation for its status and the message tail since a seq
curl --request GET \
  --url https://api-sandbox.featherhq.com/v1/v2/conversations/{conversation_id}/messages \
  --header 'x-api-key: <api-key>'
{
  "session_status": "<string>",
  "messages": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "content": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "tool_calls": [
        {
          "id": "<string>",
          "function": {
            "name": "<string>",
            "arguments": "<string>"
          },
          "type": "function"
        }
      ],
      "tool_results": {
        "tool_call_id": "<string>",
        "output": "<string>",
        "error": "<string>"
      },
      "model_used": "<string>",
      "token_count": {
        "input_tokens": 123,
        "output_tokens": 123,
        "total_tokens": 123
      },
      "latency_ms": 123,
      "is_compacted": false,
      "metadata": {},
      "delivery_status": "<string>",
      "authored_by": "<string>",
      "evidence": {
        "package_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "items": [
          {
            "citation_marker": "<string>",
            "label": "<string>",
            "short_label": "<string>",
            "document_title": "<string>",
            "version_number": 123,
            "section": {
              "path_titles": [
                "<string>"
              ],
              "path_numbers": [
                "<string>"
              ],
              "display_label": "<string>",
              "confidence": "unknown"
            },
            "deep_link": "<string>"
          }
        ],
        "view": "display",
        "schema_version": 1,
        "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    }
  ],
  "next_seq": 123
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
conversation_id
string<uuid>
required

Query Parameters

​
since_seq
integer
default:-1

Watermark: return only messages with seq > since_seq (exclusive). Message seqs are 0-based, so seed with the default -1 to fetch from the very start (includes seq 0), then pass the response's next_seq back.

Required range: x >= -1
​
include_evidence
boolean
default:false

[ENG-670 T3] Attach each message's evidence package (the KB sources shown to the model). Off by default — the poll DEFERS the large citations column; opt in to load and project it.

​
evidence_view
enum<string>
default:full

Serialization view when include_evidence=true. Poll default is 'full' (staff/audit), matching the transcript page; 'display' is the end-user source-card subset.

Available options:
display,
full

Response

Successful Response

The poll primitive's response (HITL-04 §6.6).

Backs GET /v2/conversations/{id}/messages?since_seq=N — one round-trip that returns the conversation's current session_status and every message with seq > since_seq (the new tail). The caller advances its watermark to next_seq and re-polls. The SAME primitive serves both approval-resume polling (awaiting_approval → active) and handoff operator-relay polling (waiting_for_human → closed).

next_seq is the high-water mark to pass back as since_seq on the next poll: the max seq of the returned messages, or the request's own since_seq when the tail is empty (so an idle poll doesn't rewind the watermark). The caller watermarks on this exactly as it would on :attr:TurnResponse.message_seqs after a synchronous turn.

​
session_status
string
required
​
messages
TurnResponse · object[]
required
​
next_seq
integer
required