resources/beta/subresources/assistants/methods/retrieve/index.md 2026-07-10 23:02 UTC to 2026-07-12 06:58 UTC

Retrieve assistant

get /assistants/{assistant_id}

Retrieves an assistant.

Path Parameters

• assistant_id: string

Returns

• Assistant object { id, created_at, description, 10 more }

  Represents an assistant that can call the model and use tools.

  • id: string

    The identifier, which can be referenced in API endpoints.

  • created_at: number

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

  • description: string

    The description of the assistant. The maximum length is 512 characters.

  • instructions: string

    The system instructions that the assistant uses. The maximum length is 256,000 characters.

  • metadata: Metadata

    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.

  • model: string

    ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

  • name: string

    The name of the assistant. The maximum length is 256 characters.

  • object: "assistant"

    The object type, which is always assistant.

    • "assistant"

  • tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool

    A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, file_search, or function.

    • CodeInterpreterTool object { type }

      • type: "code_interpreter"

        The type of tool being defined: code_interpreter

        • "code_interpreter"

    • FileSearchTool object { type, file_search }

      • type: "file_search"

        The type of tool being defined: file_search

        • "file_search"

      • file_search: optional object { max_num_results, ranking_options }

        Overrides for the file search tool.

        • max_num_results: optional number

          The maximum number of results the file search tool should output. The default is 20 for gpt-4* models and 5 for gpt-3.5-turbo. This number should be between 1 and 50 inclusive.

          Note that the file search tool may output fewer than max_num_results results. See the file search tool documentation for more information.

        • ranking_options: optional object { score_threshold, ranker }

          The ranking options for the file search. If not specified, the file search tool will use the auto ranker and a score_threshold of 0.

          See the file search tool documentation for more information.

          • score_threshold: number

            The score threshold for the file search. All values must be a floating point number between 0 and 1.

          • ranker: optional "auto" or "default_2024_08_21"

            The ranker to use for the file search. If not specified will use the auto ranker.

            • "auto"

            • "default_2024_08_21"

    • FunctionTool object { function, type }

      • function: FunctionDefinition

        • name: string

          The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

        • description: optional string

          A description of what the function does, used by the model to choose when and how to call the function.

        • parameters: optional FunctionParameters

          The parameters the functions accepts, described as a JSON Schema object. See the guide for examples, and the JSON Schema reference for documentation about the format.

          Omitting parameters defines a function with an empty parameter list.

        • strict: optional boolean

          Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the parameters field. Only a subset of JSON Schema is supported when strict is true. Learn more about Structured Outputs in the function calling guide.

      • type: "function"

        The type of tool being defined: function

        • "function"

  • response_format: optional AssistantResponseFormatOption

    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.

    • "auto"

      auto is the default value

      • "auto"

    • ResponseFormatText object { type }

      Default response format. Used to generate text responses.

      • type: "text"

        The type of response format being defined. Always text.

        • "text"

    • ResponseFormatJSONObject object { type }

      JSON object response format. An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

      • type: "json_object"

        The type of response format being defined. Always json_object.

        • "json_object"

    • ResponseFormatJSONSchema object { json_schema, type }

      JSON Schema response format. Used to generate structured JSON responses. Learn more about Structured Outputs.

      • json_schema: object { name, description, schema, strict }

        Structured Outputs configuration options, including a JSON Schema.

        • name: string

          The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

        • description: optional string

          A description of what the response format is for, used by the model to determine how to respond in the format.

        • schema: optional map[unknown]

          The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.

        • strict: optional boolean

          Whether to enable strict schema adherence when generating the output. If set to true, the model will always follow the exact schema defined in the schema field. Only a subset of JSON Schema is supported when strict is true. To learn more, read the Structured Outputs guide.

      • type: "json_schema"

        The type of response format being defined. Always json_schema.

        • "json_schema"

  • temperature: optional number

    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.

  • tool_resources: optional object { code_interpreter, file_search }

    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.

    • code_interpreter: optional object { file_ids }

      • file_ids: optional array of 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.

    • file_search: optional object { vector_store_ids }

      • vector_store_ids: optional array of string

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

  • top_p: optional number

    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.

Example

curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \
    -H 'OpenAI-Beta: assistants=v2' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "created_at": 0,
  "description": "description",
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "name": "name",
  "object": "assistant",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "response_format": "auto",
  "temperature": 1,
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "string"
      ]
    },
    "file_search": {
      "vector_store_ids": [
        "string"
      ]
    }
  },
  "top_p": 1
}

Example

curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

Response

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4o",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}