---
title: "Returns a list of messages for a given thread."
method: GET
path: "/threads/{thread_id}/messages"
tags: ["Assistants"]
---

# Returns a list of messages for a given thread.

`GET /threads/{thread_id}/messages`

## Path parameters

- `thread_id` string, required

## Query parameters

- `limit` integer
- `order` 'asc' | 'desc'
- `after` string
- `before` string
- `run_id` string

## Response `200`

OK

- ListMessagesResponse
  - `object` string, required
  - `data` MessageObject[], required
    - `id` string, required — The identifier, which can be referenced in API endpoints.
    - `object` 'thread.message', required — The object type, which is always `thread.message`.
    - `created_at` integer, required — The Unix timestamp (in seconds) for when the message was created.
    - `thread_id` string, required — The [thread](/docs/api-reference/threads) ID that this message belongs to.
    - `status` 'in_progress' | 'incomplete' | 'completed', required — The status of the message, which can be either `in_progress`, `incomplete`, or `completed`.
    - `incomplete_details` object, nullable, required — On an incomplete message, details about why the message is incomplete.
      - `reason` 'content_filter' | 'max_tokens' | 'run_cancelled' | 'run_expired' | 'run_failed', required — The reason the message is incomplete.
    - `completed_at` integer, nullable, required — The Unix timestamp (in seconds) for when the message was completed.
    - `incomplete_at` integer, nullable, required — The Unix timestamp (in seconds) for when the message was marked as incomplete.
    - `role` 'user' | 'assistant', required — The entity that produced the message. One of `user` or `assistant`.
    - `content` union[], required — The content of the message in array of text and/or images.
      - union
        - object — References an image [File](/docs/api-reference/files) in the content of a message.
          - `type` 'image_file', required — Always `image_file`.
          - `image_file` object, required
            - `file_id` string, required — The [File](/docs/api-reference/files) 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`.
        - object — References an image URL in the content of a message.
          - `type` 'image_url', required — The type of the content part.
          - `image_url` object, required
            - `url` string, uri, required — The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp.
            - `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`
        - object — The text content that is part of a message.
          - `type` 'text', required — Always `text`.
          - `text` object, required
            - `value` string, required — The data that makes up the text.
            - `annotations` union[], required
              - …
        - object — The refusal content generated by the assistant.
          - `type` 'refusal', required — Always `refusal`.
          - `refusal` string, required
    - `assistant_id` string, nullable, required — If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message.
    - `run_id` string, nullable, required — The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints.
    - `attachments` object[], nullable, required — 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` union[] — The tools to add this file to.
        - union
          - object
            - `type` 'code_interpreter', required — The type of tool being defined: `code_interpreter`
          - object
            - `type` 'file_search', required — The type of tool being defined: `file_search`
    - `metadata` object, nullable, required — 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. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.
  - `first_id` string, required
  - `last_id` string, required
  - `has_more` boolean, required

---

[API](https://skmtc.net/omnistack-sh/apis/openai-api.md) · [All operations](https://skmtc.net/omnistack-sh/apis/openai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/omnistack-sh/openai-api/versions/a127ad1d97cb/schema)