Returns a list of messages for a given thread.

GET /threads/{thread_id}/messages
Api key auth

Path parameters

  • thread_id string Required

    The ID of the thread the messages belong to.

Query parameters

  • limit integer

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

    Default value is 20.

  • order string

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

    Values are asc or desc. Default value is desc.

  • 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.

  • run_id string

    Filter messages by the run ID that generated them.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • object string Required
    • data array[object] Required

      Represents a message within a thread.

      Hide data attributes Show data attributes object
      • id string Required

        The identifier, which can be referenced in API endpoints.

      • object string Required

        The object type, which is always thread.message.

        Value is thread.message.

      • created_at integer Required

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

      • thread_id string Required

        The thread ID that this message belongs to.

      • status string Required

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

        Values are in_progress, incomplete, or completed.

      • incomplete_details object | null Required

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

        Hide incomplete_details attribute Show incomplete_details attribute object | null
        • reason string Required

          The reason the message is incomplete.

          Values are content_filter, max_tokens, run_cancelled, run_expired, or run_failed.

      • completed_at integer | null Required

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

      • incomplete_at integer | null Required

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

      • role string Required

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

        Values are user or assistant.

      • content array[object] Required

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

        One of:
        MessageContentImageFileObject object MessageContentImageUrlObject object MessageContentTextObject object MessageContentRefusalObject object
      • assistant_id string | null Required

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

      • run_id string | null Required

        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.

      • attachments array[object] | null Required

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

        Hide attachments attributes Show attachments attributes object
        • file_id string

          The ID of the file to attach to the message.

        • tools array[object]

          The tools to add this file to.

          One of:
          AssistantToolsCode object AssistantToolsFileSearchTypeOnly object
      • metadata object | null 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, 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.

        Hide metadata attribute Show metadata attribute object | null
        • * string Additional properties
    • first_id string Required
    • last_id string Required
    • has_more boolean Required
GET /threads/{thread_id}/messages 
curl \
 --request GET 'https://api.openai.com/v1/threads/{thread_id}/messages' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "thread.message",
      "created_at": 42,
      "thread_id": "string",
      "status": "in_progress",
      "incomplete_details": {
        "reason": "content_filter"
      },
      "completed_at": 42,
      "incomplete_at": 42,
      "role": "user",
      "content": [
        {
          "type": "image_file",
          "image_file": {
            "file_id": "string",
            "detail": "auto"
          }
        }
      ],
      "assistant_id": "string",
      "run_id": "string",
      "attachments": [
        {
          "file_id": "string",
          "tools": [
            {
              "type": "code_interpreter"
            }
          ]
        }
      ],
      "metadata": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      }
    }
  ],
  "first_id": "msg_abc123",
  "last_id": "msg_abc123",
  "has_more": false
}