List messages (PRIMARY data)

GET

/v1/sessions/{session_id}/messages

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);
}

curl --request GET \
  --url https://app.everruns.com/api/v1/sessions/example/messages

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Responses

200

List of messages

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

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:

Text content

object

annotations

Claim-level citations attached to spans of text.

The narrow render contract shared by all citation capabilities (see knowledge/runtime-resources/citations.md). Empty for non-cited text, so the wire shape of existing messages is unchanged.

Array<object>

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. See knowledge/runtime-resources/citations.md.

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:

null
object

null

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

text

required

string

type

required

string

Allowed values: text

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:

null
object

null

One of:

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

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

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

tokens

Reasoning tokens attributed to this artifact, when reported.

integer | null format: int32

type

required

string

Allowed values: reasoning

controls

One of:

null
object

null

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:

null
object

null

Reasoning configuration

object

effort

One of:

null
string

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

speed

Speed (service tier) for this message turn: “flex”, “default”, or “priority”. Only sent to providers whose model profile advertises a speed config (OpenAI service_tier).

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

created_at

required

Timestamp when this resource was created (RFC 3339).

string format: date-time

external_actor

One of:

null
object

null

required

Unique message ID (format: message_{32-hex})

string

metadata

Message-level metadata (locale, etc.)

object | null

phase

One of:

null
string

null

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

phase_source

One of:

null
string

null

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

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

{
  "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"
        }
      },
      "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