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.
1 min read
get/messages
Request example
curl --request GET \
--url https://api.dify.ai/v1/messages \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.dify.ai/v1/messages"
headers = {
"Authorization": "Bearer <token>",
}
response = requests.request("GET", url, headers=headers)
print(response.text)const response = await fetch('https://api.dify.ai/v1/messages', {
method: 'GET',
headers: {
'Authorization': 'Bearer <token>'
}
});
const data = await response.json();
console.log(data);<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://api.dify.ai/v1/messages',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer <token>',
],
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;package main
import (
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.dify.ai/v1/messages"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.dify.ai/v1/messages"))
.header("Authorization", "Bearer <token>")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());require 'uri'
require 'net/http'
url = URI('https://api.dify.ai/v1/messages')
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'
request = Net::HTTP::Get.new(url)
request['Authorization'] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyResponse
{
"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
}{
"code": "not_chat_app",
"message": "Please check if your app mode matches the right API route.",
"status": 400
}{
"code": "not_found",
"message": "Conversation Not Exists.",
"status": 404
}{
"code": "not_found",
"message": "First Message Not Exists.",
"status": 404
}get/messages
Authorization
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).
Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).
Query parameters
ID of the conversation to read. Get conversation IDs from List Conversations.
End-user identifier, defined by your app and unique within it. See End User Identity.
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.Responses
application/json
Successfully retrieved conversation history.
List of messages.
Show child attributesHide child attributes
Agent thoughts for this message.
Show child attributesHide child attributes
Chain ID for this thought.
Creation timestamp.
File IDs related to this thought.
Agent thought ID.
Unique message ID this thought belongs to.
Response from tool calls.
Position of this thought.
What LLM is thinking.
Tools called, split by
;.Input of tools in JSON format.
Labels for tools used.
Assistant answer text.
Number of tokens in the generated answer.
Conversation ID.
Creation timestamp (Unix epoch seconds).
Currency for
total_price (for example, USD), or null when pricing is unavailable.Error message if
status is error.Additional execution content associated with this message, such as human input form data from Human Input nodes in Chatflow workflows.
Show child attributesHide child attributes
Definition of a human input form rendered by a Human Input node.
Show child attributesHide child attributes
Action buttons available on the form.
Whether the form should be displayed in the UI.
Unix timestamp when the form expires.
Markdown or text content displayed with the form.
Unique form identifier.
Token for form submission authentication.
Input fields in the form.
Show child attributesHide child attributes
Default value configuration for a form input.
Variable name where the input value is stored.
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).ID of the Human Input node that generated this form.
Title of the Human Input node.
Resolved default values for form inputs, keyed by output variable name.
Data from a submitted human input form.
Show child attributesHide child attributes
Whether the human input form has been submitted.
human_input for human input content.ID of the workflow run this content belongs to.
User feedback for this message.
Show child attributesHide child attributes
Feedback rating.
like for positive, dislike for negative.Message ID.
Input variables for this message.
Files attached to this message.
Show child attributesHide child attributes
Who this file belongs to.
user for user-uploaded files, assistant for assistant-generated files.Original filename.
File ID.
MIME type of the file.
File size in bytes.
Transfer method used.
remote_url for URL-based files, local_file for uploaded files, tool_file for tool-generated files.File type, e.g.,
image.Upload file ID if transferred via
local_file.Preview URL for the file.
Number of tokens in the input message.
Parent message ID for threaded conversations.
Model provider response latency in seconds.
User query text.
Retriever resources used for this message.
Show child attributesHide child attributes
Content snippet from the resource.
Creation timestamp (Unix epoch seconds).
Type of the data source.
ID of the knowledge base.
Name of the knowledge base.
ID of the document.
Name of the document.
Number of times this chunk was hit.
Unique ID of the retriever resource.
Hash of the index node.
ID of the message this resource belongs to.
Position of the resource in the list.
Similarity score of the resource.
ID of the specific chunk within the document.
Position of the chunk within the document.
Summary of the chunk content.
Word count of the chunk.
Message status.
normal for successful messages, error when generation failed.Total price for the tokens used, or
null when pricing is unavailable.Total tokens used, the sum of
message_tokens and answer_tokens.Whether there are more messages.
Number of items per page.