Skip to content

Retrieves a run step.

GET
/threads/{thread_id}/runs/{run_id}/steps/{step_id}

Authorizations

Parameters

Path Parameters

thread_id
required
string

The ID of the thread to which the run and run step belongs.

run_id
required
string

The ID of the run to which the run step belongs.

step_id
required
string

The ID of the run step to retrieve.

Query Parameters

include[]
Array<string>
Allowed values: step_details.tool_calls[*].file_search.results[*].content

A list of additional fields to include in the response. Currently the only supported value is step_details.tool_calls[*].file_search.results[*].content to fetch the file search result content.

See the file search tool documentation for more information.

Responses

200

OK

Represents a step in execution of a run.

object
id
required

The identifier of the run step, which can be referenced in API endpoints.

string
object
required

The object type, which is always thread.run.step.

string
Allowed values: thread.run.step
created_at
required

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

integer
assistant_id
required

The ID of the assistant associated with the run step.

string
thread_id
required

The ID of the thread that was run.

string
run_id
required

The ID of the run that this run step is a part of.

string
type
required

The type of run step, which can be either message_creation or tool_calls.

string
Allowed values: message_creation tool_calls
status
required

The status of the run step, which can be either in_progress, cancelled, failed, completed, or expired.

string
Allowed values: in_progress cancelled failed completed expired
step_details
required
One of:

Details of the message creation by the run step.

object
type
required

Always message_creation.

string
Allowed values: message_creation
message_creation
required
object
message_id
required

The ID of the message that was created by this run step.

string
last_error
required

The last error associated with this run step. Will be null if there are no errors.

object
code
required

One of server_error or rate_limit_exceeded.

string
Allowed values: server_error rate_limit_exceeded
message
required

A human-readable description of the error.

string
expired_at
required

The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired.

integer
nullable
cancelled_at
required

The Unix timestamp (in seconds) for when the run step was cancelled.

integer
nullable
failed_at
required

The Unix timestamp (in seconds) for when the run step failed.

integer
nullable
completed_at
required

The Unix timestamp (in seconds) for when the run step completed.

integer
nullable
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
usage
required

Usage statistics related to the run step. This value will be null while the run step’s status is in_progress.

object
completion_tokens
required

Number of completion tokens used over the course of the run step.

integer
prompt_tokens
required

Number of prompt tokens used over the course of the run step.

integer
total_tokens
required

Total number of tokens used (prompt + completion).

integer