# GET /v1/sessions/{session_id}/messages - List messages (PRIMARY data) Source: GET /v1/sessions/{session\_id}/messages Select code samplecURL (shell:curl) ```js const url = 'https://app.everruns.com/api/v1/sessions/example/messages'; const options = {method: 'GET'}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```sh curl --request GET \ --url https://app.everruns.com/api/v1/sessions/example/messages ``` * Production APIapp.everruns.com/api/v1/sessions/{session\_id}/messages ## Parameters ### Path Parameters **session\_id** required string Session ID (prefixed, e.g., sess\_…) ## Responses ### 200 List of messages Media typeapplication/json Response wrapper for list endpoints. All list endpoints return responses wrapped in a `data` field. object **data** required Array of items returned by the list operation. Array\ Message - primary conversation data (API response) object **content** required Array of content parts. Reasoning artifacts appear here as `reasoning` parts, in the order the provider emitted them, with opaque replay state (signatures, encrypted payloads) stripped. Array One of: * object Text content object **annotations** Claim-level citations attached to spans of `text`. The narrow render contract shared by all citation capabilities. Empty for non-cited text, so the wire shape of existing messages is unchanged. Array\ A claim-level citation attached to a span of generated text. The single shared type across every citation capability: a text span linked to a source. Producers agree only on this render contract — each capability keeps its own richer representation (e.g. `KnowledgeIndexCitation`) and maps into this envelope at emit time. object **end** required Exclusive end char offset. integer **external\_id** Opaque producer id (e.g. `kchk_…`, `kbe_…`, a URL hash). Not interpreted by the render contract. string | null **origin** required Capability id that produced this annotation (e.g. `citation_retrieval`). Lets the UI and evals attribute and filter each citation by feed. string **source** required The cited source. object **location** Provenance within the document (line / char / page / block ranges), reusing the retrieval `location` JSONB shape. **snippet** Trimmed passage that backs the claim. Display-only; never relied on for prompt reconstruction. string | null **title** Human-readable source title, when known. string | null **uri** required Stable, linkable locator (e.g. `github://owner/repo@main/docs/x.md` or an `https://` URL). string **start** required 0-indexed start char offset into the enclosing `TextContentPart.text`. integer **verified** One of: * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * null null **text** required string **type** required string Allowed values: text * object Verification verdict, filled by the `citation_verification` capability. Absent means unverified (not “unsupported”). object **score** Entailment confidence in `[0, 1]`, when the verifier produced one. number | null format: float **status** required Whether the cited source supports the claim. string Allowed values: entailed unsupported uncertain * object null * object Image content (base64 or URL) object **base64** string | null **media\_type** string | null **url** string | null **type** required string Allowed values: image * object Image file content (reference to uploaded image by ID) object **filename** Original filename (for display) string | null **image\_id** required ID of the uploaded image (format: img\_{32-hex}) string **type** required string Allowed values: image\_file * object File content (reference to uploaded file, e.g. PDF, by ID) object **file\_id** required ID of the uploaded file (format: file\_{32-hex}) string **filename** Original filename (for display and provider file parts) string | null **type** required string Allowed values: file * object Tool call content (assistant requesting tool execution) object **arguments** required **id** required string **name** required string **native** One of: * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * null object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null **type** required string Allowed values: tool\_call * object One of: * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * object object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object object **arguments** required Complete JSON arguments, preserved exactly as received. string **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **name** required Registered function or custom tool name. string **type** required string Allowed values: function\_call * null object **async** Whether execution may start before response generation completes. boolean **call\_id** required Original provider call identity used when delivering the result. string **input** required Raw custom-tool input, without JSON normalization. string **name** required Registered function or custom tool name. string **type** required string Allowed values: custom\_tool\_call * object null * null Tool result content (result of tool execution) object **error** string | null **result** **tool\_call\_id** required ID of the tool call this result corresponds to string **type** required string Allowed values: tool\_result * object Provider reasoning artifact, ordered against the text and tool calls it was interleaved with. object **bound\_tool\_call\_id** Id of the tool call this artifact is bound to, when the provider scopes it that way (Gemini attaches a thought signature to one function call). string | null **encrypted** Provider-encrypted reasoning context (OpenAI `encrypted_content`). Opaque. string | null **item\_id** Provider-assigned identifier, carried verbatim (e.g. OpenAI `rs_…`). string | null **provider** required Provider that produced this artifact (e.g. `anthropic`, `openai`). Replay is only valid against the provider that issued it. string **signature** Provider signature over this specific block (Anthropic thinking signature, Gemini `thoughtSignature`). Opaque. string | null **text** One of: * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * null Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null **tokens** Reasoning tokens attributed to this artifact, when reported. integer | null format: int32 **type** required string Allowed values: reasoning * object One of: * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * object Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object Verbatim chain-of-thought exposed by the provider (Anthropic extended thinking, Gemini thought parts, Chat Completions `reasoning_content`). object **kind** required string Allowed values: plain **text** required string * null Provider-curated summary segments, not raw chain-of-thought (OpenAI Responses `summary_text`). Safe to display; never the model’s own words. object **kind** required string Allowed values: summary **parts** required Array\ * object The provider withheld the content (Anthropic `redacted_thinking`). The artifact must still be replayed verbatim, so the part keeps its signature/encrypted payload while carrying no readable text. object **kind** required string Allowed values: redacted * object null * object Provider-native assistant content retained only for internal replay. object **content** required Original provider-native assistant content. object **provider** required Provider that owns and can replay this content. string **type** required string Allowed values: provider\_opaque **controls** One of: * object Runtime controls (model, reasoning, etc.) object **error\_disclosure** Error disclosure override for this turn: “generic”, “standard”, or “detailed”. Clamped to at most the mode allowed by the agent’s `error_disclosure` capability (capability absent => “standard”), so a client can narrow but never widen disclosure. string | null **hints** Generic client hints — arbitrary key-value pairs declared by the client. Session-level defaults are set at session creation; per-message values override session hints key-by-key (shallow merge). Examples: `{"setup_connection": true, "rich_media": true}` object | null **locale** Locale override for this message turn (BCP 47, e.g. `uk-UA`). Overrides the session locale for backend-authored strings and prompts. string | null **model\_id** Model ID to use for this message (format: model\_{32-hex}). Overrides session and agent model settings. string | null **reasoning** One of: * object Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * null Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * string null * null null **speed** Speed (service tier) for this message turn: “flex”, “default”, “priority”, “fast” (OpenAI’s newer name for priority) or “ultrafast”. Only sent when the model’s profile lists the tier (OpenAI `service_tier`); otherwise the runtime drops it. string | null **verbosity** Verbosity for this message turn: “low”, “medium”, or “high”. Only sent to providers whose model profile advertises a verbosity config (OpenAI `verbosity`). string | null * null Reasoning configuration object **effort** One of: * string Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * object Effort level for reasoning. Typed rather than free-form: the effort taxonomy is closed, and each driver previously re-parsed the string with its own case handling, which let `minimal` silently mean “no reasoning” on budget-based models. string Allowed values: none minimal low medium high xhigh max * null null * string null * null null **created\_at** required Timestamp when this resource was created (RFC 3339). string format: date-time **delivery** One of: * string How a message just created was delivered. Only set on the response to creating a message; absent when listing. string Allowed values: started steered resumed duplicate * null null **external\_actor** One of: * object External actor identity (for messages from external channels like Slack) object **actor\_id** required Opaque actor identifier from the source channel (e.g. Slack user ID “U0123456789”) string **actor\_name** Resolved display name (e.g. “Alice”). Falls back to actor\_id if absent. string | null **metadata** Channel-specific metadata (e.g. team\_id, channel\_id) object | null **source** required Source channel identifier (e.g. “slack”, “discord”) string * null null **id** required Unique message ID (format: message\_{32-hex}) string **metadata** Message-level metadata (locale, etc.) object | null **phase** One of: * string Execution phase for agent messages: whether this is intermediate `commentary` or the turn’s `final_answer`. Absent on user messages. Without this a client cannot tell an intermediate message from the answer, which is the single question most consumers of a session need answered. string Allowed values: commentary final\_answer * null null **phase\_source** One of: * string Whether `phase` was reported by the provider or inferred by the runtime from tool-call presence. `derived` is a weak signal: it means only “this message called tools”, so a text-only preamble is reported as `final_answer`. Clients needing a dependable classification should treat `derived` accordingly. string Allowed values: provider derived communication * null null **role** required Message role (API layer) Simplified to only user and agent messages. Tool results are conveyed via `tool.completed` events. System messages are internal and not exposed via API. string Allowed values: user agent **sequence** required integer format: int32 **session\_id** required Session ID this message belongs to (format: session\_{32-hex}) string ##### Example ```json { "data": [ { "content": [ { "annotations": [ { "end": 19, "external_id": "kchk_01j9y3q8w2", "origin": "citation_retrieval", "source": { "snippet": "The control plane owns durable state.", "title": "Architecture Overview", "uri": "github://owner/repo@main/docs/x.md" }, "start": 0, "verified": { "score": 0.92, "status": "entailed" } } ], "type": "text" } ], "controls": { "model_id": "model_01933b5a00007000800000000000001", "reasoning": { "effort": "none" } }, "delivery": "started", "id": "message_01933b5a00007000800000000000001", "phase": "commentary", "phase_source": "provider", "role": "user", "session_id": "session_01933b5a00007000800000000000001" } ] } ``` ### 400 Invalid ID format ### 404 Session not found ### 500 Internal server error