Skip to main content
POST
/
v1
/
threads
/
{thread_id}
/
messages
from openai import OpenAI
client = OpenAI()

# Create a message
message = client.beta.threads.messages.create(
    thread_id="thread_abc123",
    role="user",
    content="How does AI work? Explain it in simple terms."
)

# List messages
messages = client.beta.threads.messages.list(
    thread_id="thread_abc123"
)

for msg in messages:
    print(msg.role, msg.content)

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}
The Assistants API is deprecated in favor of the Responses API.
Create a message in a thread.

​
Path Parameters

​
thread_id
string
required
The ID of the thread to create a message for.

​
Request Body

​
role
string
required
The role of the entity that is creating the message. Allowed values:
  • user: Indicates the message is sent by an actual user
  • assistant: Indicates the message is generated by the assistant
​
content
string
required
The text contents of the message.
​
attachments
array
A list of files attached to the message, and the tools they should be added to.
​
metadata
object
Set of 16 key-value pairs that can be attached to an object.Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

​
Response

Returns a Message object.
​
id
string
The message identifier.
​
object
string
The object type, always thread.message.
​
created_at
integer
The Unix timestamp (in seconds) for when the message was created.
​
thread_id
string
The thread ID that this message belongs to.
​
role
string
The entity that produced the message. One of user or assistant.
​
content
array
The content of the message in array of text and/or images.

​
List Messages

GET https://api.openai.com/v1/threads/{thread_id}/messages Returns a list of messages for a given thread.

​
Query Parameters

​
limit
integer
default:"20"
A limit on the number of objects to be returned. Limit can range between 1 and 100.
​
order
string
default:"desc"
Sort order by the created_at timestamp. asc for ascending order and desc for descending order.
​
after
string
A cursor for use in pagination.
​
before
string
A cursor for use in pagination.
​
run_id
string
Filter messages by the run ID that generated them.
from openai import OpenAI
client = OpenAI()

# Create a message
message = client.beta.threads.messages.create(
    thread_id="thread_abc123",
    role="user",
    content="How does AI work? Explain it in simple terms."
)

# List messages
messages = client.beta.threads.messages.list(
    thread_id="thread_abc123"
)

for msg in messages:
    print(msg.role, msg.content)

{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699017614,
  "thread_id": "thread_abc123",
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "How does AI work? Explain it in simple terms.",
        "annotations": []
      }
    }
  ],
  "attachments": [],
  "metadata": {}
}

Build docs developers (and LLMs) love

Get started for freeTalk to us