## List assistants

`$ openai beta:assistants list`

**get** `/assistants`

Returns a list of assistants.

### Parameters

- `--after: optional 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: optional 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, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

- `--limit: optional number`

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

- `--order: optional "asc" or "desc"`

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

### Returns

- `ListAssistantsResponse: object { data, first_id, has_more, 2 more }`

  - `data: array of Assistant`

    - `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: map[string]`

      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](https://platform.openai.com/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](https://platform.openai.com/docs/models) 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`.

    - `tools: array of AssistantTool`

      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`.

      - `code_interpreter_tool: object { type }`

        - `type: "code_interpreter"`

          The type of tool being defined: `code_interpreter`

      - `file_search_tool: object { type, file_search }`

        - `type: "file_search"`

          The type of tool being defined: `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](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) 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](https://platform.openai.com/docs/assistants/tools/file-search#customizing-file-search-settings) 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"`

      - `function_tool: object { function, type }`

        - `function: object { name, description, parameters, strict }`

          - `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 map[unknown]`

            The parameters the functions accepts, described as a JSON Schema object. See the [guide](https://platform.openai.com/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) 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](https://platform.openai.com/docs/guides/function-calling).

        - `type: "function"`

          The type of tool being defined: `function`

    - `response_format: optional "auto" or ResponseFormatText or ResponseFormatJSONObject or ResponseFormatJSONSchema`

      Specifies the format that the model must output. Compatible with [GPT-4o](https://platform.openai.com/docs/models#gpt-4o), [GPT-4 Turbo](https://platform.openai.com/docs/models#gpt-4-turbo-and-gpt-4), 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](https://platform.openai.com/docs/guides/structured-outputs).

      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.

      - `union_member_0: "auto"`

        `auto` is the default value

      - `response_format_text: object { type }`

        Default response format. Used to generate text responses.

        - `type: "text"`

          The type of response format being defined. Always `text`.

      - `response_format_json_object: 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`.

      - `response_format_json_schema: object { json_schema, type }`

        JSON Schema response format. Used to generate structured JSON responses.
        Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/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](https://json-schema.org/).

          - `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](https://platform.openai.com/docs/guides/structured-outputs).

        - `type: "json_schema"`

          The type of response format being defined. Always `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](https://platform.openai.com/docs/api-reference/files) 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](https://platform.openai.com/docs/api-reference/vector-stores/object) 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.

  - `first_id: string`

  - `has_more: boolean`

  - `last_id: string`

  - `object: string`

### Example

```cli
openai beta:assistants list \
  --api-key 'My API Key'
```

#### Response

```json
{
  "data": [
    {
      "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
    }
  ],
  "first_id": "asst_abc123",
  "has_more": false,
  "last_id": "asst_abc456",
  "object": "list"
}
```