0
# Conversations
1

2
Manage persistent conversation state independently of threads. The Conversations API provides a stateful conversation interface where messages and tool calls are stored as items, enabling complex multi-turn interactions with full history management.
3

4
## Capabilities
5

6
### Conversation Management
7

8
Create and manage conversations with persistent state.
9

10
```typescript { .api }
11
/**
12
 * Create a new conversation
13
 * @param params - Conversation creation parameters
14
 * @returns Conversation object with unique identifier
15
 */
16
function create(
17
  params?: ConversationCreateParams
18
): Promise<Conversation>;
19

20
/**
21
 * Retrieve conversation information
22
 * @param conversationID - Unique identifier for the conversation
23
 * @returns Conversation object with metadata
24
 */
25
function retrieve(conversationID: string): Promise<Conversation>;
26

27
/**
28
 * Update conversation metadata
29
 * @param conversationID - Unique identifier for the conversation
30
 * @param params - Update parameters including metadata
31
 * @returns Updated conversation object
32
 */
33
function update(
34
  conversationID: string,
35
  params: ConversationUpdateParams
36
): Promise<Conversation>;
37

38
/**
39
 * Delete a conversation (items in the conversation will not be deleted)
40
 * @param conversationID - Unique identifier for the conversation
41
 * @returns Deletion confirmation
42
 */
43
function delete(conversationID: string): Promise<ConversationDeletedResource>;
44

45
interface ConversationCreateParams {
46
  /** Initial items to include in the conversation context (up to 20 items) */
47
  items?: Array<ResponseInputItem> | null;
48
  /** Set of 16 key-value pairs for storing additional information */
49
  metadata?: Metadata | null;
50
}
51

52
interface ConversationUpdateParams {
53
  /** Set of 16 key-value pairs for storing additional information */
54
  metadata: Metadata | null;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import OpenAI from "openai";
62

63
const client = new OpenAI();
64

65
// Create a new conversation
66
const conversation = await client.conversations.create({
67
  metadata: {
68
    user_id: "user_123",
69
    session: "chat_session_1",
70
  },
71
});
72

73
console.log(`Conversation created: ${conversation.id}`);
74

75
// Retrieve conversation details
76
const retrieved = await client.conversations.retrieve(conversation.id);
77
console.log(`Created at: ${new Date(retrieved.created_at * 1000)}`);
78

79
// Update conversation metadata
80
const updated = await client.conversations.update(conversation.id, {
81
  metadata: {
82
    user_id: "user_123",
83
    session: "chat_session_1",
84
    status: "active",
85
  },
86
});
87

88
// Delete a conversation
89
const result = await client.conversations.delete(conversation.id);
90
console.log(`Conversation deleted: ${result.deleted}`);
91
```
92

93
### Item Management
94

95
Manage individual items (messages, tool calls, etc.) within conversations.
96

97
```typescript { .api }
98
/**
99
 * Create items in a conversation
100
 * @param conversationID - Unique identifier for the conversation
101
 * @param params - Item creation parameters
102
 * @returns List of created items
103
 */
104
function conversations.items.create(
105
  conversationID: string,
106
  params: ItemCreateParams
107
): Promise<ConversationItemList>;
108

109
/**
110
 * Retrieve a single item from a conversation
111
 * @param itemID - Unique identifier for the item
112
 * @param params - Parameters including conversation_id
113
 * @returns Conversation item object
114
 */
115
function conversations.items.retrieve(
116
  itemID: string,
117
  params: ItemRetrieveParams
118
): Promise<ConversationItem>;
119

120
/**
121
 * List all items for a conversation
122
 * @param conversationID - Unique identifier for the conversation
123
 * @param params - List parameters for pagination and filtering
124
 * @returns Paginated list of conversation items
125
 */
126
function conversations.items.list(
127
  conversationID: string,
128
  params?: ItemListParams
129
): Promise<ConversationItemsPage>;
130

131
/**
132
 * Delete an item from a conversation
133
 * @param itemID - Unique identifier for the item
134
 * @param params - Parameters including conversation_id
135
 * @returns Updated conversation object
136
 */
137
function conversations.items.delete(
138
  itemID: string,
139
  params: ItemDeleteParams
140
): Promise<Conversation>;
141

142
interface ItemCreateParams {
143
  /** The items to add to the conversation (up to 20 items at a time) */
144
  items: Array<ResponseInputItem>;
145
  /** Additional fields to include in the response */
146
  include?: Array<ResponseIncludable>;
147
}
148

149
interface ItemRetrieveParams {
150
  /** The ID of the conversation that contains the item */
151
  conversation_id: string;
152
  /** Additional fields to include in the response */
153
  include?: Array<ResponseIncludable>;
154
}
155

156
interface ItemListParams {
157
  /** Additional output data to include in the response */
158
  include?: Array<ResponseIncludable>;
159
  /** The order to return items in ('asc' or 'desc', default 'desc') */
160
  order?: "asc" | "desc";
161
  /** Maximum number of items to return */
162
  limit?: number;
163
  /** Cursor for fetching the next page of results */
164
  after?: string;
165
  /** Cursor for fetching the previous page of results */
166
  before?: string;
167
}
168

169
interface ItemDeleteParams {
170
  /** The ID of the conversation that contains the item */
171
  conversation_id: string;
172
}
173
```
174

175
**Usage Examples:**
176

177
```typescript
178
// Create conversation items (messages)
179
const items = await client.conversations.items.create(conversation.id, {
180
  items: [
181
    {
182
      type: "message",
183
      role: "user",
184
      content: [
185
        {
186
          type: "input_text",
187
          text: "Hello! Can you help me with Python?",
188
        },
189
      ],
190
    },
191
  ],
192
});
193

194
console.log(`Added ${items.data.length} items`);
195

196
// Retrieve a specific item
197
const item = await client.conversations.items.retrieve(items.data[0].id, {
198
  conversation_id: conversation.id,
199
});
200

201
// List all items in the conversation
202
for await (const item of client.conversations.items.list(conversation.id, {
203
  order: "asc",
204
  include: ["message.output_text.logprobs"],
205
})) {
206
  if (item.type === "message") {
207
    console.log(`${item.role}: ${JSON.stringify(item.content)}`);
208
  }
209
}
210

211
// Delete an item
212
await client.conversations.items.delete(items.data[0].id, {
213
  conversation_id: conversation.id,
214
});
215
```
216

217
## Types
218

219
### Conversation
220

221
```typescript { .api }
222
interface Conversation {
223
  /** The unique ID of the conversation */
224
  id: string;
225
  /** Unix timestamp (seconds) when the conversation was created */
226
  created_at: number;
227
  /** Key-value pairs attached to the conversation (max 16 pairs) */
228
  metadata: unknown;
229
  /** The object type, which is always 'conversation' */
230
  object: "conversation";
231
}
232

233
interface ConversationDeletedResource {
234
  id: string;
235
  deleted: boolean;
236
  object: "conversation.deleted";
237
}
238
```
239

240
### Conversation Items
241

242
Conversation items can be various types including messages, tool calls, and their outputs:
243

244
```typescript { .api }
245
/** Union type representing all possible conversation item types */
246
type ConversationItem =
247
  | Message
248
  | ResponseFunctionToolCallItem
249
  | ResponseFunctionToolCallOutputItem
250
  | ResponseFileSearchToolCall
251
  | ResponseFunctionWebSearch
252
  | ImageGenerationCall
253
  | ResponseComputerToolCall
254
  | ResponseComputerToolCallOutputItem
255
  | ResponseReasoningItem
256
  | ResponseCodeInterpreterToolCall
257
  | LocalShellCall
258
  | LocalShellCallOutput
259
  | ResponseFunctionShellToolCall
260
  | ResponseFunctionShellToolCallOutput
261
  | ResponseApplyPatchToolCall
262
  | ResponseApplyPatchToolCallOutput
263
  | McpListTools
264
  | McpApprovalRequest
265
  | McpApprovalResponse
266
  | McpCall
267
  | ResponseCustomToolCall
268
  | ResponseCustomToolCallOutput;
269
```
270

271
### Message
272

273
```typescript { .api }
274
interface Message {
275
  /** The unique ID of the message */
276
  id: string;
277
  /** The content of the message */
278
  content: Array<
279
    | ResponseInputText
280
    | ResponseOutputText
281
    | TextContent
282
    | SummaryTextContent
283
    | ReasoningText
284
    | ResponseOutputRefusal
285
    | ResponseInputImage
286
    | ComputerScreenshotContent
287
    | ResponseInputFile
288
  >;
289
  /** The role of the message */
290
  role:
291
    | "unknown"
292
    | "user"
293
    | "assistant"
294
    | "system"
295
    | "critic"
296
    | "discriminator"
297
    | "developer"
298
    | "tool";
299
  /** The status of item */
300
  status: "in_progress" | "completed" | "incomplete";
301
  /** The type of the message, always 'message' */
302
  type: "message";
303
}
304
```
305

306
### Content Types
307

308
```typescript { .api }
309
interface TextContent {
310
  text: string;
311
  type: "text";
312
}
313

314
interface SummaryTextContent {
315
  /** A summary of the reasoning output from the model so far */
316
  text: string;
317
  /** The type of the object, always 'summary_text' */
318
  type: "summary_text";
319
}
320

321
interface ComputerScreenshotContent {
322
  /** The identifier of an uploaded file that contains the screenshot */
323
  file_id: string | null;
324
  /** The URL of the screenshot image */
325
  image_url: string | null;
326
  /** Specifies the event type, always 'computer_screenshot' */
327
  type: "computer_screenshot";
328
}
329
```
330

331
### Conversation Item List
332

333
```typescript { .api }
334
interface ConversationItemList {
335
  /** List of conversation items */
336
  data: Array<ConversationItem>;
337
  /** The ID of the first item in the list */
338
  first_id: string;
339
  /** Whether there are more items available */
340
  has_more: boolean;
341
  /** The ID of the last item in the list */
342
  last_id: string;
343
  /** The type of object returned, must be 'list' */
344
  object: "list";
345
}
346
```
347

348
### Includable Fields
349

350
The `include` parameter allows you to request additional data in responses:
351

352
- `web_search_call.action.sources` - Include sources of web search tool calls
353
- `web_search_call.results` - Include search results of web search tool calls
354
- `code_interpreter_call.outputs` - Include outputs of Python code execution
355
- `computer_call_output.output.image_url` - Include image URLs from computer calls
356
- `file_search_call.results` - Include search results of file search tool calls
357
- `message.input_image.image_url` - Include image URLs from input messages
358
- `message.output_text.logprobs` - Include log probabilities with assistant messages
359
- `reasoning.encrypted_content` - Include encrypted reasoning tokens for stateless usage
360

361
## Complete Workflow Example
362

363
```typescript
364
import OpenAI from "openai";
365

366
const client = new OpenAI();
367

368
async function conversationWorkflow() {
369
  // 1. Create a conversation with initial metadata
370
  const conversation = await client.conversations.create({
371
    metadata: {
372
      user_id: "user_789",
373
      topic: "python_help",
374
      priority: "high",
375
    },
376
  });
377

378
  console.log(`Conversation started: ${conversation.id}`);
379

380
  // 2. Add user message
381
  const userMessage = await client.conversations.items.create(conversation.id, {
382
    items: [
383
      {
384
        type: "message",
385
        role: "user",
386
        content: [
387
          {
388
            type: "input_text",
389
            text: "Can you explain list comprehensions in Python?",
390
          },
391
        ],
392
      },
393
    ],
394
  });
395

396
  // 3. Get model response using Responses API
397
  const response = await client.responses.create({
398
    model: "gpt-4",
399
    conversation_id: conversation.id,
400
    input: [
401
      {
402
        type: "message",
403
        role: "user",
404
        content: [
405
          {
406
            type: "input_text",
407
            text: "Can you explain list comprehensions in Python?",
408
          },
409
        ],
410
      },
411
    ],
412
  });
413

414
  // 4. List all conversation items
415
  console.log("\nConversation history:");
416
  for await (const item of client.conversations.items.list(conversation.id, {
417
    order: "asc",
418
  })) {
419
    if (item.type === "message") {
420
      const textContent = item.content.find((c) => c.type === "output_text");
421
      if (textContent && "text" in textContent) {
422
        console.log(`${item.role}: ${textContent.text.substring(0, 100)}...`);
423
      }
424
    }
425
  }
426

427
  // 5. Update conversation metadata
428
  await client.conversations.update(conversation.id, {
429
    metadata: {
430
      user_id: "user_789",
431
      topic: "python_help",
432
      priority: "high",
433
      resolved: "true",
434
      resolved_at: new Date().toISOString(),
435
    },
436
  });
437

438
  // 6. Retrieve specific items
439
  const firstItem = userMessage.data[0];
440
  const retrievedItem = await client.conversations.items.retrieve(
441
    firstItem.id,
442
    {
443
      conversation_id: conversation.id,
444
      include: ["message.output_text.logprobs"],
445
    }
446
  );
447

448
  console.log(`\nRetrieved item: ${retrievedItem.type}`);
449

450
  // 7. Clean up (optional)
451
  // Note: Deleting a conversation doesn't delete its items
452
  const deleted = await client.conversations.delete(conversation.id);
453
  console.log(`\nConversation deleted: ${deleted.deleted}`);
454

455
  return conversation;
456
}
457

458
conversationWorkflow();
459
```
460

461
## Integration with Responses API
462

463
Conversations are closely integrated with the Responses API:
464

465
```typescript
466
// Create conversation
467
const conversation = await client.conversations.create();
468

469
// Use conversation_id in Responses API
470
const response = await client.responses.create({
471
  model: "gpt-4",
472
  conversation_id: conversation.id,
473
  input: [
474
    {
475
      type: "message",
476
      role: "user",
477
      content: [{ type: "input_text", text: "Hello!" }],
478
    },
479
  ],
480
});
481

482
// Items are automatically added to the conversation
483
const items = await client.conversations.items.list(conversation.id);
484
console.log(`Conversation now has ${items.data.length} items`);
485
```
486

487
## Notes
488

489
- Conversations provide persistent state for multi-turn interactions
490
- Items include messages, tool calls, and their outputs
491
- Deleting a conversation does not delete its items
492
- Metadata supports up to 16 key-value pairs per conversation
493
- Keys max 64 characters, values max 512 characters
494
- Items can be added in batches of up to 20 at a time
495
- The `include` parameter allows requesting additional data like log probabilities
496
- Conversations integrate seamlessly with the Responses API for stateful interactions
497
- Computer screenshot content supports both file IDs and image URLs
498
- Items are ordered by creation time, with `order` parameter controlling sort direction
499