Create a thread and run it in one request.

POST /threads/runs
Api key auth
application/json

Body Required

  • assistant_id string Required

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

  • thread object

    Options to create a new thread. If no thread is provided when running a request, an empty thread will be created.

    Additional properties are NOT allowed.

    Hide thread attributes Show thread attributes object
    • messages array[object]

      A list of messages to start the thread with.

      Hide messages attributes Show messages attributes object
      • role string Required

        The role of the entity that is creating the message. Allowed values include:

        • user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
        • assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.

        Values are user or assistant.

      • content string | array[object] Required

        One of:
        Text content string Array of content parts array[object]

        The text contents of the message.

      • attachments array[object] | null

        A list of files attached to the message, and the tools they should be 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

        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
    • tool_resources object | null

      A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

      Hide tool_resources attributes Show tool_resources attributes object | null
      • code_interpreter object
        Hide code_interpreter attribute Show code_interpreter attribute object
        • file_ids array[string]

          A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

          Not more than 20 elements. Default value is [] (empty).

      • file_search object

        One of:
        object-1 object object-2 object
        Hide attributes Show attributes
        • vector_store_ids array[string] Required

          The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread.

          Not more than 1 element.

        • vector_stores array[object]

          A helper to create a vector store with file_ids and attach it to this thread. There can be a maximum of 1 vector store attached to the thread.

          Not more than 1 element.

          Hide vector_stores attributes Show vector_stores attributes object
          • file_ids array[string]

            A list of file IDs to add to the vector store. There can be a maximum of 10000 files in a vector store.

            Not more than 10000 elements.

          • chunking_strategy object

            The chunking strategy used to chunk the file(s). If not set, will use the auto strategy.

            One of:
            Auto Chunking Strategy object Static Chunking Strategy object

            The default strategy. This strategy currently uses a max_chunk_size_tokens of 800 and chunk_overlap_tokens of 400.

            Hide attribute Show attribute
            • type string Required

              Always auto.

              Value is auto.

          • metadata object | null

            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
    • metadata object | null

      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

  • model string | null

    The ID of the Model to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used.

    Any of:
    string-1 string | null string-2 string | null
  • instructions string | null

    Override the default system message of the assistant. This is useful for modifying the behavior on a per-run basis.

  • tools array[object] | null

    Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis.

    Not more than 20 elements.

    One of:
    AssistantToolsCode object AssistantToolsFileSearch object AssistantToolsFunction object
    Hide attribute Show attribute
    • type string Required

      The type of tool being defined: code_interpreter

      Value is code_interpreter.

  • tool_resources object | null

    A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

    Hide tool_resources attributes Show tool_resources attributes object | null
    • code_interpreter object
      Hide code_interpreter attribute Show code_interpreter attribute object
      • file_ids array[string]

        A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.

        Not more than 20 elements. Default value is [] (empty).

    • file_search object
      Hide file_search attribute Show file_search attribute object
      • vector_store_ids array[string]

        The ID of the vector store attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.

        Not more than 1 element.

  • metadata object | null

    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
  • temperature number | null

    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.

    Minimum value is 0, maximum value is 2. Default value is 1.

  • top_p number | null

    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.

    Minimum value is 0, maximum value is 1. Default value is 1.

  • stream boolean | null

    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_tokens integer | null

    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.

    Minimum value is 256.

  • max_completion_tokens integer | null

    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.

    Minimum value is 256.

  • truncation_strategy object

    Controls for how a thread will be truncated prior to the run. Use this to control the intial context window of the run.

    Hide truncation_strategy attributes Show truncation_strategy attributes object
    • type string Required

      The truncation strategy to use for the thread. The default is auto. If set to last_messages, the thread will be truncated to the n most recent messages in the thread. When set to auto, messages in the middle of the thread will be dropped to fit the context length of the model, max_prompt_tokens.

      Values are auto or last_messages.

    • last_messages integer | null

      The number of most recent messages from the thread when constructing the context for the run.

      Minimum value is 1.

  • tool_choice string | object

    One of:
    string-1 string AssistantsNamedToolChoice object

    none means the model will not call any tools and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools before responding to the user.

    Values are none, auto, or required.

  • parallel_tool_calls boolean

    Whether to enable parallel function calling during tool use.

    Default value is true.

  • response_format string | null | object

    Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.

    Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

    Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.

    Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

    One of:
    string-1 string | null ResponseFormatText object | null ResponseFormatJsonObject object | null ResponseFormatJsonSchema object | null

    auto is the default value

    Value is auto.

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • id string Required

      The identifier, which can be referenced in API endpoints.

    • object string Required

      The object type, which is always thread.run.

      Value is thread.run.

    • created_at integer Required

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

    • thread_id string Required

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

    • assistant_id string Required

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

    • status string Required

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

      Values are queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.

    • required_action object | null Required

      Details on the action required to continue the run. Will be null if no action is required.

      Hide required_action attributes Show required_action attributes object | null
      • type string Required

        For now, this is always submit_tool_outputs.

        Value is submit_tool_outputs.

      • submit_tool_outputs object Required

        Details on the tool outputs needed for this run to continue.

        Hide submit_tool_outputs attribute Show submit_tool_outputs attribute object
        • tool_calls array[object] Required

          A list of the relevant tool calls.

          Tool call objects

          Hide tool_calls attributes Show tool_calls attributes object
          • id string Required

            The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the Submit tool outputs to run endpoint.

          • type string Required

            The type of tool call the output is required for. For now, this is always function.

            Value is function.

          • function object Required

            The function definition.

            Hide function attributes Show function attributes object
            • name string Required

              The name of the function.

            • arguments string Required

              The arguments that the model expects you to pass to the function.

    • last_error object | null Required

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

      Hide last_error attributes Show last_error attributes object | null
      • code string Required

        One of server_error, rate_limit_exceeded, or invalid_prompt.

        Values are server_error, rate_limit_exceeded, or invalid_prompt.

      • message string Required

        A human-readable description of the error.

    • expires_at integer | null Required

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

    • started_at integer | null Required

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

    • cancelled_at integer | null Required

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

    • failed_at integer | null Required

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

    • completed_at integer | null Required

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

    • incomplete_details object | null Required

      Details on why the run is incomplete. Will be null if the run is not incomplete.

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

        The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run.

        Values are max_completion_tokens or max_prompt_tokens.

    • model string Required

      The model that the assistant used for this run.

    • instructions string Required

      The instructions that the assistant used for this run.

    • tools array[object] Required

      The list of tools that the assistant used for this run.

      Not more than 20 elements. Default value is [] (empty).

      One of:
      AssistantToolsCode object AssistantToolsFileSearch object AssistantToolsFunction 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
    • usage object | null Required

      Usage statistics related to the run. This value will be null if the run is not in a terminal state (i.e. in_progress, queued, etc.).

      Hide usage attributes Show usage attributes object | null
      • completion_tokens integer Required

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

      • prompt_tokens integer Required

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

      • total_tokens integer Required

        Total number of tokens used (prompt + completion).

    • temperature number | null

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

    • top_p number | null

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

    • max_prompt_tokens integer | null Required

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

      Minimum value is 256.

    • max_completion_tokens integer | null Required

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

      Minimum value is 256.

    • truncation_strategy object Required

      Controls for how a thread will be truncated prior to the run. Use this to control the intial context window of the run.

      Hide truncation_strategy attributes Show truncation_strategy attributes object
      • type string Required

        The truncation strategy to use for the thread. The default is auto. If set to last_messages, the thread will be truncated to the n most recent messages in the thread. When set to auto, messages in the middle of the thread will be dropped to fit the context length of the model, max_prompt_tokens.

        Values are auto or last_messages.

      • last_messages integer | null

        The number of most recent messages from the thread when constructing the context for the run.

        Minimum value is 1.

    • tool_choice string | object Required

      One of:
      string-1 string AssistantsNamedToolChoice object

      none means the model will not call any tools and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools before responding to the user.

      Values are none, auto, or required.

    • parallel_tool_calls boolean Required

      Whether to enable parallel function calling during tool use.

      Default value is true.

    • response_format string | null | object Required

      Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.

      Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

      Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.

      Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.

      One of:
      string-1 string | null ResponseFormatText object | null ResponseFormatJsonObject object | null ResponseFormatJsonSchema object | null

      auto is the default value

      Value is auto.
POST /threads/runs 
curl \
 --request POST 'https://api.openai.com/v1/threads/runs' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"assistant_id":"string","thread":{"messages":[{"role":"user","content":"string","attachments":[{"file_id":"string","tools":[{"type":"code_interpreter"}]}],"metadata":{"additionalProperty1":"string","additionalProperty2":"string"}}],"tool_resources":{"code_interpreter":{"file_ids":[]},"file_search":{"vector_store_ids":["string"],"vector_stores":[{"file_ids":["string"],"chunking_strategy":{"type":"auto"},"metadata":{"additionalProperty1":"string","additionalProperty2":"string"}}]}},"metadata":{"additionalProperty1":"string","additionalProperty2":"string"}},"model":"gpt-4o","instructions":"string","tools":[{"type":"code_interpreter"}],"tool_resources":{"code_interpreter":{"file_ids":[]},"file_search":{"vector_store_ids":["string"]}},"metadata":{"additionalProperty1":"string","additionalProperty2":"string"},"temperature":1,"top_p":1,"stream":true,"max_prompt_tokens":42,"max_completion_tokens":42,"truncation_strategy":{"type":"auto","last_messages":42},"tool_choice":"none","parallel_tool_calls":true,"response_format":"auto"}'
Request examples 
{
  "assistant_id": "string",
  "thread": {
    "messages": [
      {
        "role": "user",
        "content": "string",
        "attachments": [
          {
            "file_id": "string",
            "tools": [
              {
                "type": "code_interpreter"
              }
            ]
          }
        ],
        "metadata": {
          "additionalProperty1": "string",
          "additionalProperty2": "string"
        }
      }
    ],
    "tool_resources": {
      "code_interpreter": {
        "file_ids": []
      },
      "file_search": {
        "vector_store_ids": [
          "string"
        ],
        "vector_stores": [
          {
            "file_ids": [
              "string"
            ],
            "chunking_strategy": {
              "type": "auto"
            },
            "metadata": {
              "additionalProperty1": "string",
              "additionalProperty2": "string"
            }
          }
        ]
      }
    },
    "metadata": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    }
  },
  "model": "gpt-4o",
  "instructions": "string",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "tool_resources": {
    "code_interpreter": {
      "file_ids": []
    },
    "file_search": {
      "vector_store_ids": [
        "string"
      ]
    }
  },
  "metadata": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "temperature": 1,
  "top_p": 1,
  "stream": true,
  "max_prompt_tokens": 42,
  "max_completion_tokens": 42,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": 42
  },
  "tool_choice": "none",
  "parallel_tool_calls": true,
  "response_format": "auto"
}
Response examples (200) 
{
  "id": "string",
  "object": "thread.run",
  "created_at": 42,
  "thread_id": "string",
  "assistant_id": "string",
  "status": "queued",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "string",
          "type": "function",
          "function": {
            "name": "string",
            "arguments": "string"
          }
        }
      ]
    }
  },
  "last_error": {
    "code": "server_error",
    "message": "string"
  },
  "expires_at": 42,
  "started_at": 42,
  "cancelled_at": 42,
  "failed_at": 42,
  "completed_at": 42,
  "incomplete_details": {
    "reason": "max_completion_tokens"
  },
  "model": "string",
  "instructions": "string",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "usage": {
    "completion_tokens": 42,
    "prompt_tokens": 42,
    "total_tokens": 42
  },
  "temperature": 42.0,
  "top_p": 42.0,
  "max_prompt_tokens": 42,
  "max_completion_tokens": 42,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": 42
  },
  "tool_choice": "none",
  "parallel_tool_calls": true,
  "response_format": "auto"
}