Sign in
Assistants

Create run

Create a run.

post/threads/{thread_id}/runs

Path parameters

thread_idstring required

The ID of the thread to run.

Query parameters

include[]string[]

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.

Request body

assistant_idstring required

The ID of the assistant to use to execute this run.

reasoning_effort'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' nullable

Constrains effort on reasoning for reasoning models. Currently supported values are none, minimal, low, medium, high, xhigh, and max. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response. Not all reasoning models support every value. See the reasoning guide for model-specific support.

instructionsstring nullable

Overrides the instructions of the assistant. This is useful for modifying the behavior on a per-run basis.

additional_instructionsstring nullable

Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions.

metadataMetadata nullable

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.

temperaturenumber nullable

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

top_pnumber nullable

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

streamboolean nullable

If true, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a data: [DONE] message.

max_prompt_tokensinteger nullable

The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status incomplete. See incomplete_details for more info.

max_completion_tokensinteger nullable

The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status incomplete. See incomplete_details for more info.

parallel_tool_callsboolean

Whether to enable parallel function calling during tool use.

Example request

{
  "temperature": 1,
  "top_p": 1
}

Response

OK

idstring required

The identifier, which can be referenced in API endpoints.

object'thread.run' required

The object type, which is always thread.run.

created_atinteger required

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

thread_idstring required

The ID of the thread that was executed on as a part of this run.

assistant_idstring required

The ID of the assistant used for execution of this run.

status'queued' | 'in_progress' | 'requires_action' | 'cancelling' | 'cancelled' | 'failed' | 'completed' | 'incomplete' | 'expired' required

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.

expires_atinteger nullable required

The Unix timestamp (in seconds) for when the run will expire.

started_atinteger nullable required

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

cancelled_atinteger nullable required

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

failed_atinteger nullable required

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

completed_atinteger nullable required

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

modelstring required

The model that the assistant used for this run.

instructionsstring required

The instructions that the assistant used for this run.

metadataMetadata 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, 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.

temperaturenumber nullable

The sampling temperature used for this run. If not set, defaults to 1.

top_pnumber nullable

The nucleus sampling value used for this run. If not set, defaults to 1.

max_prompt_tokensinteger nullable required

The maximum number of prompt tokens specified to have been used over the course of the run.

max_completion_tokensinteger nullable required

The maximum number of completion tokens specified to have been used over the course of the run.

parallel_tool_callsboolean required

Whether to enable parallel function calling during tool use.

Changes

Changed in 17 of the 163 revisions of this API.571171

  • 9430b00d75b41See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 6ac2618eefd71See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

  • ab0c5306e3901See the full diff
    • ○

      added the new max enum value to the request property /

      request-property-enum-value-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 74cbcf73838f1819See the full diff
    • ▲

      the request property // became not nullable

      request-property-became-not-nullable

    • ▲

      the request property // became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property /// became not nullable

      request-property-became-not-nullable

    • ▲

      the request property //// became not nullable

      request-property-became-not-nullable

    • ▲

      the request property // became not nullable

      request-property-became-not-nullable

    • ▲

      removed the enum value high of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value low of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value medium of the request property

      request-property-enum-value-removed

    • ▲

      response property metadata list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property response_format/oneOf[subschema #4: JSON schema]/json_schema/strict list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property tools/items/oneOf[subschema #3: Function tool]/function/strict list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property truncation_strategy/allOf[subschema #1: Thread Truncation Controls]/last_messages list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      the response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ○

      the request property default value medium was removed

      request-property-default-value-removed

    • ○

      the request property default value false was removed

      request-property-default-value-removed

    • ○

      the request property default value false was removed

      request-property-default-value-removed

    • ○

      added the new gpt-5 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-5-2025-08-07 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-5-mini enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-5-mini-2025-08-07 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-5-nano enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-5-nano-2025-08-07 enum value to the request property ////

      request-property-enum-value-added

    • ○

      request property // list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property // list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property /// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property //// list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property // list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      added subschema #1 subschema #2 to the response property anyOf list for the response status

      response-property-any-of-added

    • ○

      the response's property default value false was removed for the status

      response-property-default-value-removed

    • ○

      the response's property default value false was removed for the status

      response-property-default-value-removed

    This revision also has 40 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6a6c681b18206See the full diff
    • ○

      added the new gpt-4.1 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.1-2025-04-14 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.1-mini enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.1-mini-2025-04-14 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.1-nano enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.1-nano-2025-04-14 enum value to the request property ////

      request-property-enum-value-added

    This revision also has 18 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 6ab43fe7798e215See the full diff
    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ▲

      added subschema #1 to the response property oneOf list for the response status

      response-property-one-of-added

    • ●

      removed subschema #2 from the request property allOf list

      request-property-all-of-removed

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      added the new gpt-4.5-preview enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new gpt-4.5-preview-2025-02-27 enum value to the request property ////

      request-property-enum-value-added

    • ○

      added subschema #1 to the request property oneOf list

      request-property-one-of-added

    • ○

      removed subschema #2 from the response property allOf list for the response status

      response-property-all-of-removed

  • 96060afbb5b912See the full diff
    • ▲

      removed subschema #2 from the request property anyOf list

      request-property-any-of-removed

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added to the request property anyOf list

      request-property-any-of-added

  • fc164a27fdb91135See the full diff
    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      removed subschema #1 from the request property oneOf list

      request-property-one-of-removed

    • ▲

      removed subschema #1 from the request property oneOf list

      request-property-one-of-removed

    • ▲

      the request property type changed from object to no type

      request-property-type-changed

    • ▲

      the response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ●

      removed the request property /

      request-property-removed

    • ●

      removed the request property /

      request-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed subschema #1 from the response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1 from the response property oneOf list for the response status

      response-property-one-of-removed

  • 15156e46769c8311See the full diff
    • ▲

      added the new required request property /

      new-required-request-property

    • ▲

      the request property type changed from no type to object

      request-property-type-changed

    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ▲

      the response property became nullable for the status

      response-property-became-nullable

    • ▲

      added subschema #1 to the response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      the response's property type changed from no type to object for status

      response-property-type-changed

    • ●

      removed subschema #2 from the request property allOf list

      request-property-all-of-removed

    • ●

      removed subschema #2 from the request property allOf list

      request-property-all-of-removed

    • ●

      removed subschema #2 from the request property allOf list

      request-property-all-of-removed

    • ○

      added the new optional request property /

      new-optional-request-property

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      the request property became nullable

      request-property-became-nullable

    • ○

      added subschema #1 to the request property oneOf list

      request-property-one-of-added

    • ○

      added subschema #1 to the request property oneOf list

      request-property-one-of-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      removed subschema #2 from the response property allOf list for the response status

      response-property-all-of-removed

    • ○

      removed subschema #2 from the response property allOf list for the response status

      response-property-all-of-removed

    • ○

      removed subschema #2 from the response property allOf list for the response status

      response-property-all-of-removed

    • ○

      added the required property / to the response with the status

      response-required-property-added

  • bdebcdfcbbde1135See the full diff
    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      added subschema #2 to the request property allOf list

      request-property-all-of-added

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      removed subschema #1 from the request property oneOf list

      request-property-one-of-removed

    • ▲

      removed subschema #1 from the request property oneOf list

      request-property-one-of-removed

    • ▲

      the request property type changed from object to no type

      request-property-type-changed

    • ▲

      the response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ●

      removed the request property /

      request-property-removed

    • ●

      removed the request property /

      request-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      added subschema #2 to the response property allOf list for the response status

      response-property-all-of-added

    • ○

      removed subschema #1 from the response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1 from the response property oneOf list for the response status

      response-property-one-of-removed