Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

List items

client.conversations.items.list(conversationID, query?, options?): ConversationCursorPage<ConversationItem>
GET
/conversations/{conversation_id}/items

List all items for a conversation with the given ID.

Parameters
conversationID: string
query: ItemListParams { after, include, limit, order }
Returns
ConversationItem = Message { id, content, role, 3 more } | ResponseFunctionToolCallItem { id, status, created_by } | ResponseFunctionToolCallOutputItem { id, output, status, 6 more } | 26 more

A single item within a conversation. The set of possible types are the same as the output type of a Response object.

One of the following:
Message { id, content, role, 3 more }

A message to or from the model.

ResponseFunctionToolCallItem extends ResponseFunctionToolCall { arguments, call_id, name, 6 more } { id, status, created_by }

A tool call to run a function. See the function calling guide for more information.

ResponseFunctionToolCallOutputItem { id, output, status, 6 more }
ResponseFileSearchToolCall { id, queries, status, 2 more }

The results of a file search tool call. See the file search guide for more information.

ResponseFunctionWebSearch { id, action, status, type }

The results of a web search tool call. See the web search guide for more information.

ImageGenerationCall { id, result, status, 8 more }

An image generation request made by the model.

ResponseComputerToolCall { id, call_id, pending_safety_checks, 4 more }

A tool call to a computer use tool. See the computer use guide for more information.

ResponseComputerToolCallOutputItem { id, call_id, output, 4 more }
ResponseToolSearchCall { id, arguments, call_id, 4 more }
ResponseToolSearchOutputItem { id, call_id, execution, 4 more }
AdditionalTools { id, role, tools, type }
ResponseConfigurationUpdateItem { id, type, reasoning }

A configuration update that applies to subsequent responses until it is replaced by another configuration update.

ResponseReasoningItem { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

Program { id, call_id, code, 2 more }
ProgramOutput { id, call_id, result, 2 more }
ResponseCompactionItem { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

ResponseCodeInterpreterToolCall { id, code, container_id, 3 more }

A tool call to run code.

LocalShellCall { id, action, call_id, 2 more }

A tool call to run a command on the local shell.

LocalShellCallOutput { id, output, type, status }

The output of a local shell tool call.

ResponseFunctionShellToolCall { id, action, call_id, 5 more }

A tool call that executes one or more shell commands in a managed environment.

ResponseFunctionShellToolCallOutput { id, call_id, max_output_length, 5 more }

The output of a shell tool call that was emitted.

ResponseApplyPatchToolCall { id, call_id, operation, 4 more }

A tool call that applies file diffs by creating, deleting, or updating files.

ResponseApplyPatchToolCallOutput { id, call_id, status, 4 more }

The output emitted by an apply patch tool call.

McpListTools { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

McpApprovalRequest { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

McpApprovalResponse { id, approval_request_id, approve, 2 more }

A response to an MCP approval request.

McpCall { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

ResponseCustomToolCall { call_id, input, name, 5 more }

A call to a custom tool created by the model.

ResponseCustomToolCallOutput { call_id, output, type, 2 more }

The output of a custom tool call from your code, being sent back to the model.

List items

import OpenAI from "openai";
const client = new OpenAI();

const items = await client.conversations.items.list("conv_123", { limit: 10 });
console.log(items.data);

{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Hello!"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_abc",
  "has_more": false
}
Returns Examples
{
  "object": "list",
  "data": [
    {
      "type": "message",
      "id": "msg_abc",
      "status": "completed",
      "role": "user",
      "content": [
        {"type": "input_text", "text": "Hello!"}
      ]
    }
  ],
  "first_id": "msg_abc",
  "last_id": "msg_abc",
  "has_more": false
}