--- title: "List Agent Messages" method: GET path: "/agent/sessions/{agent_session_id}/messages" --- # List Agent Messages `GET /agent/sessions/{agent_session_id}/messages` ## Request - Base URL: `https://app.runconverge.com/api` - URL: `https://app.runconverge.com/api/agent/sessions/{agent_session_id}/messages` - Auth: none declared ## Path parameters - `agent_session_id` integer, required ## Query parameters - `follow` boolean - `after` integer - `exclude_system` boolean ## Headers - `accept` string - `Authorization` string, nullable - `X-User-Id` string, nullable ## Cookies - `session_id` string, nullable ## Response `200` SSE stream (Accept: text/event-stream) or JSON list (any other Accept) of messages with id > `after`. `exclude_system` omits `system` messages. - AgentMessageSchema[] - `id` integer, required - `session_id` integer, required - `payload` union, required - UserMessage: User message. - `type` 'user' - `content` union, required - string - union[] - union - TextBlock: Text content block. - … - ThinkingBlock: Thinking content block. - … - ToolUseBlock: Tool use content block. - … - ToolResultBlock: Tool result content block. - … - `attachments` union[] - union - QuoteAttachment: A verbatim excerpt the user highlighted from a prior assistant response, pinned to their next turn so the agent knows what they're replying to. - `id` string, required - `type` 'quote' - `text` string, required - FileQuoteAttachment: A verbatim excerpt the user highlighted from a workspace file in the drawer (e.g. a skill's markdown), pinned to their next turn so the agent knows which passage they mean. May carry a note the user attached to the excerpt. - `id` string, required - `type` 'file-quote' - `path` string, required - `file_title` string, required - `quote` string, required - `comment` string, nullable - FileAttachment: A workspace file pinned to the user's turn — uploaded for this message, or picked out of the workspace. Already materialized when it gets here; the agent reads it at `path`. `path` identifies the file (the upload endpoint issues one per upload, so re-uploading a name never aliases an earlier attachment). It is normalized and confined to the workspace at send, and `filename` is re-derived from it there, so the name the agent sees always matches the file it is given. - `id` string, required - `type` 'file' - `filename` string, required - `content_type` string, required - `size_bytes` integer, required - `path` string, required - `parent_tool_use_id` string, nullable - `tool_use_result` union - object - string - AssistantMessage: Assistant message with content blocks. - `type` 'assistant' - `content` union[], required - union - TextBlock: Text content block. - `type` 'text' - `text` string, required - ThinkingBlock: Thinking content block. - `type` 'thinking' - `thinking` string, required - `signature` string, required - ToolUseBlock: Tool use content block. - `type` 'tool_use' - `id` string, required - `name` string, required - `input` object, required - ToolResultBlock: Tool result content block. - `type` 'tool_result' - `tool_use_id` string, required - `content` union - … - `is_error` boolean, nullable - `error` 'authentication_failed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'unknown', nullable - SystemMessage: System message with metadata. - `type` 'system' - `subtype` string, required - `data` object, required - ResultMessage: Result message with cost and usage information. `total_cost_usd` and `usage` are the raw, margin-revealing figures the SDK emits. They are recorded internally but stripped before the message is persisted to the session stream; the customer-facing copy carries `credits` instead (see the supervisor). Never surface `total_cost_usd`/`usage` to customers. - `type` 'result' - `subtype` string, required - `duration_ms` integer, required - `duration_api_ms` integer, required - `is_error` boolean, required - `api_error_status` integer, nullable - `num_turns` integer, required - `session_id` string, required - `total_cost_usd` number, nullable - `usage` object, nullable - `credits` integer, nullable - `result` string, nullable - `structured_output` unknown - SuggestedPlanMessage - `type` 'suggested_plan' - `plan_id` integer, required - `version` integer, required - `title` string, nullable - AnalyticsQueryMessage: An analytics query the agent ran (e.g. attribution-analytics). - `type` 'artifact' - `tool_use_id` string, nullable - `kind` 'analytics_query' - `query` TrendsQueryOutput, required - `metrics` union[] - union - EventMetricOutput - … - AdPlatformMetric - … - FormulaMetric - … - InlineFormulaMetricOutput: A formula over its own inputs: A is `inputs[0]`, B `inputs[1]`, ... - … - `filters` AllOfFilters - `all_of` AnyOfFilters[] - `any_of` union[] - … - `breakdown` union - EventPropertyBreakdown - `type` 'event' - `scope` 'event' | 'profile' | 'session' | 'product', required - `property_name` union, required - … - `property_type` 'string' | 'numeric' | 'boolean' | 'list_of_strings', required - EventSourceBreakdown - `type` 'event_source' - AdPlatformSourceBreakdown - `type` 'ad_platform_source' - TouchpointBreakdown - `type` 'touchpoint' - `property` 'channel_group' | 'channel' | 'campaign' | 'adset' | 'ad', required - CustomDimensionBreakdown - `type` 'custom_dimension' - `custom_dimension_id` integer, required - `date_range` DateRangeQuery, required - `since` union, required - string, date - string, date-time - string - `until` union - string, date - string, date-time - string - `time_granularity` 'hour' | 'day' | 'week' | 'month' | 'second' - `compare` union - true - string, date - string - `attribution` ConvergeApiAttributionsAttribution - `mode` 'click_time' | 'conversion_time' - `model` 'first_touch' | 'first_touch_paid' | 'inv_j_shaped' | 'j_shaped' | 'j_shaped_paid' | 'last_touch' | 'last_touch_paid' | 'linear' | 'participation' | 'time_decay' | 'inv_time_decay' | 'u_shaped' | 'direct_session' | 'inv_j_shaped_paid' | 'top_of_funnel' - `window` integer - `lookback` integer, nullable - `type` 'trends' - TurnAbortedMessage: Server-synthesized terminal marker for a turn that ended without a normal SDK result — interrupted by the user, failed unrecoverably, or blocked because the workspace hit its monthly credit limit. Distinct from ResultMessage, which is the SDK's own end-of-turn record. - `type` 'turn_aborted' - `reason` 'interrupted' | 'failed' | 'credit_limit', required - `detail` string, nullable - `origin` 'stop_request' | 'sandbox_signal' | 'credit_limit' | 'turn_crashed' | 'retries_exhausted', nullable - `account_id` integer, nullable - PlanOutcomeMessage: Structured plan-review feedback emitted by the apply endpoint. - `type` 'plan_outcome' - `plan_id` integer, required - `plan_version` integer, required - `outcomes` ConvergeApiAgentSandboxTypesPlanOutcomeMessageSuggestion[], required - `suggestion_id` string, required - `success` boolean, required - `error` string, nullable - `overrides` union[] - union - CentsOverride: A monetary value the user changed before applying a suggestion. `from_cents` is the value the agent proposed, not the object's live value: an edit is measured against the proposal. Renders as `proposed_*`/ `applied_*` so it can't be read as a change's live precondition. The field names stay as they are — persisted messages deserialize into this model. TODO: Migrate this as well to major units - … - RoasOverride: A ROAS-goal value the user changed before applying a suggestion. Carries the agent's proposed multiplier (`from_roas`) and what the operator pushed (`to_roas`). - … - DuplicateOverride: Duplicate-ad start status / rename the user changed before applying. Carries the settings the agent proposed (`from_*`) alongside what the operator pushed (`to_*`). `rename_*` of `None` or "" both mean "not set" — with neither prefix nor suffix the copy keeps the source name verbatim — and render as an empty attribute. - … - ReplacedOverride: A change the user swapped for a different one before applying. The strongest signal the review loop produces: the operator didn't just retune the number, they wanted a different action on the same object. The agent sees what it proposed (`field`) and what actually went out (`to_field` / `to_summary`) so it can propose the right thing next time. - … - DisabledOverride: A change the user dropped from a compound suggestion before applying. The rest of the suggestion still went out, so this is narrower than a rejection: the operator wanted most of what was proposed, minus this part. - … - `created_object` CreatedObject: A new object created by applying a change in a suggestion. Reports the id the platform assigned the new object so the agent can act on it (rename, pause, scale further) without re-querying the platform to find where it landed. `field` is the change that created it (`duplicate_ad`, `duplicate_adset`, …). `source_object_id` is the object that was copied for a duplicate change, and is `None` when the object was created from scratch. - `change_index` integer, required - `field` string, required - `new_object_id` string, required - `source_object_id` string, nullable - `rejected` Feedback[] - `suggestion_id` string, required - `feedback` string, nullable - `skipped` string[] - `created_at` string, date-time, required - `account_id` integer, nullable ## Other responses - `422`: Validation Error ## Changes - **2026-10-15** `f723e951cc0b`: 2 info - added the optional property `items/payload/oneOf[subschema #7: TurnAbortedMessage]/account_id` to the response with the `200` status - added the optional property `items/payload/oneOf[subschema #7: TurnAbortedMessage]/origin` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/runconverge/apis/runconverge-api/changes/agent/sessions/:agent_session_id/messages/get.md) --- [API](https://skmtc.dev/runconverge/apis/runconverge-api.md) - [All operations](https://skmtc.dev/runconverge/apis/runconverge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runconverge/apis/runconverge-api/revisions/f723e951cc0b?raw)