--- title: "List Agent Messages" method: GET path: "/agent/sessions/{agent_session_id}/messages" --- # List Agent Messages `GET /agent/sessions/{agent_session_id}/messages` ## Path parameters - `agent_session_id` integer, required ## Query parameters - `follow` boolean - `after` integer ## 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`. - 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` TrendsQuery, required - `metrics` union[] - union - EventMetric - … - AdPlatformMetric - … - FormulaMetric - … - `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 - 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. Carries the agent's proposed value and what the operator pushed so the agent sees exactly what was edited. 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. - … - `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 - `follow_up` 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 --- [API](https://skmtc.dev/runconverge/apis/fastapi.md) · [All operations](https://skmtc.dev/runconverge/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runconverge/fastapi/revisions/1452e350bd1d/schema)