---
title: "List agent run messages"
method: GET
path: "/api/agents/{agentId}/run-async/{runId}/messages"
tags: ["Agents"]
---

# List agent run messages

`GET /api/agents/{agentId}/run-async/{runId}/messages`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/agents/{agentId}/run-async/{runId}/messages`
- Auth: HTTP bearer

Page through an agent run's conversation, oldest first: messages to the agent, its replies, and its tool calls with their output. Works at any run status. A message keeps its offset as the run grows; the latest page starts at `totalCount - limit`.

## Path parameters

- `agentId` string, uuid, required: Unique identifier of the agent
- `runId` string, uuid, required: Unique identifier of the asynchronous run to check status for

## Query parameters

- `offset` integer: Messages to skip, counting from the oldest (default 0)
- `limit` integer: Most messages to return (default 20)

## Response `200`

Successful response

- object: A page of an agent run conversation
  - `totalCount` integer, required: Messages in the run so far
  - `messages` union[], required
    - union: A message, reply, or tool call in an agent run
      - object
        - `type` 'user', required
        - `text` string, required
        - `timestamp` string, required: ISO 8601 time it was written
      - object
        - `type` 'agent', required
        - `text` string, required
        - `timestamp` string, required: ISO 8601 time it was written
      - object
        - `type` 'tool', required
        - `action` string, required: Integration action the agent called
        - `status` 'inProgress' | 'success' | 'error', required
        - `input` unknown
        - `output` string: The result the agent read, cut at 10000 characters
        - `timestamp` string, required: ISO 8601 time it was written

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)