Skip to content
Median
Esc
↑↓navigate↵open⌘Jpreview

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.

GET/thread
Authorization
AuthorizationBearer token · headerrequired
A MEDIAN_KEY from Settings under API. It starts with `median_key_` and stays on your server. The tool endpoint routes also accept an OAuth access token (`median_oat_`) from `median login` or an MCP client, acting as the person who approved it. The messaging routes accept only a Median key.
Query parameters
sessionstringrequired
The visitor's session token, 8 to 128 characters.
min length 8 · max length 128
Responses
200The thread, newest message last.
conversationIdstring | nullrequired
Null for a session that has never written.
statusstring | nullrequired
`resolved` once the conversation is resolved or closed.
Allowed:openresolvednull
awaitingHumanbooleanrequired
True while the next reply will come from a person.
messagesMessage[]required
Show properties
Array of Message
idstringrequired
conversationIdstringrequired
createdAtintegerrequired
Milliseconds since the epoch.
senderstringrequired
`agent` covers both the AI and your team; `agent.kind` says which.
Allowed:visitoragent
agentAgent | anyrequired
Null on a visitor's own message.
Show properties
One of:
Agent
kindstringrequired
Allowed:aihuman
namestringrequired
avatarUrlstring | nullrequired
any
any
bodystringrequired
pendingbooleanrequired
A reply still being written. It updates in place, keeping its id.
attachmentsAttachment[]required
Show properties
Array of Attachment
namestringrequired
sizeintegerrequired
typestringrequired
urlstring | nullrequired
Where to download it.
400`invalid_request`: the `session` query parameter is missing. `invalid_session`: the session is not 8 to 128 characters.
errorobjectrequired
Show properties
codestringrequired
Branch on this rather than on the message.
messagestringrequired
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`.
errorobjectrequired
Show properties
codestringrequired
Branch on this rather than on the message.
messagestringrequired
429The 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](/api/errors-and-limits#rate-limits).
errorobjectrequired
Show properties
codestringrequired
Branch on this rather than on the message.
messagestringrequired
Request
curl -X GET "https://api.median.sh/v1/thread?session=user_42" \
  -H "Authorization: Bearer YOUR_TOKEN"
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": []
    }
  ]
}