API Reference

Conversations

Items

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List items

$ openai conversations:items list

GET/conversations/{conversation_id}/items

List all items for a conversation with the given ID.

ParametersExpand Collapse

--conversation-id: string

The ID of the conversation to list items for.

--after: optional string

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

--include: optional array of 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 number

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

--order: optional "asc" or "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

conversation_item_list: object { data, first_id, has_more, 2 more }

A list of Conversation items.

data: array of ConversationItem

A list of conversation items.

first_id: string

The ID of the first item in the list.

has_more: boolean

Whether there are more items available.

last_id: string

The ID of the last item in the list.

object: "list"

The type of object returned, must be list.

List items

CLI Tool

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

openai conversations:items list \
  --api-key 'My API Key' \
  --conversation-id conv_123

{
  "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
}