> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # List Conversation Messages > **Available for**: Chatflow Returns a conversation's history in scroll-loading form. Without `first_id`, the newest `limit` messages come back in chronological order; with `first_id`, the messages before it. **Standard API equivalent**: [List Conversation Messages](/en/3.13.x/develop/api/conversations/list-conversation-messages). Differences: - `user` is required. - These response fields never vary: - `feedback` is always `null`. - `retriever_resources` is always empty. - `agent_thoughts` is always empty. - `parent_message_id` is always the all-zero UUID. - Error codes differ. ## OpenAPI ````yaml /en/3.13.x/develop/api/openapi_service.json get /v2/messages openapi: 3.0.1 info: title: Dify Service API description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Dify Service API. Replace it with your deployment's API endpoint. variables: api_base_url: default: api.example.com/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Chat Messages description: Operations related to chat messages and interactions. - name: Files description: File upload and preview operations. - name: End Users description: Operations related to end user information. - name: Feedback description: User feedback operations. - name: Conversations description: Operations related to managing conversations. - name: Audio description: Text-to-Speech and Speech-to-Text operations. - name: Applications description: Operations to retrieve application settings and information. - name: Annotations description: Operations related to managing annotations for direct replies. - name: Human Input description: Endpoints for resuming paused workflows that require human input. - name: Workflow Runs description: Operations for executing and managing workflows. - name: Completion Messages description: Operations related to text generation and completion. - name: Knowledge Bases description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. - name: Documents description: >- Operations for creating, updating, and managing documents within a knowledge base. - name: Chunks description: Operations for managing document chunks and child chunks. - name: Metadata description: >- Operations for managing knowledge base metadata fields and document metadata values. - name: Tags description: Operations for managing knowledge base tags and tag bindings. - name: Models description: Operations for retrieving available models. - name: Knowledge Pipeline description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. - name: Deployed Environments description: >- Endpoints served by deployed environments over the `v2` base URL. Deployed environments serve only the endpoints in this group; calling any other path there returns `404 not_found`. Authentication and errors differ from the standard Service API; each page here is authoritative for deployed environments. paths: /v2/messages: get: tags: - Deployed Environments summary: List Conversation Messages description: >- **Available for**: Chatflow Returns a conversation's history in scroll-loading form. Without `first_id`, the newest `limit` messages come back in chronological order; with `first_id`, the messages before it. **Standard API equivalent**: [List Conversation Messages](/en/3.13.x/develop/api/conversations/list-conversation-messages). Differences: - `user` is required. - These response fields never vary: - `feedback` is always `null`. - `retriever_resources` is always empty. - `agent_thoughts` is always empty. - `parent_message_id` is always the all-zero UUID. - Error codes differ. operationId: listDeployedMessages parameters: - name: user in: query required: true description: >- End-user identifier, defined by your app and unique within it. Conversations belong to the app, the environment, and this `user` together; later reads and changes must send the same value. See [End User Identity](/en/3.13.x/develop/api/guides/end-user-identity). schema: type: string minLength: 1 maxLength: 255 - name: conversation_id in: query required: true description: >- ID of the conversation to read. Get conversation IDs from [List Conversations](/en/3.13.x/develop/api/deployed-environments/list-conversations). schema: type: string format: uuid - name: first_id in: query required: false description: >- Pagination cursor: the `id` of the first message on the current page. Pass it to fetch the previous (older) page; omit to fetch the latest messages. schema: type: string format: uuid - name: limit in: query required: false description: Number of chat history messages to return per request. schema: type: integer default: 20 minimum: 1 maximum: 100 responses: '200': description: One page of the conversation's messages, oldest first. content: application/json: schema: type: object properties: limit: type: integer description: Page size applied to this page. has_more: type: boolean description: Whether earlier messages exist. data: type: array description: Messages, oldest first. items: type: object properties: id: type: string description: Message ID. conversation_id: type: string description: Conversation ID. parent_message_id: type: string description: >- Always the all-zero UUID for messages created through this API. inputs: type: object description: Input variables for this turn. additionalProperties: true query: type: string description: The user's question. answer: type: string description: >- The app's answer. Recognizable file links are refreshed to current download URLs. feedback: type: object nullable: true description: >- Always `null`; message feedback is not available in deployed environments. additionalProperties: true retriever_resources: type: array description: Always an empty array in deployed environments. items: type: object properties: {} created_at: type: integer description: Creation time as a Unix timestamp in seconds. agent_thoughts: type: array description: Always an empty array in deployed environments. items: type: object properties: {} message_files: type: array description: Files attached to this turn. items: type: object properties: id: type: string description: Stable ID linking the message and the file. filename: type: string description: File name. type: type: string description: >- File category: `image`, `audio`, `video`, or `document`. url: type: string description: >- Relative download URL, already carrying the `user` query value (and `kind=tool` for tool-produced files). Fetch it against the deployed-environment base URL. mime_type: type: string description: MIME type. size: type: integer description: File size in bytes. transfer_method: type: string description: >- `local_file` for uploaded files; `tool_file` for files produced by tools. belongs_to: type: string description: '`user` or `assistant`.' upload_file_id: type: string description: >- The file's own ID, usable with [Download File](/en/3.13.x/develop/api/deployed-environments/download-file). message_tokens: type: integer description: Input token count. answer_tokens: type: integer description: Output token count. total_tokens: type: integer description: >- Total token count for the turn: `message_tokens` plus `answer_tokens`. provider_response_latency: type: number description: Always `0` in deployed environments. total_price: type: string nullable: true description: Total cost of the turn; `null` when unavailable. currency: type: string nullable: true description: Cost currency; `null` when unavailable. status: type: string description: >- `normal`, `stopped`, or `error`. A turn still running is reported as `normal`. error: type: string nullable: true description: Run error message; `null` on success. extra_contents: type: array description: Always an empty array in deployed environments. items: type: object properties: {} examples: ok: summary: Response Example value: limit: 20 has_more: false data: - id: 7c9e6679-7425-40de-944b-e07fc1f90ae7 conversation_id: 0f8fad5b-d9cb-469f-a165-70867728950e parent_message_id: 00000000-0000-0000-0000-000000000000 inputs: order_id: ORDER-1001 query: Where is my refund now? answer: Your refund is being processed by the bank. feedback: null retriever_resources: [] created_at: 1787788860 agent_thoughts: [] message_files: - id: a8098c1a-f86e-51da-bd1e-66d42f3f323a filename: receipt.pdf type: document url: >- /v2/files/16fd2706-8baf-433b-82eb-8c7fada847da/preview?user=customer-001 mime_type: application/pdf size: 48231 transfer_method: local_file belongs_to: user upload_file_id: 16fd2706-8baf-433b-82eb-8c7fada847da message_tokens: 28 answer_tokens: 19 total_tokens: 47 provider_response_latency: 0 total_price: '0.0012' currency: USD status: normal error: null extra_contents: [] '400': description: >- - `invalid_param`: a path or query value breaks its validation rule. The message names the rule the value broke, such as `value must be a valid UUID` for a malformed `conversation_id`. - `invalid_param`: `user` contains only whitespace. The message is `invalid argument`. - `not_chat_app`: the API key belongs to an app that is not a Chatflow. - `app_unavailable`: the app can't serve API requests in this environment right now. - API access is turned off. - The app is not deployed here. - A deployment is still rolling out. - The environment is being deleted. Ask the app's owner to check its **Access Point** tab, or an administrator to check the environment in the Enterprise Dashboard, and retry once it serves again. content: application/json: examples: invalid_param: summary: invalid_param value: code: invalid_param message: >- invalid ListServiceAPIMessagesRequest.ConversationId: value must be a valid UUID | caused by: invalid uuid format status: 400 invalid_param_user: summary: invalid_param (whitespace user) value: code: invalid_param message: invalid argument status: 400 not_chat_app: summary: not_chat_app value: status: 400 code: not_chat_app message: Please check if your app mode matches the right API route. app_unavailable: summary: app_unavailable value: status: 400 code: app_unavailable message: App unavailable, please check your app configurations. '401': description: >- `unauthorized`: the API key is missing, malformed, unknown, or revoked. content: application/json: examples: unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 '404': description: >- - `not_found`: the conversation does not exist or does not belong to this `user`. - `not_found`: `first_id` names a message that is not in this conversation. content: application/json: examples: not_found: summary: not_found value: status: 404 code: not_found message: Conversation Not Exists. not_found_first_message: summary: not_found (first_id) value: code: not_found message: First Message Not Exists. status: 404 '500': description: >- `internal_server_error`: the platform could not complete the request; retry, and contact your administrator if it persists. content: application/json: examples: internal_server_error: summary: internal_server_error value: code: internal_server_error message: internal error status: 500 servers: - url: https://{deployed_api_base_url} description: >- Base URL shared by every deployed environment: the standard Service API address, with `/v2` in place of `/v1`. variables: deployed_api_base_url: default: api.example.com description: >- On the app's **Access Point** tab, copy the full URL from any deployed environment's **Backend Service API** card, then remove the `https://` prefix and the trailing `/v2`. components: securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/3.13.x/develop/api/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). ````