> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/openai/openai-python/llms.txt
> Use this file to discover all available pages before exploring further.

# Thread Messages

<Warning>
  The Assistants API is deprecated in favor of the Responses API.
</Warning>

Create a message in a thread.

## Path Parameters

<ParamField path="thread_id" type="string" required>
  The ID of the thread to create a message for.
</ParamField>

## Request Body

<ParamField body="role" type="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
</ParamField>

<ParamField body="content" type="string" required>
  The text contents of the message.
</ParamField>

<ParamField body="attachments" type="array">
  A list of files attached to the message, and the tools they should be added to.

  <Expandable title="Attachment object">
    <ParamField body="file_id" type="string">
      The ID of the file to attach to the message.
    </ParamField>

    <ParamField body="tools" type="array">
      The tools to add this file to.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="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.
</ParamField>

## Response

Returns a `Message` object.

<ResponseField name="id" type="string">
  The message identifier.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, always `thread.message`.
</ResponseField>

<ResponseField name="created_at" type="integer">
  The Unix timestamp (in seconds) for when the message was created.
</ResponseField>

<ResponseField name="thread_id" type="string">
  The thread ID that this message belongs to.
</ResponseField>

<ResponseField name="role" type="string">
  The entity that produced the message. One of `user` or `assistant`.
</ResponseField>

<ResponseField name="content" type="array">
  The content of the message in array of text and/or images.
</ResponseField>

## List Messages

`GET https://api.openai.com/v1/threads/{thread_id}/messages`

Returns a list of messages for a given thread.

### Query Parameters

<ParamField query="limit" type="integer" default="20">
  A limit on the number of objects to be returned. Limit can range between 1 and 100.
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order by the `created_at` timestamp. `asc` for ascending order and `desc` for descending order.
</ParamField>

<ParamField query="after" type="string">
  A cursor for use in pagination.
</ParamField>

<ParamField query="before" type="string">
  A cursor for use in pagination.
</ParamField>

<ParamField query="run_id" type="string">
  Filter messages by the run ID that generated them.
</ParamField>

<RequestExample>
  ```python Python theme={null}
  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)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";
  const openai = new OpenAI();

  // Create a message
  const message = await openai.beta.threads.messages.create(
    "thread_abc123",
    {
      role: "user",
      content: "How does AI work? Explain it in simple terms."
    }
  );

  // List messages
  const messages = await openai.beta.threads.messages.list(
    "thread_abc123"
  );

  for (const msg of messages.data) {
    console.log(msg.role, msg.content);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.openai.com/v1/threads/thread_abc123/messages \\
    -H "Authorization: Bearer $OPENAI_API_KEY" \\
    -H "Content-Type: application/json" \\
    -H "OpenAI-Beta: assistants=v2" \\
    -d '{
      "role": "user",
      "content": "How does AI work? Explain it in simple terms."
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "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": {}
  }
  ```
</ResponseExample>