---
title: "Read messages for one agent session"
method: GET
path: "/agents/sessions/{session_id}/messages"
tags: ["AI", "Agents"]
---

# Read messages for one agent session

`GET /agents/sessions/{session_id}/messages`

## Request

- Base URL: `https://app.mammoth.io/api/v2`
- URL: `https://app.mammoth.io/api/v2/agents/sessions/{session_id}/messages`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-KEY` and API key in header `X-API-SECRET` and API key in header `X-WORKSPACE-ID`

## Path parameters

- `session_id` string, required

## Response `200`

Request fulfilled, document follows

- AgentSessionMessagesResponse
  - `session_id` string, required
  - `messages` AgentDisplayMessage[], required
    - `id` string
    - `role` string, required
    - `content` string, required
    - `status` string
    - `thinking` string, nullable
    - `message_type` string, nullable
    - `request_id` string, nullable
    - `questions` unknown[], nullable
      - unknown
    - `answered` boolean, nullable
    - `answers` object, nullable
    - `charts` object[], nullable
    - `widget` object, nullable
    - `resolved` boolean, nullable
    - `result` unknown
    - `quick_replies` union[], nullable
      - union
        - string
        - object
    - `sources` object[], nullable
    - `parts` object[], nullable
    - `attachments` union[], nullable
      - union
        - DatasetAttachment
          - `dataset_id` integer, required
          - `name` string, required
          - `view_id` integer, nullable
        - BiWorkbookAttachment
          - `kind` 'bi_workbook', required
          - `attachment_id` integer, required
          - `filename` string, required
          - `name` string, required
        - SourceFileAttachment
          - `kind` 'source_file', required
          - `file_id` integer, required
          - `name` string, required
          - `reading` string, nullable
        - ImageAttachment
          - `kind` 'image', required
          - `ref` string, required
          - `name` string, required
        - DocumentAttachment
          - `kind` 'document', required
          - `ref` string, required
          - `name` string, required
    - `plan` Plan
      - `schema_version` 1
      - `plan_id` string, required
      - `revision` integer, required
      - `kind` 'recommendation' | 'execution', required
      - `goal` string, required
      - `steps` PlanStep[], required
        - `n` integer, required
        - `title` string, required
        - `why` string, nullable
        - `touches` ObjectRef[]
          - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
          - `id` integer, nullable
          - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `reads` ObjectRef[]
          - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
          - `id` integer, nullable
          - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `makes` string[]
        - `names` string[]
        - `renames` Rename[]
          - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'automation' | 'project', required
          - `requested` string, required
          - `final` string, required
        - `workflow_ops` object[]
        - `workflow_changes` object[]
        - `needs` string, nullable
        - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
        - `result` string, nullable
        - `produced` ObjectRef[]
          - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
          - `id` integer, nullable
          - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `changed` ObjectRef[]
          - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
          - `id` integer, nullable
          - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `by` 'agent' | 'user'
        - `after` integer[], nullable
        - `replaced` boolean
        - `since_revision` integer, nullable
        - `wait` StepWait
          - `job` string, nullable: The id of a job already started, e.g. "4821".
          - `until` string, date-time, nullable: An ISO 8601 UTC time, e.g. "2026-10-05T03:00:00Z".
        - `skipped_by` 'user' | 'left_out' | 'null', nullable
        - `failed_at` string, date-time, nullable
        - `row_effect` object, nullable
        - `alert_effect` object, nullable
        - `join_effect` object, nullable
        - `send_effect` object, nullable
        - `credentials` ConnectorCredentialInput
          - `auth_type` string, required: The connector's authentication scheme, e.g. 'api_key', 'oauth2', 'basic'. Used only to route the submitted values, never rendered as a label.
          - `fields` CredentialField[], required: The credential fields to collect, in the order they should appear — e.g. [{'name': 'api_key', 'label': 'API key'}]. Name every field the connector actually needs; never include one whose value you already have. Do not include a 'value' — this card never carries one.
            - `name` string, required
            - `label` string
            - `sensitive` boolean
            - `required` boolean: True when the connector cannot be created without this field, e.g. a username or password. The card marks every other field optional and keeps Connect disabled until each required one is filled.
        - `credentials_needed` boolean
      - `supersedes` string, nullable
      - `request_kind` 'build' | 'automate' | 'fix', nullable
      - `workflow_id` integer, nullable
      - `workflow_build` WorkflowBuild
        - `run_id` string, required
        - `keys` string[], required
        - `status` 'running' | 'done' | 'partial' | 'failed'
        - `message` string, nullable
        - `built_keys` string[]
        - `final` object
        - `run` BuildRun
          - `id` string, required
          - `status` string, nullable
          - `started_at` string, nullable
          - `finished_at` string, nullable
          - `steps` BuildRunStep[]
            - `kind` string, nullable
            - `label` string, nullable
            - `keys` string[]
            - `status` string, nullable
            - `started_at` string, nullable
            - `progressed_at` string, nullable
            - `finished_at` string, nullable
            - `result` object, nullable
      - `scope_project` EffectObject
        - `kind` string, required
        - `id` integer, nullable
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `worked_after_failure` integer[]
      - `assumptions` string[]
      - `combined_effect` object, nullable
      - `effect` PlanEffect, required: What the plan does, for the plan card (see ``plan_effect``).
        - `steps` StepEffect[], required
          - `n` integer, required
          - `kind` 'read' | 'make' | 'change' | 'deferred', required
          - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
          - `made` EffectObject[], required
            - `kind` string, required
            - `id` integer, nullable
            - `name` string
            - `project_id` integer, nullable
            - `project` string
          - `changed` EffectObject[], required
            - `kind` string, required
            - `id` integer, nullable
            - `name` string
            - `project_id` integer, nullable
            - `project` string
          - `project_id` integer, nullable
          - `project` string
        - `makes` object, required
        - `new_projects` integer, required
        - `changes` integer, required
        - `project` string, nullable
        - `changes_project` string, nullable
        - `may_change` boolean, required
        - `may_change_in` string, nullable
        - `gates` string[]
        - `gate_target` string
      - `example` boolean, required: Whether the plan is an example workflow (Show me): a recommendation whose steps carry workflow changes. It is previewed, never built.
    - `plan_ref` PlanRef
      - `plan_id` string, required
      - `n` integer, nullable
      - `action` 'skip' | 'discard' | 'build' | 'null', nullable
      - `leave_out` integer[]
    - `events` object[], nullable
    - `resumable` boolean, nullable
    - `at` integer, nullable
    - `request_kind` object, nullable
    - `turn_id` string, nullable
  - `working` boolean
  - `turn_id` string, nullable
  - `plan` Plan
    - `schema_version` 1
    - `plan_id` string, required
    - `revision` integer, required
    - `kind` 'recommendation' | 'execution', required
    - `goal` string, required
    - `steps` PlanStep[], required
      - `n` integer, required
      - `title` string, required
      - `why` string, nullable
      - `touches` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `reads` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `makes` string[]
      - `names` string[]
      - `renames` Rename[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'automation' | 'project', required
        - `requested` string, required
        - `final` string, required
      - `workflow_ops` object[]
      - `workflow_changes` object[]
      - `needs` string, nullable
      - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
      - `result` string, nullable
      - `produced` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `changed` ObjectRef[]
        - `kind` 'dataset' | 'view' | 'dashboard' | 'export' | 'project' | 'file' | 'folder', required
        - `id` integer, nullable
        - `of_step` integer, nullable: The `n` of the earlier step that makes this object (its `makes` has this `kind`), instead of an `id`, for an object that does not exist yet.
        - `name` string
        - `project_id` integer, nullable
        - `project` string
      - `by` 'agent' | 'user'
      - `after` integer[], nullable
      - `replaced` boolean
      - `since_revision` integer, nullable
      - `wait` StepWait
        - `job` string, nullable: The id of a job already started, e.g. "4821".
        - `until` string, date-time, nullable: An ISO 8601 UTC time, e.g. "2026-10-05T03:00:00Z".
      - `skipped_by` 'user' | 'left_out' | 'null', nullable
      - `failed_at` string, date-time, nullable
      - `row_effect` object, nullable
      - `alert_effect` object, nullable
      - `join_effect` object, nullable
      - `send_effect` object, nullable
      - `credentials` ConnectorCredentialInput
        - `auth_type` string, required: The connector's authentication scheme, e.g. 'api_key', 'oauth2', 'basic'. Used only to route the submitted values, never rendered as a label.
        - `fields` CredentialField[], required: The credential fields to collect, in the order they should appear — e.g. [{'name': 'api_key', 'label': 'API key'}]. Name every field the connector actually needs; never include one whose value you already have. Do not include a 'value' — this card never carries one.
          - `name` string, required
          - `label` string
          - `sensitive` boolean
          - `required` boolean: True when the connector cannot be created without this field, e.g. a username or password. The card marks every other field optional and keeps Connect disabled until each required one is filled.
      - `credentials_needed` boolean
    - `supersedes` string, nullable
    - `request_kind` 'build' | 'automate' | 'fix', nullable
    - `workflow_id` integer, nullable
    - `workflow_build` WorkflowBuild
      - `run_id` string, required
      - `keys` string[], required
      - `status` 'running' | 'done' | 'partial' | 'failed'
      - `message` string, nullable
      - `built_keys` string[]
      - `final` object
      - `run` BuildRun
        - `id` string, required
        - `status` string, nullable
        - `started_at` string, nullable
        - `finished_at` string, nullable
        - `steps` BuildRunStep[]
          - `kind` string, nullable
          - `label` string, nullable
          - `keys` string[]
          - `status` string, nullable
          - `started_at` string, nullable
          - `progressed_at` string, nullable
          - `finished_at` string, nullable
          - `result` object, nullable
    - `scope_project` EffectObject
      - `kind` string, required
      - `id` integer, nullable
      - `name` string
      - `project_id` integer, nullable
      - `project` string
    - `worked_after_failure` integer[]
    - `assumptions` string[]
    - `combined_effect` object, nullable
    - `effect` PlanEffect, required: What the plan does, for the plan card (see ``plan_effect``).
      - `steps` StepEffect[], required
        - `n` integer, required
        - `kind` 'read' | 'make' | 'change' | 'deferred', required
        - `status` 'proposed' | 'approved' | 'in_progress' | 'done' | 'skipped' | 'failed' | 'blocked' | 'stopped', required
        - `made` EffectObject[], required
          - `kind` string, required
          - `id` integer, nullable
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `changed` EffectObject[], required
          - `kind` string, required
          - `id` integer, nullable
          - `name` string
          - `project_id` integer, nullable
          - `project` string
        - `project_id` integer, nullable
        - `project` string
      - `makes` object, required
      - `new_projects` integer, required
      - `changes` integer, required
      - `project` string, nullable
      - `changes_project` string, nullable
      - `may_change` boolean, required
      - `may_change_in` string, nullable
      - `gates` string[]
      - `gate_target` string
    - `example` boolean, required: Whether the plan is an example workflow (Show me): a recommendation whose steps carry workflow changes. It is previewed, never built.
  - `scope` AgentObjectScope
    - `kind` 'workflow' | 'dataset', required
    - `id` integer, required
    - `name` string, nullable
    - `project_id` integer, nullable
  - `summary` AgentSessionSummary
    - `session_id` string, required
    - `agent_key` string, required
    - `scope_type` string, required
    - `scope_id` integer, nullable
    - `title` string, nullable
    - `status` string, required
    - `visibility` 'private' | 'shared', required
    - `owner_user_id` integer, required
    - `is_owner` boolean, required
    - `project_scope` string, nullable
    - `project_id` integer, nullable
    - `workflow_id` integer, nullable
    - `scope` AgentObjectScope
      - `kind` 'workflow' | 'dataset', required
      - `id` integer, required
      - `name` string, nullable
      - `project_id` integer, nullable
    - `object_chat` AgentObjectChat
      - `kind` 'workflow' | 'view' | 'dataset' | 'automation' | 'automations' | 'lineage', required
      - `id` integer, required
      - `name` string, nullable
      - `project_id` integer, nullable
      - `dataset_id` integer, nullable
      - `dataset_name` string, nullable
    - `created_at` string, nullable
    - `last_active_at` string, nullable
    - `attention` 'question' | 'approval' | 'stopped' | 'failed' | 'new_result' | 'waiting_job' | 'waiting_time' | 'paused' | 'capped' | 'null', nullable
    - `unseen` boolean
    - `needs_you` boolean
    - `made` AgentSessionMade
      - `kind` string, required
      - `id` union, required
        - integer
        - string
      - `name` string, required
    - `match` AgentSessionMatch
      - `field` 'title' | 'message' | 'made', required
      - `snippet` string, required
    - `pinned_at` string, nullable
    - `title_source` 'auto' | 'result' | 'user' | 'null', nullable

## Other responses

- `400`: Bad request syntax or unsupported method
- `403`: Request forbidden -- authorization will not help

---

[API](https://skmtc.dev/mammoth/apis/mammoth-analytics.md) · [All operations](https://skmtc.dev/mammoth/apis/mammoth-analytics/llms.txt) · [OpenAPI document](https://skmtc.dev/mammoth/apis/mammoth-analytics/revisions/fe078afe239b?raw)