Poll a v2 conversation for its status and the message tail since a seq

The HITL-04 §6.6 poll primitive — net-new, message+seq shaped.

Distinct from GET /{id}/turns (cursor-paginated over turns): this is the one round-trip a caller loops on while a turn is parked, returning the conversation’s current session_status AND every message with seq > since_seq. The SAME primitive serves approval-resume polling (awaiting_approval → active) and handoff operator-relay polling (waiting_for_human → closed); the uniform waker generates+persists the resumed/operator message and the caller’s next poll picks it up.

The caller watermarks on the returned next_seq (the max seq of the tail, or the request since_seq when the tail is empty so an idle poll never rewinds). Borrows the read-router message-row + worst-of-N delivery- status plumbing; ordered by seq ascending. Org-scoped: cross-org / missing id → 404 before any read.

GET

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/conversations/{conversation_id}/messages \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "session_status": "<string>",
  "messages": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "seq": 123,
      "role": "user",
      "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",
        "evidence_status": "complete",
        "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>",
            "kb_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "kb_name": "<string>",
            "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "source_provider": "<string>",
            "external_id": "<string>",
            "external_uri": "<string>"
          }
        ],
        "view": "display",
        "schema_version": 1,
        "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "kb_used": false
      },
      "message": "<string>",
      "sources": [
        {
          "title": "<string>",
          "url": "<string>"
        }
      ]
    }
  ],
  "next_seq": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

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 /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

Show child attributes

next_seq

integer

required

Poll a v2 conversation for its status and the message tail since a seq

curl --request GET \
  --url https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages \
  --header 'x-api-key: <api-key>'

import requests

url = "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.featherhq.com/v1/conversations/{conversation_id}/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "session_status": "<string>",
  "messages": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "seq": 123,
      "role": "user",
      "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",
        "evidence_status": "complete",
        "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>",
            "kb_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "kb_name": "<string>",
            "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "source_provider": "<string>",
            "external_id": "<string>",
            "external_uri": "<string>"
          }
        ],
        "view": "display",
        "schema_version": 1,
        "message_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "kb_used": false
      },
      "message": "<string>",
      "sources": [
        {
          "title": "<string>",
          "url": "<string>"
        }
      ]
    }
  ],
  "next_seq": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "retryable": true,
  "retry_after": 123
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}