--- title: "Poll a v2 conversation for its status and the message tail since a seq" method: GET path: "/v1/v2/conversations/{conversation_id}/messages" tags: ["runtime v2"] --- # Poll a v2 conversation for its status and the message tail since a seq `GET /v1/v2/conversations/{conversation_id}/messages` 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. ## Path parameters - `conversation_id` string, uuid, required ## Query parameters - `since_seq` integer — 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. - `include_evidence` boolean — [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` 'display' | '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. ## Response `200` Successful Response - ConversationMessagesPoll — 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` SrcConversationSchemasTurnResponse[], required - `id` string, uuid, required - `session_id` string, uuid, required - `role` 'user' | 'assistant' | 'system' | 'tool' | 'system_event', required - `content` string, required - `tool_calls` ToolCall[], nullable - `id` string, required - `type` string - `function` ToolCallFunction, required - `name` string, required - `arguments` string, required - `tool_results` ToolResult - `tool_call_id` string, required - `output` string, required - `error` string, nullable - `model_used` string, nullable - `token_count` TokenCount - `input_tokens` integer, required - `output_tokens` integer, required - `total_tokens` integer, nullable - `latency_ms` integer, nullable - `is_compacted` boolean - `metadata` object - `created_at` string, date-time, required - `delivery_status` string, nullable - `authored_by` string, nullable - `evidence` union - EvidencePackageDisplay — End-user serialization view — source cards only, NO audit internals. A distinct model (not :class:`EvidencePackage` with a narrower config) so the omitted fields are absent from the schema, and so ``view`` yields a clean tagged union. ``organization_id``, ``agent_id`` and ``status_reason`` are full-only and intentionally not present here. - `view` 'display' - `schema_version` integer - `package_id` string, uuid, required - `conversation_id` string, uuid, required - `message_id` string, uuid, nullable - `turn_id` string, uuid, required - `created_at` string, date-time, required - `evidence_status` 'complete' | 'partial' | 'failed' | 'not_applicable', required - `items` EvidenceItemDisplay[], required - `citation_marker` string, nullable - `label` string, nullable - `short_label` string, nullable - `document_title` string, nullable - `version_number` integer, nullable - `section` EvidenceSection — A document section path — never a fabricated ``§N``. - `path_titles` string[], nullable - `path_numbers` string[], nullable - `display_label` string, nullable - `confidence` 'parsed' | 'derived' | 'unknown' - `deep_link` string, nullable - EvidencePackageFull — Staff/audit serialization view — the full envelope plus a ``view`` tag. Adds only the ``full`` discriminator literal; every audit field (scores/basis/band, ``rag_query_id``, chunk ids, hashes, constraints, ``status_reason``) rides through unchanged from :class:`EvidencePackage`. - `schema_version` integer - `package_id` string, uuid, required - `organization_id` string, uuid, required - `conversation_id` string, uuid, required - `message_id` string, uuid, nullable - `turn_id` string, uuid, required - `agent_id` string, uuid, nullable - `created_at` string, date-time, required - `evidence_status` 'complete' | 'partial' | 'failed' | 'not_applicable', required - `status_reason` 'complete' | 'no_kb_used' | 'no_exposed_chunks' | 'answerability_suppressed' | 'partial_missing_source_rows' | 'item_cap_applied' | 'build_failed', nullable - `items` EvidenceItem[], required - `evidence_id` string, uuid, required - `rag_query_id` string, uuid, nullable - `attribution_level` 'exposed' - `prompt_order` integer, nullable - `provenance` EvidenceProvenance, required - `kb_id` string, uuid, required - `kb_name` string, nullable - `document_id` string, uuid, required - `document_title` string, required - `version_id` string, uuid, nullable - `version_number` integer, nullable - `source_type` string, required - `source_provider` string, nullable - `deep_link` string, nullable - `filename` string, nullable - `section` EvidenceSection — A document section path — never a fabricated ``§N``. - … - `chunk_id` string, required - `chunk_index` integer, nullable - `content_sha256` string, nullable - `last_processed_at` string, date-time, nullable - `position` EvidencePosition - `type` 'text' - `start_char` integer, nullable - `end_char` integer, nullable - `score` EvidenceScore — Relevance signal — NOT a probability (``calibrated=False`` always in v1). - `retrieval_score_raw` number, nullable - `retrieval_score_display` number, nullable - `score_basis` 'raw_hybrid_dotproduct' | 'minmax_normalized' | 'reranked_original_score' | 'grouped_unranked', required - `band` 'high' | 'medium' | 'low' | 'unknown' - `calibrated` boolean - `usage_constraints` EvidenceUsageConstraints — Carried, not enforced (v1). - `sensitivity` 'public' | 'internal' | 'confidential' | 'restricted', nullable - `sensitivity_level` integer, nullable - `visibility_mode` 'org_wide' | 'audience', nullable - `audience_tags` string[], nullable - `constraint_source` 'acl_columns' | 'metadata' | 'none' - `raw` object, nullable - `display` EvidenceDisplay - `label` string, required - `short_label` string, nullable - `citation_marker` string, nullable - `source_trust` string, nullable - `scan_status` string, nullable - `view` 'full' - `next_seq` integer, required ## Other responses - `400` — Bad request - `401` — Authentication required - `404` — Resource not found - `422` — Validation Error --- [API](https://skmtc.net/oneloop-hq/apis/feather-api.md) · [All operations](https://skmtc.net/oneloop-hq/apis/feather-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oneloop-hq/feather-api/versions/888bdd5c076e/schema)