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 Voice & Audio Production API reference
API Dashboard
Try ChatGPT
API Reference
Conversations
Items

List items

conversations.items.list(strconversation_id, ItemListParams**kwargs) -> SyncConversationCursorPage[ConversationItem]
GET/conversations/{conversation_id}/items

List all items for a conversation with the given ID.

ParametersExpand Collapse
conversation_id: str
after: Optional[str]

An item ID to list items after, used in pagination.

include: Optional[List[ResponseIncludable]]

Specify additional output data to include in the model response. Currently supported values are:

  • web_search_call.action.sources: Include the sources of the web search tool call.
  • code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items.
  • computer_call_output.output.image_url: Include image urls from the computer call output.
  • file_search_call.results: Include the search results of the file search tool call.
  • message.input_image.image_url: Include image urls from the input message.
  • message.output_text.logprobs: Include logprobs with assistant messages.
  • reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program).
limit: Optional[int]

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

order: Optional[Literal["asc", "desc"]]

The order to return the input items in. Default is desc.

  • asc: Return the input items in ascending order.
  • desc: Return the input items in descending order.
ReturnsExpand Collapse
ConversationItem

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:
class Message: …

A message to or from the model.

class ResponseFunctionToolCallItem: …

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

class ResponseFunctionToolCallOutputItem: …
class ResponseFileSearchToolCall: …

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

class ImageGenerationCall: …

An image generation request made by the model.

class ResponseComputerToolCall: …

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

class ResponseComputerToolCallOutputItem: …
class ResponseToolSearchCall: …
class ResponseToolSearchOutputItem: …
class AdditionalTools: …
class ResponseReasoningItem: …

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.

class Program: …
class ProgramOutput: …
class ResponseCompactionItem: …

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

class ResponseCodeInterpreterToolCall: …

A tool call to run code.

class LocalShellCall: …

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

class LocalShellCallOutput: …

The output of a local shell tool call.

class ResponseFunctionShellToolCall: …

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

class ResponseFunctionShellToolCallOutput: …

The output of a shell tool call that was emitted.

class ResponseApplyPatchToolCall: …

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

class ResponseApplyPatchToolCallOutput: …

The output emitted by an apply patch tool call.

class McpListTools: …

A list of tools available on an MCP server.

class McpApprovalRequest: …

A request for human approval of a tool invocation.

class McpApprovalResponse: …

A response to an MCP approval request.

class McpCall: …

An invocation of a tool on an MCP server.

class ResponseCustomToolCall: …

A call to a custom tool created by the model.

class ResponseCustomToolCallOutput: …

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

List items

from openai import OpenAI
client = OpenAI()

items = client.conversations.items.list("conv_123", limit=10)
print(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
}