---
title: "Create Maestro Run"
method: POST
path: "/studio/v1/maestro/runs"
---

# Create Maestro Run

`POST /studio/v1/maestro/runs`

## Request body

- CreateMaestroRunsPayload
  - `input` union, required
    - Message[]
      - `role` 'assistant' | 'user', required — The role of an individual message. - `user`: Input provided by the user. Any instructions given here that conflict with instructions given in the `system` prompt take precedence over the `system` prompt instructions. - `assistant`: Response generated by the model. - `system`: Initial instructions provided to the system to provide general guidance on the tone and voice of the generated message. An initial system message is optional but recommended to provide guidance on the tone of the chat. For example, "You are a helpful chatbot with a background in earth sciences and a charming French accent."
      - `content` string, required
    - string
  - `output_type` object
  - `models` string[]
  - `tools` LanguageStudioApiServerDataTypesExecutionEngineToolDefinition[]
    - union
      - HTTPToolResource
        - `type` 'http'
        - `function` HTTPToolFunction, required
          - `name` string, required
          - `description` string, required
          - `parameters` HTTPToolFunctionParameters, required
            - `type` 'object'
            - `properties` object, required
            - `required` string[], required
            - `additionalProperties` boolean
        - `endpoint` HTTPToolEndpoint, required
          - `url` string, required
          - `headers` object
      - MCPToolResource
        - `type` 'mcp'
        - `server_label` string
        - `server_url` string
        - `headers` object
        - `allowed_tools` string[]
        - `mcp_id` string
      - FileSearchToolResource
        - `type` 'file_search'
        - `retrieval_similarity_threshold` number
        - `labels` string[]
        - `labels_filter_mode` 'AND' | 'OR'
        - `labels_filter` union
          - ComparisonOperator
          - LogicalOperator
          - object
        - `file_ids` string[]
        - `retrieval_strategy` 'segments' | 'default' | 'add_neighbors' | 'full_doc' — An enumeration.
        - `max_neighbors` integer
        - `path` string
        - `response_language` 'arabic' | 'dutch' | 'english' | 'french' | 'german' | 'hebrew' | 'italian' | 'portuguese' | 'spanish' | 'unset'
        - `hybrid_search_alpha` number
        - `use_two_step_embedders` boolean
      - WebSearchToolResource
        - `type` 'web_search'
        - `urls` string[]
        - `fallback_to_web` boolean
        - `query_suffix` string
        - `rephrase_query` boolean
        - `use_cached_pages` boolean
  - `context` object
  - `requirements` LanguageStudioApiServerDataTypesExecutionEngineRequirement[]
    - `name` string, required
    - `description` string, required
    - `is_mandatory` boolean
  - `budget` 'low' | 'medium' | 'high'
  - `verbose` boolean
  - `include` string[]
  - `structured_rag_enabled` boolean
  - `dynamic_planning_enabled` boolean
  - `assistant_id` string
  - `variant` 'main' | 'ingestion'
  - `custom_retrieval_configs` object[]
  - `response_language` 'arabic' | 'dutch' | 'english' | 'french' | 'german' | 'hebrew' | 'italian' | 'portuguese' | 'spanish' | 'unset'
  - `system_prompt` string
  - `stream` boolean — Whether or not to stream the result one token at a time using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events). This can be useful when waiting for long results where a long wait time for an answer can be problematic, such as a chatbot. If set to `True`, then `n` must be 1. A streaming response is different than the non-streaming response.

## Response `200`

Successful Response

- MaestroRunResult
  - `id` string, uuid, required — A unique ID for the request (not the message). Repeated identical requests get different IDs. However, for a streaming response, the ID will be the same for all responses in the stream.
  - `status` 'completed' | 'failed' | 'in_progress' | 'requires_action', required
  - `result` unknown
  - `data_sources` object
  - `requirements_result` object
  - `created_at` string, date-time
  - `error` MaestroRunError
    - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/ai21/apis/ai21-studio-api.md) · [All operations](https://skmtc.net/ai21/apis/ai21-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ai21/ai21-studio-api/versions/c1da6d993d39/schema)