Conversation API
Endpoint and SDK reference for stateful multi-turn conversations.
Conversations keep memory across messages using a conversation_id. Keep that ID if you want to continue the same thread later.
content in conversation endpoints uses the same MessageContent[] schema as Runner API.
See Runner API — content body structure and Multimodal.
SDK surface
conversation.start(conversationId?, deploymentId?)
const conversation = client.conversationconversation.start() // new local contextconversation.start("conv_existing_123") // resume existing conversationstart(...) sets active conversation context (conversation.id + deploymentId) and clears local conversation state.
Use start("conv_...") to resume a saved conversation.
Do not switch deployment in the middle of a thread and expect the same conversation continuity.
For most apps, if you need a different deployment, initialize a new client with that deployment id.
The second deploymentId argument is an advanced option and is rarely needed.
conversation.run(options) / conversation.stream(options)
await conversation.run({content: [{ type: "text", text: "Hello" }],variables: { CUSTOMER_TIER: "pro" }, // first message onlymeta: { userId: "user_123" }, // first message onlyhistoryLimit: 10, // continuation only})| Option | Type | Required | Notes |
|---|---|---|---|
content | MessageContent[] | Yes | Must be non-empty |
variables | object | No | First message only |
meta | object | No | First message only |
historyLimit | number | No | Continuation only |
signal | AbortSignal | No | Cancel in-flight request |
conversation.loadMessages(options)
await conversation.loadMessages() // uses active conversation.idawait conversation.loadMessages({conversationId: "conv_existing_123",page: 1,pageSize: 20,append: true,})| Option | Type | Required | Notes |
|---|---|---|---|
conversationId | string | No | Uses active conversation.id if omitted |
page | number | No | Defaults to API default |
pageSize | number | No | Defaults to API default |
append | boolean | No | Merge into existing conversation.messages and dedupe by message id |
conversation.list(options)
await conversation.list({page: 1,pageSize: 20,meta: { userId: "user_123", channel: "web-chat" },})| Option | Type | Required |
|---|---|---|
page | number | No |
pageSize | number | No |
meta | object | No |
conversation.abort() aborts any in-flight conversation.run(...) or conversation.stream(...) call.
State fields exposed by client.conversation:
id,deploymentId,status,data,live,error,meta,rawmessages,messagesPageInfo,conversations,conversationsPageInfo
React surface
Error notes
contentmust be a non-empty array.variablesandmetaare rejected on continuation calls.- See Errors reference for status and SDK error mapping.