Skip to content
Lucero

Returns a list of messages for a given thread.

GET
/threads/{thread_id}/messages

Authorizations

Parameters

Path Parameters

thread_id
required
string

The ID of the thread the messages belong to.

Query Parameters

limit
integer
default: 20

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

order
string
default: desc
Allowed values: asc desc

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

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, ending 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

OK

object
object
required
string
list
data
required
Array<object>

Represents a message within a thread.

object
id
required

The identifier, which can be referenced in API endpoints.

string
object
required

The object type, which is always thread.message.

string
Allowed values: thread.message
created_at
required

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

integer
thread_id
required

The thread ID that this message belongs to.

string
status
required

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

string
Allowed values: in_progress incomplete completed
incomplete_details
required

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

object
reason
required

The reason the message is incomplete.

string
Allowed values: content_filter max_tokens run_cancelled run_expired run_failed
completed_at
required

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

integer
nullable
incomplete_at
required

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

integer
nullable
role
required

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

string
Allowed values: user assistant
content
required

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

Array
One of:

References an image File in the content of a message.

object
type
required

Always image_file.

string
Allowed values: image_file
image_file
required
object
file_id
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.

string
detail

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.

string
default: auto
Allowed values: auto low high
assistant_id
required

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

string
nullable
run_id
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.

string
nullable
attachments
required

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

Array<object>
nullable
object
file_id

The ID of the file to attach to the message.

string
tools

The tools to add this file to.

Array
One of:
object
type
required

The type of tool being defined: code_interpreter

string
Allowed values: code_interpreter
metadata
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.

object
first_id
required
string
msg_abc123
last_id
required
string
msg_abc123
has_more
required
boolean