GET /api/v1/chats/{id}

Returns one conversation, in the same shape the list uses, with its messages oldest first. Requires the read:chat scope (or * for full access).

Request

GET /api/v1/chats/cmq5chat0alk34567890 HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Query parameters

Parameter	Required	Description
`after`	No	A message ID you already have. Only messages after it are returned
`limit`	No	Maximum messages to return, 1 to 500. Default 500

Response: 200

{
  "chat": {
    "id": "cmq5chat0alk34567890",
    "status": "OPEN",
    "handler": "HUMAN",
    "handlerUser": { "id": "cmq1user0alk34567890", "name": "Kevin Rep" },
    "assignee": { "id": "cmq1user0alk34567890", "name": "Kevin Rep" },
    "subject": "Do you ship to Canada?"
  },
  "messages": [
    {
      "id": "cmq6msg00alk34567890",
      "role": "VISITOR",
      "userId": null,
      "userName": null,
      "body": "Do you ship to Canada?",
      "createdAt": "2026-09-27T14:02:00.000Z"
    },
    {
      "id": "cmq6msg01alk34567890",
      "role": "SYSTEM",
      "userId": null,
      "userName": null,
      "body": "Kevin joined the conversation",
      "createdAt": "2026-09-27T14:03:09.000Z"
    },
    {
      "id": "cmq6msg02alk34567890",
      "role": "USER",
      "userId": "cmq1user0alk34567890",
      "userName": "Kevin Rep",
      "body": "Yes, we ship to Canada. Most orders arrive in 3 to 5 business days.",
      "createdAt": "2026-09-27T14:03:10.000Z"
    }
  ],
  "messagesNextCursor": null
}

The chat object above is shortened. The full field list is on The Chat object.

Polling a live conversation

Keep the id of the last message you have and pass it as after. Only newer messages come back, so a poll every few seconds stays cheap:

curl -s "https://agentlyleads.com/api/v1/chats/cmq5chat0alk34567890?after=cmq6msg02alk34567890" \
  -H "Authorization: Bearer $AL_KEY"

When nothing new has been written, messages is empty.

Long transcripts

If a conversation has more messages than limit, messagesNextCursor is set to the last message's ID. Pass it as after to get the rest.

Response: 404

An ID that belongs to another workspace returns the same 404 as one that does not exist:

{ "error": "Conversation not found." }