conversations.list()

Read one customer’s conversation with an assistant.

const thread = await concatflow.conversations.list({
  assistantId: process.env.CONCATFLOW_ASSISTANT_ID!,
  partition: { customer_id: "4712" },
});

Parameters

assistantId · string · required

The assistant’s ID.

partition · Record<string, string | number> · required

The customer’s partition, as sent to sessions.create. Keys and values must not contain , or =.

Returns a Thread

A customer with no conversation returns an empty thread, not an error.

partition · Record<string, string>

The partition you asked for.

since · string | null

ISO 8601 timestamp of the conversation’s start. null when there is none.

launcher · "bubble" | "bar" | null

The launcher set on the assistant in the dashboard.

questions · number

Number of questions asked.

credits_cents · number

Total cost, in hundredths of a credit. 100 is one credit.

messages · ThreadMessage[]

Questions and answers, oldest first. Each question is followed by its answer.

Show ThreadMessage

id · string

Stable ID of the message.

role · "user" | "assistant"

user for the customer’s question, assistant for the answer.

text · string

The question, or the written answer.

at · string

ISO 8601 timestamp.

credits_cents · number | null

Cost of the answer. null on questions.

blocks · ThreadBlock[]

What the answer displayed: tables, metrics, charts, interfaces. Empty on questions.

Show ThreadBlock

id · string

Block ID.

kind · string

table, metric, chart, or openui for an interface (list, map, detail card).

title · string

The block’s title.

spec · Record<string, unknown>

What the block shows. Its shape depends on kind.

Example

{
  "partition": { "customer_id": "4712" },
  "since": "2026-10-02T09:14:03.112000+00:00",
  "launcher": "bar",
  "questions": 1,
  "credits_cents": 12,
  "messages": [
    { "id": "…:q", "role": "user", "text": "Which invoices are still unpaid?", "at": "2026-10-02T09:14:03.112000+00:00", "credits_cents": null, "blocks": [] },
    { "id": "…:a", "role": "assistant", "text": "You have two unpaid invoices.", "at": "2026-10-02T09:14:03.112000+00:00", "credits_cents": 12, "blocks": [] }
  ]
}

Errors

401 invalid_api_key, 404 for an unknown assistant, 422 bad_partition for an unreadable partition. See Errors.