from ai21 import AI21Client

client = AI21Client()

run_result = client.beta.maestro.runs.create_and_poll(
    input="Extract vendor name, invoice number, total amount, and due date from the document",
    requirements=[
        {
            "name": "field presence validation",
            "description": "Ensure all required fields are extracted and not left empty"
        },
        {
            "name": "format consistency",
            "description": "Dates must follow YYYY-MM-DD and amounts should be in USD format."
        },
    ],
    include=["requirements_result"]
)

print(run_result.result)

​
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.
​
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.
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.
​
tool_resources
object
A set of resources used by AI21 Maestro’s tools.
The tool_resourcesparameter will be deprecated in October 2025 .
Use the tools parameter instead.
Validation has been added to restrict the number of search tools you can provide.
If more than one web_search or file_search tool is included,
the request will fail with 422 Unprocessable Entity.
Error message:
You are only allowed to provide one instance of file_search or web_search tools.
​
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):
  • gpt-4o – The latest GPT‑4o model, accessed using AI21’s own API key
  • mistral-8x7b
  • mistral-7b
  • mistral-small
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, defaults to English.

​
Returns

Run object 
from ai21 import AI21Client

client = AI21Client()

run_result = client.beta.maestro.runs.create_and_poll(
    input="Extract vendor name, invoice number, total amount, and due date from the document",
    requirements=[
        {
            "name": "field presence validation",
            "description": "Ensure all required fields are extracted and not left empty"
        },
        {
            "name": "format consistency",
            "description": "Dates must follow YYYY-MM-DD and amounts should be in USD format."
        },
    ],
    include=["requirements_result"]
)

print(run_result.result)