Conversations
Export conversations
Export conversation metadata and public transcript text with your platform API key.
/v2/agents//conversations/exportAuthenticate with the platform API key and put agent_id in the URL path.
Export behavior
Each item represents one thread. It preserves the information in the dashboard CSV and organizes related values into JSON objects. thread_id identifies the row; conversation_id identifies its parent conversation. Separate threads remain separate rows.
The response includes customer threads across API, widget, standalone and connected messaging channels, including groups and inactive or historical channels. Playground data, deleted resources, private notes, system events and replies still generating are excluded.
Response structure
| Field | Contents |
|---|---|
channel | id, type, name |
contact | id, identifier, name, email, phone_number |
assignee | Assigned teammate's id and name |
csat | Customer's rating and comment |
topics | Array of objects with id and title |
messages | Array of messages with id, role, content_text, created_at |
Contact fields come from the profile recorded in that channel, matching CSV. A contact's global profile can differ. Missing or inaccessible contacts, unassigned teammates and unanswered CSAT are null; a known contact with an incomplete profile retains its id and has null for unavailable fields. No topics gives []. Counts and ratings are numbers; timestamps are UTC ISO 8601.
The CSV remains flat. For example, its channel_name maps to channel.name, contact_email to contact.email, and csat_comment to csat.comment. topics preserves each title separately, including punctuation. CSV cell escaping and semicolon joining do not apply to JSON.
Filter conversations
Use thread_id for one CSV row, conversation_id for the threads of one parent conversation, channel_id for one channel, or contact_identifier for the identifier recorded in that channel. Filters combine. An inaccessible thread, conversation or channel returns an empty list; an inaccessible agent returns 404.
start_date is inclusive and end_date is exclusive. Both require ISO 8601 date-times with a timezone, for example 2026-10-01T00:00:00Z through 2026-11-01T00:00:00Z for October. They filter thread creation time, matching the CSV row. Date-only or timezone-free values are rejected.
Message text
include=messages is the default. Each message contains only id, role (user, assistant, operator), content_text and created_at. Messages belong to the row's thread and are ordered oldest first. Stored captions or transcripts are included when available; a message without text has an empty content_text. Attachments, parts and internal model/tool metadata are not exported.
Use include=summary for CSV metadata without message bodies. The summary field always means the thread's stored summary; the include option only controls whether messages are fetched.
Pagination and limits
Each page returns up to 20 complete threads. Every thread includes all its eligible public messages in one messages array. Set limit to request fewer threads. The endpoint allows 30 requests per minute per organization; use Retry-After to retry a 429 response.
Without query parameters, you receive the 20 newest threads with include=messages. Threads are sorted by created_at DESC, then by internal ID descending. Each thread's messages remain oldest first. The next page contains older threads; recent activity does not change a thread's position.
Follow pagination.next_cursor until has_more is false to retrieve the remaining threads. Each thread and its messages arrive together; no transcript merging is needed. See Pagination for ordering and consistency.
Complete Python export
Install requests and set MUCHAT_PLATFORM_API_KEY and MUCHAT_AGENT_ID. The example writes one complete thread as JSON per line and retries temporary rate limits. Run python export.py > conversations.jsonl to save the export without keeping every page in memory.
import json
import os
import time
from urllib.parse import quote
import requests
agent_id = quote(os.environ["MUCHAT_AGENT_ID"], safe="")
url = f"https://api.mu.chat/v2/agents/{agent_id}/conversations/export"
params = {"limit": 20}
headers = {"Authorization": f"Bearer {os.environ['MUCHAT_PLATFORM_API_KEY']}"}
retry_count = 0
while True:
response = requests.get(url, params=params, headers=headers, timeout=60)
if response.status_code in (429, 503) and retry_count < 5:
time.sleep(int(response.headers.get("Retry-After", "5")))
retry_count += 1
continue
response.raise_for_status()
retry_count = 0
page = response.json()
for thread in page["data"]:
print(json.dumps(thread, ensure_ascii=False))
if not page["pagination"]["has_more"]:
break
params["cursor"] = page["pagination"]["next_cursor"]Authentication
AuthorizationstringheaderrequiredAuthenticate with a Bearer token in this format: Bearer <token>
Path Parameters
agent_idstringrequiredYOUR_AGENT_IDQuery Parameters
channel_idstring | nulluuidconversation_idstring | nulluuidthread_idstring | nulluuidcontact_identifierstring | null255start_datestring | nulldate-timeend_datestring | nulldate-timecursorstring | null2048limitinteger20120includeenum<string>messagessummarymessagesResponse
dataobject[]requiredShow child attributes
thread_idstringrequireduuidconversation_idstringrequireduuidstatusenum<string>requiredopenpendingresolvedsnoozedcreated_atstringrequiredchannelobjectrequiredShow child attributes
idstringrequireduuidtypestringrequirednamestring | nullrequiredcontactobject | nullrequiredShow child attributes
idstringrequireduuididentifierstring | nullrequirednamestring | nullrequiredemailstring | nullrequiredphone_numberstring | nullrequiredassigneeobject | nullrequiredShow child attributes
idstringrequirednamestring | nullrequiredcsatobject | nullrequiredShow child attributes
ratingintegerrequiredcommentstring | nullrequiredtopicsobject[]requiredShow child attributes
idstringrequireduuidtitlestringrequiredcontact_message_countintegerrequiredsentimentstring | nullrequiredsummarystring | nullrequiredthread_urlstringrequiredmessagesobject[] | nullShow child attributes
idstringrequireduuidroleenum<string>requireduserassistantoperatorcontent_textstringrequiredcreated_atstringrequiredpaginationobjectrequiredShow child attributes
has_morebooleanrequirednext_cursorstring | nullrequiredsnapshot_atstringrequired