> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # List messages > Returns the list of messages in a conversation. ## OpenAPI ````yaml get /conversations/{conversation_id}/messages openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /conversations/{conversation_id}/messages: get: tags: - Conversations summary: List messages description: Returns the list of messages in a conversation. operationId: Conversations.listMessages parameters: - name: conversation_id in: path required: true schema: type: string description: The id of the conversation to list messages for. - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' responses: '200': description: List of messages content: application/json: schema: type: object required: - object - data properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/ConversationMessage' description: >- An array containing the actual response elements, paginated by any request parameters. has_more: type: boolean description: >- Whether or not there are more elements available after this set. If false, this set comprises the end of the list. '404': description: >- Not found. The requested conversation does not exist, or the authenticated user does not have permission to access it. '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' x-codeSamples: - lang: JavaScript source: >- import Datagrid from 'datagrid-ai'; const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const message of client.conversations.messages.list('conversation_id')) { console.log(message.id); } - lang: Python source: |- import os from datagrid_ai import Datagrid client = Datagrid( api_key=os.environ.get("DATAGRID_API_KEY"), # This is the default and can be omitted ) page = client.conversations.messages.list( conversation_id="conversation_id", ) page = page.data[0] print(page.id) components: parameters: limit: name: limit in: query schema: type: integer default: 50 minimum: 1 maximum: 100 required: false description: The limit on the number of objects to return, ranging between 1 and 100. after: name: after in: query schema: type: string required: false description: >- A cursor to use in pagination. `after` is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `after=obj_foo` to fetch the next page of the list. before: name: before in: query schema: type: string required: false description: >- A cursor to use in pagination. `before` is an object ID that defines your place in the list. For example, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `before=obj_bar` to fetch the previous page of the list. schemas: ConversationMessage: type: object description: >- The `conversation.message` object represents a message in a conversation. required: - object - id - agent_id - role - content - created_at - conversation_id - credits - citations properties: object: type: string enum: - conversation.message description: The object type, which is always `conversation.message`. id: type: string description: The message identifier. agent_id: type: string description: The ID of the agent that sent or responded to the message. role: type: string enum: - user - agent description: The role of the message sender - either 'user' or 'agent'. content: type: array description: Contents of the message. items: oneOf: - $ref: '#/components/schemas/MessageContentText' - $ref: '#/components/schemas/MessageContentVoice' - $ref: '#/components/schemas/MessageContentFile' discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/MessageContentText' voice: $ref: '#/components/schemas/MessageContentVoice' input_file: $ref: '#/components/schemas/MessageContentFile' created_at: type: string format: date-time description: The ISO string for when the message was created. conversation_id: type: string description: The ID of the conversation the message belongs to. credits: nullable: true description: >- Credit consumption for this converse turn. `null` for user-role messages and when retrieving messages from conversation history. allOf: - $ref: '#/components/schemas/OperationCredits' citations: $ref: '#/components/schemas/Citations' nullable: true RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. MessageContentText: type: object description: Text content for a message. required: - type - text properties: type: type: string enum: - text x-stainless-const: true text: type: string description: The text content of the message. MessageContentVoice: type: object description: Voice content for a message. required: - type - audio_clips - transcript - duration_ms properties: type: type: string enum: - voice x-stainless-const: true audio_clips: type: array description: Array of audio clips with timestamps for synchronized playback. items: $ref: '#/components/schemas/VoiceAudioClip' transcript: type: string description: User transcript of the voice message. agent_transcript: type: string description: Agent transcript of the voice message (for agent role messages). nullable: true duration_ms: type: number description: Total duration of the voice message in milliseconds. nullable: true timeline_events: type: array description: >- Per-turn transcript, citation, and tool-call status events in chronological order. Each entry includes a timestamp offset from the start of the voice session. Present only for voice sessions that recorded timeline data. items: $ref: '#/components/schemas/VoiceTimelineEvent' MessageContentFile: type: object description: >- File attachment content for a message. Represents a file that was uploaded as part of the user's message. required: - type - file_id properties: type: type: string enum: - input_file x-stainless-const: true file_id: type: string description: >- The ID of the attached file. Use this ID with the files API to download the file content. OperationCredits: type: object required: - consumed properties: consumed: type: number description: The number of credits consumed by the operation. Citations: type: array description: >- Array of citations that provide sources for factual statements in the response. Each citation includes the referenced text and its sources. items: type: object required: - citation - sources properties: citation: type: string description: The text snippet from the response that is being cited. sources: type: array description: Array of sources that support this citation. items: $ref: '#/components/schemas/CitationSource' VoiceAudioClip: type: object description: A single audio clip from a voice message. required: - id - audio_uri - start_time_ms - duration_ms - participant properties: id: type: string description: >- Unique identifier for the audio clip file. Use this ID with the files API to download the audio content. audio_uri: type: string description: Datagrid file URI for the audio file (WAV format). start_time_ms: type: number description: >- Start time of this clip relative to the beginning of the voice message, in milliseconds. duration_ms: type: number description: Duration of this audio clip in milliseconds. participant: type: object description: Participant who spoke in this clip. required: - type - id properties: type: type: string enum: - user - agent id: type: string VoiceTimelineEvent: type: object description: >- A single event from a voice session timeline, representing a transcript turn, citation, or tool-call status update. required: - type - timestamp_ms properties: type: type: string enum: - transcript - citation - tool_call_status description: The type of timeline event. timestamp_ms: type: number description: >- Timestamp offset from the start of the voice session, in milliseconds. role: type: string enum: - user - agent description: The role of the participant for this event. text: type: string description: >- Plain text transcript for this turn. Present when type is 'transcript'. citations: $ref: '#/components/schemas/Citations' description: Citations for this event. Present when type is 'citation'. tool_name: type: string description: >- Name of the tool whose status changed. Present when type is 'tool_call_status'. status: type: string enum: - started - completed - failed description: >- Tool-call status for this event. Present when type is 'tool_call_status'. CitationSource: type: object required: - type - source_name - confirmations properties: type: type: string enum: - image - pdf_page - record - web_search - sql_query_result - action source_id: type: string description: Id of the source. source_name: type: string description: Name of the source. source_uri: type: string description: URI of the source. confirmations: type: array description: An array of text snippets from the source that confirm the citation. items: type: string securitySchemes: BearerAuth: type: http scheme: bearer ````