POST
/
studio
/
v1
/
maestro
/
runs
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”

Note:

Requirements only work if no tools are selected.

Avoid conflicting requirements

Conflicts may reduce run quality or prevent fulfillment.

​
tools
object[]

An array of objects.

​
tool_resources
object

A set of resources used by AI21 Maestro’s tools.

​
models
string[]

defaults to null.

Specify a single model to be used for the run. Choose from the following:

First-Party Models:

  • jamba-large
  • jamba-mini

Third-Party Models:

  • gpt-4.1-large
  • gpt-4.1-mini
  • gpt-4o
  • claude-3.5-sonnet
  • claude-3.7-sonnet
  • gemini-2.5-pro
​
budget
string

Controls how many resources AI21 Maestro allocates to fulfill the requirements. Accepted values:

  • high
  • medium
  • low

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.

​
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)