> ## Documentation Index > Fetch the complete documentation index at: https://dify-6c0370d8-fix-template-upload-size-guidance.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List Conversation Messages > **Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps. Returns a conversation's message history, newest first. Pass `first_id` to page backward into older messages. ## OpenAPI ````yaml /en/api-reference/openapi_service.json get /messages openapi: 3.0.1 info: 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. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline paths: /messages: get: tags: - Conversations summary: List Conversation Messages description: >- **Available for**: Chatflow, Agent, Chatbot, Legacy Agent apps. Returns a conversation's message history, newest first. Pass `first_id` to page backward into older messages. operationId: getConversationHistory parameters: - description: >- ID of the conversation to read. Get conversation IDs from [List Conversations](/en/api-reference/conversations/list-conversations). in: query name: conversation_id required: true schema: type: string - description: >- End-user identifier, defined by your app and unique within it. See [End User Identity](/en/api-reference/guides/end-user-identity). in: query name: user required: false schema: type: string - 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. in: query name: first_id required: false schema: type: string - description: Number of chat history messages to return per request. in: query name: limit required: false schema: default: 20 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: examples: conversationHistory: summary: Response Example value: data: - agent_thoughts: [] answer: iPhone 13 Pro Max specs are listed here:... answer_tokens: 58 conversation_id: 45701982-8118-4bc5-8e9b-64562b4555f2 created_at: 1705407629 currency: USD error: null extra_contents: [] feedback: rating: like id: 9da23599-e713-473b-982c-4328d4f5c78a inputs: city: San Francisco message_files: [] message_tokens: 100 parent_message_id: null provider_response_latency: 1.234 query: What are the specs of the iPhone 13 Pro Max? retriever_resources: [] status: normal total_price: '0.0012825' total_tokens: 158 has_more: false limit: 20 schema: $ref: '#/components/schemas/ConversationHistoryResponse' description: Successfully retrieved conversation history. '400': content: application/json: examples: not_chat_app: summary: not_chat_app value: code: not_chat_app message: Please check if your app mode matches the right API route. status: 400 description: '`not_chat_app` : App mode does not match the API route.' '404': content: application/json: examples: conversation_not_exists: summary: not_found value: code: not_found message: Conversation Not Exists. status: 404 first_message_not_exists: summary: not_found value: code: not_found message: First Message Not Exists. status: 404 description: |- - `not_found` : Conversation does not exist. - `not_found` : First message does not exist (invalid `first_id`). components: schemas: ConversationHistoryResponse: properties: data: description: List of messages. items: $ref: '#/components/schemas/ConversationMessageItem' type: array has_more: description: Whether there are more messages. type: boolean limit: description: Number of items per page. type: integer type: object ConversationMessageItem: properties: agent_thoughts: description: Agent thoughts for this message. items: $ref: '#/components/schemas/AgentThoughtItem' type: array answer: description: Assistant answer text. type: string answer_tokens: description: Number of tokens in the generated answer. type: integer conversation_id: description: Conversation ID. format: uuid type: string created_at: description: Creation timestamp (Unix epoch seconds). format: int64 type: integer currency: description: >- Currency for `total_price` (for example, `USD`), or `null` when pricing is unavailable. nullable: true type: string error: description: Error message if `status` is `error`. nullable: true type: string extra_contents: description: >- Additional execution content associated with this message, such as human input form data from Human Input nodes in Chatflow workflows. items: $ref: '#/components/schemas/HumanInputContent' type: array feedback: description: User feedback for this message. nullable: true properties: rating: description: Feedback rating. `like` for positive, `dislike` for negative. type: string type: object id: description: Message ID. format: uuid type: string inputs: additionalProperties: true description: Input variables for this message. type: object message_files: description: Files attached to this message. items: $ref: '#/components/schemas/MessageFileItem' type: array message_tokens: description: Number of tokens in the input message. type: integer parent_message_id: description: Parent message ID for threaded conversations. format: uuid nullable: true type: string provider_response_latency: description: Model provider response latency in seconds. format: double type: number query: description: User query text. type: string retriever_resources: description: Retriever resources used for this message. items: $ref: '#/components/schemas/RetrieverResource' type: array status: description: >- Message status. `normal` for successful messages, `error` when generation failed. type: string total_price: description: >- Total price for the tokens used, or `null` when pricing is unavailable. format: decimal nullable: true type: string total_tokens: description: Total tokens used, the sum of `message_tokens` and `answer_tokens`. type: integer type: object AgentThoughtItem: description: An agent thought step in the message. properties: chain_id: description: Chain ID for this thought. nullable: true type: string created_at: description: Creation timestamp. format: int64 type: integer files: description: File IDs related to this thought. items: type: string type: array id: description: Agent thought ID. format: uuid type: string message_id: description: Unique message ID this thought belongs to. format: uuid type: string observation: description: Response from tool calls. type: string position: description: Position of this thought. type: integer thought: description: What LLM is thinking. type: string tool: description: Tools called, split by `;`. type: string tool_input: description: Input of tools in JSON format. type: string tool_labels: additionalProperties: true description: Labels for tools used. nullable: true type: object type: object HumanInputContent: description: >- Execution content from a Human Input node, including form definition and submission data. properties: form_definition: $ref: '#/components/schemas/HumanInputFormDefinition' description: >- Form definition from the Human Input node. `null` when the content represents a submission response. nullable: true form_submission_data: $ref: '#/components/schemas/HumanInputFormSubmissionData' description: >- Submitted form data. `null` when the form has not been submitted yet. nullable: true submitted: description: Whether the human input form has been submitted. type: boolean type: description: '`human_input` for human input content.' type: string workflow_run_id: description: ID of the workflow run this content belongs to. type: string type: object MessageFileItem: description: A file attached to a message. properties: belongs_to: description: >- Who this file belongs to. `user` for user-uploaded files, `assistant` for assistant-generated files. nullable: true type: string filename: description: Original filename. type: string id: description: File ID. format: uuid type: string mime_type: description: MIME type of the file. nullable: true type: string size: description: File size in bytes. nullable: true type: integer transfer_method: description: >- Transfer method used. `remote_url` for URL-based files, `local_file` for uploaded files, `tool_file` for tool-generated files. type: string type: description: File type, e.g., `image`. type: string upload_file_id: description: Upload file ID if transferred via `local_file`. format: uuid nullable: true type: string url: description: Preview URL for the file. format: url nullable: true type: string type: object RetrieverResource: description: Citation and attribution information for a retriever resource. properties: content: description: Content snippet from the resource. type: string created_at: description: Creation timestamp (Unix epoch seconds). format: int64 type: integer data_source_type: description: Type of the data source. type: string dataset_id: description: ID of the knowledge base. format: uuid type: string dataset_name: description: Name of the knowledge base. type: string document_id: description: ID of the document. format: uuid type: string document_name: description: Name of the document. type: string hit_count: description: Number of times this chunk was hit. type: integer id: description: Unique ID of the retriever resource. format: uuid type: string index_node_hash: description: Hash of the index node. type: string message_id: description: ID of the message this resource belongs to. format: uuid type: string position: description: Position of the resource in the list. type: integer score: description: Similarity score of the resource. format: float type: number segment_id: description: ID of the specific chunk within the document. format: uuid type: string segment_position: description: Position of the chunk within the document. type: integer summary: description: Summary of the chunk content. nullable: true type: string word_count: description: Word count of the chunk. type: integer type: object HumanInputFormDefinition: description: Definition of a human input form rendered by a Human Input node. properties: actions: description: Action buttons available on the form. items: $ref: '#/components/schemas/UserAction' type: array display_in_ui: description: Whether the form should be displayed in the UI. type: boolean expiration_time: description: Unix timestamp when the form expires. type: integer form_content: description: Markdown or text content displayed with the form. type: string form_id: description: Unique form identifier. type: string form_token: description: Token for form submission authentication. nullable: true type: string inputs: description: Input fields in the form. items: $ref: '#/components/schemas/FormInput' type: array node_id: description: ID of the Human Input node that generated this form. type: string node_title: description: Title of the Human Input node. type: string resolved_default_values: additionalProperties: true description: >- Resolved default values for form inputs, keyed by output variable name. type: object type: object HumanInputFormSubmissionData: description: Data from a submitted human input form. properties: action_id: description: ID of the action button that was clicked. type: string action_text: description: Display text of the action button that was clicked. type: string node_id: description: ID of the Human Input node. type: string node_title: description: Title of the Human Input node. type: string rendered_content: description: Rendered content of the form submission. type: string type: object UserAction: description: An action button on a human input form. properties: button_style: description: '`primary`, `default`, `accent`, or `ghost`.' type: string id: description: Unique action identifier. type: string title: description: Button display text. type: string type: object FormInput: description: A form input field definition. properties: default: $ref: '#/components/schemas/FormInputDefault' description: Default value configuration for this input. nullable: true output_variable_name: description: Variable name where the input value is stored. type: string type: description: >- Form input control type. Available values: `paragraph` (multi-line text input), `select` (single-choice from a list), `file` (single file upload), and `file-list` (multiple file uploads). type: string type: object FormInputDefault: description: Default value configuration for a form input. properties: selector: description: Variable selector path when `type` is `variable`. items: type: string type: array type: description: >- `variable` for dynamic values from workflow variables, `constant` for static values. type: string value: description: Static value when `type` is `constant`. type: string type: object securitySchemes: ApiKeyAuth: 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/api-reference/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`). scheme: bearer type: http ````