> ## Documentation Index > Fetch the complete documentation index at: https://docs.reygrid.com/llms.txt > Use this file to discover all available pages before exploring further. # List conversation messages > Returns a paginated list of messages. conversationRef can be either a conversationId or a persistent userId. ## OpenAPI ````yaml /openapi.yaml get /agents/{agentId}/conversations/{conversationRef}/messages openapi: 3.0.3 info: title: ReyGrid API version: 1.0.3 description: | ReyGrid API ## Persistent user conversations If you want to build a separate conversation system for each user, build a wrapper layer around the ReyGrid API. The wrapper should manage the application's own user IDs and map them to ReyGrid conversations. The wrapper is responsible for: - Managing and identifying users. - Storing the relationship between the application's userId and ReyGrid conversationId. - Persisting conversation IDs in the application's own database. - Reusing the stored conversationId when the same user continues a conversation. - Verifying that conversation IDs belong to the expected user before using them. ReyGrid's userId can also be used as a stable identifier for persistent conversations. However, if the application requires its own user and conversation management, it should maintain this mapping in its own database. servers: - url: https://reygrid.com/api/v1 security: [] paths: /agents/{agentId}/conversations/{conversationRef}/messages: get: summary: List conversation messages description: | Returns a paginated list of messages. conversationRef can be either a conversationId or a persistent userId. operationId: listConversationMessages parameters: - name: agentId in: path required: true description: The ID of the agent. schema: type: string - name: conversationRef in: path required: true description: > A conversation ID or persistent user ID. When a user ID is provided, it identifies the user's persistent conversation. schema: type: string - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/Size' responses: '200': description: Paginated list of messages content: application/json: schema: $ref: '#/components/schemas/MessagesResponse' example: success: true userId: user_42 messages: - id: msg_x6tWaZ3H9oOKd role: assistant content: >- Your order #1042 shipped yesterday and should arrive within 2 business days. feedback: rating: up createdAt: '2026-10-05T10:22:01.000Z' createdAt: '2026-10-05T10:21:36.002Z' - id: msg_mgGdMG8f9PUjc role: user content: 'Where is my order #1042?' createdAt: '2026-10-05T10:21:34.120Z' pagination: totalMessages: 14 totalPages: 1 currentPage: 1 pagingCounter: 1 hasNextPage: false '401': description: API key is missing or invalid content: application/json: schema: $ref: '#/components/schemas/AuthErrorResponse' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: CONVERSATION_NOT_FOUND message: This conversation does not exist security: - apiKeyAuth: [] x-codeSamples: - lang: bash label: cURL source: >- curl "https://reygrid.com/api/v1/agents/{AgentId}/conversations/user_42/messages?size=50" \ -H "Authorization: Bearer $REYGRID_API_KEY" - lang: python label: Python SDK source: |- from reygrid import ReyGrid client = ReyGrid(api_key="YOUR_API_KEY") res = client.list_messages("{AgentId}", "user_42", size=50) for message in res.messages: # newest first print(message.role, message.content) - lang: javascript label: TypeScript SDK source: >- import { ReyGrid } from "reygrid"; const client = new ReyGrid({ apiKey: "YOUR_API_KEY" }); const { messages } = await client.listMessages("{AgentId}", "user_42", { size: 50 }); for (const m of messages) console.log(m.role, m.content); // newest first components: parameters: Page: name: page in: query required: false description: Page number. schema: type: integer minimum: 1 default: 1 Size: name: size in: query required: false description: Number of items per page. schema: type: integer minimum: 1 maximum: 100 default: 20 schemas: MessagesResponse: type: object required: - success - messages - pagination properties: success: type: boolean userId: type: string conversationId: type: string messages: type: array items: $ref: '#/components/schemas/Message' pagination: $ref: '#/components/schemas/MessagesPagination' AuthErrorResponse: type: object required: - error - code properties: error: type: string example: Unauthorized code: type: string example: AUTH_REQUIRED ErrorResponse: type: object required: - success - error properties: success: type: boolean output: type: object additionalProperties: true error: $ref: '#/components/schemas/Error' usage: $ref: '#/components/schemas/ChatUsage' Message: type: object required: - id - role - createdAt properties: id: type: string content: type: string role: type: string tool_calls: type: array items: $ref: '#/components/schemas/MessageToolCall' createdAt: type: string format: date-time MessagesPagination: allOf: - $ref: '#/components/schemas/Pagination' - type: object required: - totalMessages properties: totalMessages: type: integer Error: type: object required: - code - message properties: code: type: string message: type: string list: type: array description: | Validation error details. Present when error.code is INVALID_BODY. items: $ref: '#/components/schemas/ValidationErrorItem' ChatUsage: type: object required: - credits properties: credits: type: number MessageToolCall: type: object required: - id - type - function properties: id: type: string type: type: string enum: - function function: $ref: '#/components/schemas/ToolCallFunction' status: type: string Pagination: type: object required: - totalPages - currentPage - pagingCounter - hasNextPage properties: totalPages: type: integer currentPage: type: integer pagingCounter: type: integer hasNextPage: type: boolean ValidationErrorItem: type: object additionalProperties: true ToolCallFunction: type: object required: - name - arguments properties: name: type: string arguments: type: string securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: API-Key description: ReyGrid API key sent as a Bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.