Skip to main content
POST
https://api.ai21.com
/
studio
/
v1
/
maestro
/
runs
from ai21 import AI21Client
from ai21.models.chat import ChatMessage

client = AI21Client(api_key="YOUR_API_KEY")

# Create and poll a Maestro run
run = client.beta.maestro.runs.create_and_poll(
    input="Summarize today's major movements in global financial markets and explain possible reasons for these changes.",
    requirements=[
        {"name": "factual_accuracy",
            "description": "Base insights on verifiable data from reliable financial sources."},
        {"name": "clarity", "description": "Keep explanations concise and free of jargon."},
        {"name": "tone", "description": "Maintain a neutral, professional tone suitable for enterprise reporting."}
    ],
    tools=[
        {
            "type": "web_search",
            "urls": ["https://www.reuters.com/markets/", "https://finance.yahoo.com/"]
        }
    ],
    include=["requirements_result", "data_sources"],
    budget="medium"
)

# Print the generated analysis
print("=== Financial Market Summary ===")
print(run.result)
print()

# Print requirement evaluation
print("=== Requirements Results ===")
for req in run.requirements_result["requirements"]:
    print(f"- {req['name']}: {req['score']} ({req['reason']})")
print()

# Print data sources
print("=== Data Sources ===")
if hasattr(run, 'data_sources') and run.data_sources:
    if run.data_sources.get('web_search'):
        print("Web Search Results:")
        for result in run.data_sources['web_search']:
            print(f"  - {result.get('url')}")
else:
    print("No data sources available")

​
Request body

​
input
string | object[]
required
A list of conversational turns, alternating between the user and the assistant, or a single instruction string.Please note that there are two different options for the input.
Text input string
A plain instruction string for AI21 Maestro. Equivalent to a single message with the user role.

Input messages object []
A list of message objects representing a multi-turn conversation alternating between the user and the assistant.
​
role
string
required
The role of the entity that is creating the message. Allowed values include:user : A message is sent by an actual user. It represents the user’s intent.assistant : A message is generated by the assistant.
​
content
string
required
The textual content of the message.
​
requirements
object[]
Explicit requirements for the output. The requirements can be in terms of content, style, format, genre, point of view, and various guardrails AI21 Maestro will allocate resources to maintain all requirements throughout the run. At the end of the run, the score for each requirement and the overall score will be returned. Users can specify up to 10 requirements.
​
name
string
required
The requirement’s name, which allows users to reference it in their applications later.
​
description
string
required
The requirement’s description in natural language. This will influence our result scoring and budget allocation. The maximum length for each description is 128 words.
​
is_mandatory
boolean
Default: false.
If set to true, and the associated requirement is not fully satisfied, the overall requirements_result score will be 0.
Examples of requirements:
  • “Write up to 3 paragraphs”
  • “Output only the answer”
  • “Don’t mention a word about the company’s CEO”
  • “Use a friendly tone”
Avoid conflicting requirementsConflicts may reduce run quality or prevent fulfillment.
​
tools
object[]
An array of objects. Each object describes a tool that AI21 Maestro may invoke during execution. The behavior and required fields vary depending on the tool’s type.
MCP Tool object
Use this tool type to allow AI21 Maestro to interact with external services through the Model Context Protocol (MCP). MCP enables dynamic discovery of available tools and resources provided by an MCP server, making integration more flexible and extensible.
​
type
string
required
The string has to be mcp.
​
server_label
string
required
Unique name for the MCP server within the session.
​
server_url
string
required
Fully qualified URL of the MCP server endpoint.
​
headers
object
Authentication headers (e.g., bearer tokens).
​
allowed_tools
string[]
List of tool names that Maestro can use. Must align with the tools exposed by the MCP server.
If not specified, all tools will be loaded.
HTTP Tool object
Use this tool type to allow AI21 Maestro to perform HTTP POST requests to an external service.
​
type
string
required
The string has to be http.
​
function
object
required
Describes the callable function interface of the tool.
​
name
string
required
A unique identifier for the tool. Should clearly reflect the action it performs.
​
description
string
An explanation of what the tool does and when it should be used.
​
parameters
object
A JSON Schema describing the input parameters this tool accepts.
Each parameter should preferably include a description.
​
endpoint
object
required
Defines how to construct the HTTP request.
​
url
string
required
The endpoint URL the tool should call.
​
headers
object
HTTP headers to include in the request, typically used for authorization or content-type declarations.
Only POSTrequests are currently supported.
For more information on how the request is made, see the following example.
JSON Example
{
  "type": "http",
  "function": {
    "name": "getWeatherForecast",
    "description": "Fetches a 7-day weather forecast for a given location.",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City or region to fetch weather for"
        }
      },
      "required": ["location"]
    }
  },
  "endpoint": {
    "url": "https://api.weatherapi.com/v1/forecast",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}
File Search Tool object
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a file search.
​
type
string
required
The string has to be file_search.
​
labels
string[]
Restrict file search to files with these labels.
If not provided, search is not restricted by label.
​
file_ids
string[]
Restrict file search to these file IDs.
If not provided, search is not restricted by file ID.
Web Search Tool object
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a web search.
​
type
string
required
The string has to be web_search.
​
urls
string[]
Restrict web search to the specified URL prefixes. The following formats are valid:
  1. https://example.com – limits to URLs that start with www.example.com
  2. example.com – limits to URLs that start with www.example.com
  3. example.com/page – limits to URLs that start with www.example.com/page
  4. sub.example.com – limits to URLs that start with the specified subdomain (e.g., docs.example.com, blog.example.com)
If not provided, search is not restricted to specific domains.
​
models
string[]
defaults to null.Specify a single model to be used for the run. Choose from the following:First-Party Models Models hosted and managed by AI21:
  • jamba-large
  • jamba-mini
Third‑Party Models (Managed by AI21) Models hosted by third-party providers but accessed through AI21’s API (no user API key required):
  • claude-3-5-haiku
  • claude-4-sonnet
  • gemini-2.5-flash
  • gemini-2.5-flash-lite
  • gpt-4.1
  • gpt-4.1-mini
  • llama-33-70b-instruct
  • mistral-7b
  • mistral-8x7b
  • mistral-small
  • mistral-small-24B
  • qwen-qwq-32b
  • qwen3-235b-a22b-instruct-2507
Third-Party Models (BYOK)
Bring‑Your‑Own‑Key (BYOK) third‑party models:
Specify the ID of a third-party model configured on the 3rd-Party Models page.These models require your own API key. AI21 uses your key to authenticate and access the model on your behalf. Supported providers include OpenAI, Anthropic, and Google.
​
budget
string
Controls how many resources AI21 Maestro allocates to fulfill a task, including the number of execution steps and the level of effort applied.The higher the budget, the more likely latency and execution costs will increase.

Accepted values:
  • low - One execution step is taken with minimal effort to fulfill the requirements.
  • medium - Multiple execution steps are taken with moderate effort to fulfill the requirements.
  • high - Multiple execution strategies, each containing multiple execution steps, are used with maximum effort to fulfill the requirements.
Defaults to low if not provided.
​
include
string[]
Specify which extra fields should be included in the output. If not provided, none of these fields will be included. Supported values:
  • data_sources — Includes the data_sources field in the output.
  • requirements_result — Includes detailed results for each requirement in the requirements_result field.
​
response_language
string | null
Controls the output language of AI21 Maestro responses.
Response language can be only one of the following: “arabic”, “dutch”, “english”, “french”, “german”, “hebrew”, “italian”, “portuguese”, “spanish”.

If not provided, the language is detected automatically, AI21 Maestro will respond in the same language as the input prompt unless a specific language is set.

​
Returns

Run object 
from ai21 import AI21Client
from ai21.models.chat import ChatMessage

client = AI21Client(api_key="YOUR_API_KEY")

# Create and poll a Maestro run
run = client.beta.maestro.runs.create_and_poll(
    input="Summarize today's major movements in global financial markets and explain possible reasons for these changes.",
    requirements=[
        {"name": "factual_accuracy",
            "description": "Base insights on verifiable data from reliable financial sources."},
        {"name": "clarity", "description": "Keep explanations concise and free of jargon."},
        {"name": "tone", "description": "Maintain a neutral, professional tone suitable for enterprise reporting."}
    ],
    tools=[
        {
            "type": "web_search",
            "urls": ["https://www.reuters.com/markets/", "https://finance.yahoo.com/"]
        }
    ],
    include=["requirements_result", "data_sources"],
    budget="medium"
)

# Print the generated analysis
print("=== Financial Market Summary ===")
print(run.result)
print()

# Print requirement evaluation
print("=== Requirements Results ===")
for req in run.requirements_result["requirements"]:
    print(f"- {req['name']}: {req['score']} ({req['reason']})")
print()

# Print data sources
print("=== Data Sources ===")
if hasattr(run, 'data_sources') and run.data_sources:
    if run.data_sources.get('web_search'):
        print("Web Search Results:")
        for result in run.data_sources['web_search']:
            print(f"  - {result.get('url')}")
else:
    print("No data sources available")