API Reference

Beta

Threads

Messages

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List messages

Deprecated

client.beta.threads.messages.list(stringthreadID, MessageListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): CursorPage<Message { id, assistant_id, attachments, 11 more } >

GET/threads/{thread_id}/messages

Returns a list of messages for a given thread.

ParametersExpand Collapse

threadID: string

query: MessageListParams { after, before, limit, 2 more }

after?: string

A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.

before?: string

A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

limit?: number

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

order?: "asc" | "desc"

Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.

One of the following:

"asc"

"desc"

run_id?: string

Filter messages by the run ID that generated them.

ReturnsExpand Collapse

Message { id, assistant_id, attachments, 11 more }

Represents a message within a thread.

id: string

The identifier, which can be referenced in API endpoints.

assistant_id: string | null

If applicable, the ID of the assistant that authored this message.

attachments: Array<Attachment> | null

A list of files attached to the message, and the tools they were added to.

file_id?: string

The ID of the file to attach to the message.

tools?: Array<CodeInterpreterTool { type } | AssistantToolsFileSearchTypeOnly { type } >

The tools to add this file to.

One of the following:

CodeInterpreterTool { type }

type: "code_interpreter"

The type of tool being defined: code_interpreter

AssistantToolsFileSearchTypeOnly { type }

type: "file_search"

The type of tool being defined: file_search

completed_at: number | null

The Unix timestamp (in seconds) for when the message was completed.

content: Array<MessageContent>

The content of the message in array of text and/or images.

One of the following:

ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }

file_id: string

The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.

detail?: "auto" | "low" | "high"

Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.

One of the following:

"auto"

"low"

"high"

type: "image_file"

Always image_file.

ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }

url: string

The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.

formaturi

detail?: "auto" | "low" | "high"

Specifies the detail level of the image. low uses fewer tokens, you can opt in to high resolution using high. Default value is auto

One of the following:

"auto"

"low"

"high"

type: "image_url"

The type of the content part.

TextContentBlock { text, type }

The text content that is part of a message.

text: Text { annotations, value }

annotations: Array<Annotation>

One of the following:

FileCitationAnnotation { end_index, file_citation, start_index, 2 more }

A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files.

end_index: number

minimum0

file_citation: FileCitation { file_id }

file_id: string

The ID of the specific File the citation is from.

start_index: number

minimum0

text: string

The text in the message content that needs to be replaced.

type: "file_citation"

Always file_citation.

FilePathAnnotation { end_index, file_path, start_index, 2 more }

A URL for the file that's generated when the assistant used the code_interpreter tool to generate a file.

end_index: number

minimum0

file_path: FilePath { file_id }

file_id: string

The ID of the file that was generated.

start_index: number

minimum0

text: string

The text in the message content that needs to be replaced.

type: "file_path"

Always file_path.

value: string

The data that makes up the text.

type: "text"

Always text.

RefusalContentBlock { refusal, type }

The refusal content generated by the assistant.

refusal: string

type: "refusal"

Always refusal.

created_at: number

The Unix timestamp (in seconds) for when the message was created.

incomplete_at: number | null

The Unix timestamp (in seconds) for when the message was marked as incomplete.

incomplete_details: IncompleteDetails | null

On an incomplete message, details about why the message is incomplete.

reason: "content_filter" | "max_tokens" | "run_cancelled" | 2 more

The reason the message is incomplete.

One of the following:

"content_filter"

"max_tokens"

"run_cancelled"

"run_expired"

"run_failed"

metadata: Metadata | null

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

object: "thread.message"

The object type, which is always thread.message.

role: "user" | "assistant"

The entity that produced the message. One of user or assistant.

One of the following:

"user"

"assistant"

run_id: string | null

The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.

status: "in_progress" | "incomplete" | "completed"

The status of the message, which can be either in_progress, incomplete, or completed.

One of the following:

"in_progress"

"incomplete"

"completed"

thread_id: string

The thread ID that this message belongs to.

List messages

TypeScript

HTTP

TypeScript

Python

Java

Go

Ruby

import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const threadMessages = await openai.beta.threads.messages.list(
    "thread_abc123"
  );

  console.log(threadMessages.data);
}

main();

{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "How does AI work? Explain it in simple terms.",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    },
    {
      "id": "msg_abc456",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "Hello, what is AI?",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc456",
  "has_more": false
}

Returns Examples

{
  "object": "list",
  "data": [
    {
      "id": "msg_abc123",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "How does AI work? Explain it in simple terms.",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    },
    {
      "id": "msg_abc456",
      "object": "thread.message",
      "created_at": 1699016383,
      "assistant_id": null,
      "thread_id": "thread_abc123",
      "run_id": null,
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": {
            "value": "Hello, what is AI?",
            "annotations": []
          }
        }
      ],
      "attachments": [],
      "metadata": {}
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc456",
  "has_more": false
}