API Reference

Conversations

Items

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve an item

$ openai conversations:items retrieve

GET/conversations/{conversation_id}/items/{item_id}

Get a single item from a conversation with the given IDs.

ParametersExpand Collapse

--conversation-id: string

The ID of the conversation that contains the item.

--item-id: string

The ID of the item to retrieve.

--include: optional array of ResponseIncludable

Additional fields to include in the response. See the include parameter for listing Conversation items above for more information.

ReturnsExpand Collapse

conversation_item: Message { id, content, role, 3 more } or ResponseFunctionToolCallItem { id, status, created_by } or ResponseFunctionToolCallOutputItem { id, output, status, 6 more } or 25 more

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

message: object { id, content, role, 3 more }

A message to or from the model.

response_function_tool_call_item: ResponseFunctionToolCall { arguments, call_id, name, 5 more }

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

response_function_tool_call_output_item: object { id, output, status, 6 more }

response_file_search_tool_call: object { id, queries, status, 2 more }

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

response_function_web_search: object { id, action, status, type }

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

image_generation_call: object { id, result, status, type }

An image generation request made by the model.

response_computer_tool_call: object { id, call_id, pending_safety_checks, 4 more }

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

response_computer_tool_call_output_item: object { id, call_id, output, 4 more }

response_tool_search_call: object { id, arguments, call_id, 4 more }

response_tool_search_output_item: object { id, call_id, execution, 4 more }

additional_tools: object { id, role, tools, type }

response_reasoning_item: object { 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: object { id, call_id, code, 2 more }

program_output: object { id, call_id, result, 2 more }

response_compaction_item: object { id, encrypted_content, type, created_by }

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

response_code_interpreter_tool_call: object { id, code, container_id, 3 more }

A tool call to run code.

local_shell_call: object { id, action, call_id, 2 more }

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

local_shell_call_output: object { id, output, type, status }

The output of a local shell tool call.

response_function_shell_tool_call: object { id, action, call_id, 5 more }

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

response_function_shell_tool_call_output: object { id, call_id, max_output_length, 5 more }

The output of a shell tool call that was emitted.

response_apply_patch_tool_call: object { id, call_id, operation, 4 more }

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

response_apply_patch_tool_call_output: object { id, call_id, status, 4 more }

The output emitted by an apply patch tool call.

mcp_list_tools: object { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

mcp_approval_request: object { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

mcp_approval_response: object { id, approval_request_id, approve, 2 more }

A response to an MCP approval request.

mcp_call: object { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

response_custom_tool_call: object { call_id, input, name, 4 more }

A call to a custom tool created by the model.

response_custom_tool_call_output: object { call_id, output, type, 2 more }

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

Retrieve an item

CLI Tool

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

openai conversations:items retrieve \
  --api-key 'My API Key' \
  --conversation-id conv_123 \
  --item-id msg_abc

{
  "type": "message",
  "id": "msg_abc",
  "status": "completed",
  "role": "user",
  "content": [
    {"type": "input_text", "text": "Hello!"}
  ]
}

Returns Examples

{
  "type": "message",
  "id": "msg_abc",
  "status": "completed",
  "role": "user",
  "content": [
    {"type": "input_text", "text": "Hello!"}
  ]
}