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

        References an image File in the content of a message.

        Hide attributes Show attributes
        • type string Required

          Always image_file.

          Value is image_file.

        • image_file object Required
          Hide image_file attributes Show image_file attributes object
          • file_id string Required

            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 string

            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.

            Values are auto, low, or high. Default value is auto.

      • 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
          Hide attribute Show attribute
          • type string Required

            The type of tool being defined: code_interpreter

            Value is code_interpreter.

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