GET /thread
Updated Oct 1, 20261 minute read
Get the thread
A session's conversation history: up to 200 messages across its 10 most recently started conversations, oldest first. The most recently active conversations fill the 200 first.
A session that has never written returns conversationId: null, status: null, and an empty messages array, not an error. Messages can span several conversations. A resolved thread stays in the history and the next message starts a new one, so draw a divider where conversationId changes. Internal notes and system lines are never included.
Part of Conversations.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
session | query | string | Yes | The visitor's session token, 8 to 128 characters. |
Responses
| Status | Description |
|---|---|
200 | The thread, newest message last. |
400 | invalid_request: the session query parameter is missing. invalid_session: the session is not 8 to 128 characters. |
401 | missing_api_key: no bearer token. invalid_api_key: the key matches no organization or was revoked. publishable_key: a median_pk_ key was sent. An OAuth access token is refused here with invalid_api_key. |
429 | The organization's API allowance for this class of request is used up. Wait the Retry-After header's seconds. Limits depend on the plan. See rate limits. |
200 body
| Field | Type | Required | Description |
|---|---|---|---|
conversationId | any | Yes | Null for a session that has never written. |
status | "open" | "resolved" | null | Yes | resolved once the conversation is resolved or closed. |
awaitingHuman | boolean | Yes | True while the next reply will come from a person. |
messages | object[] | Yes | |
messages[].id | string | Yes | |
messages[].conversationId | string | Yes | |
messages[].createdAt | integer | Yes | Milliseconds since the epoch. |
messages[].sender | "visitor" | "agent" | Yes | agent covers both the AI and your team; agent.kind says which. |
messages[].agent | object | null | Yes | Null on a visitor's own message. |
messages[].body | string | Yes | |
messages[].pending | boolean | Yes | A reply still being written. It updates in place, keeping its id. |
messages[].attachments | object[] | Yes | |
messages[].attachments[].name | string | Yes | |
messages[].attachments[].size | integer | Yes | |
messages[].attachments[].type | string | Yes | |
messages[].attachments[].url | any | Yes | Where to download it. |
Example response
{
"conversationId": "js7...",
"status": "open",
"awaitingHuman": false,
"messages": [
{
"id": "jd2...",
"conversationId": "js7...",
"createdAt": 1754990000000,
"sender": "visitor",
"agent": null,
"body": "How do I export my data?",
"pending": false,
"attachments": []
},
{
"id": "jd3...",
"conversationId": "js7...",
"createdAt": 1754990004000,
"sender": "agent",
"agent": {
"kind": "ai",
"name": "Median AI",
"avatarUrl": null
},
"body": "Settings, then Export. It arrives as a zip.",
"pending": false,
"attachments": []
}
]
}Example request
curl https://api.median.sh/v1/thread?session=user_42 \
-H "Authorization: Bearer $MEDIAN_KEY"