Welcome to AI21 Labs

Start building your AI solution with comprehensive guides and API references for AI21 Maestro and our Jamba Family of Open Models.

Terms and Policies

Publications

# Rate Limits Source: https://docs.ai21.com/reference/api-rate-limits Rate limits serve as essential mechanisms to control the flow of requests made to a system, ensuring its stability and fair usage. Rate limits restrict the number of requests that can be made within a specific time frame. Rate limits are commonly measured by **RPM** (requests per minute) or **RPS** (requests per second), indicating the maximum allowed number of requests a user or application can make during that time. Below are the rate limits for all of our models when accessed on the AI21 Platform via our SDK or REST endpoints. If you require a higher limit for your particular use case, please don't hesitate to get in touch with us at [sales@ai21.com](mailto:sales@ai21.com). ### Cloud-based services Cloud providers have their own rate limits. For instance, Amazon SageMaker rate limits are determined by the instance that you deploy to hold the model. Amazon Bedrock has their own pricing and rate limits for AI21 model usage. See your cloud provider's documentation for details. ## Foundation models Foundation models have usage limits per second (RPS) and per minute (RPM): | Foundation Model | RPS | RPM | | ---------------- | --- | --- | | Jamba Large | 10 | 200 | | Jamba Mini | 10 | 200 | *** # Authentication Source: https://docs.ai21.com/reference/authentication All API requests must include an `Authorization` header \ with a **Bearer token** for authentication. To authenticate: 1. Use your API key as the token. 2. Include it in the request header as shown below: **Header format:**\ Authorization: Bearer \ Replace `` with your actual key.\ \ See the [Create an API Key guide](https://docs.ai21.com/docs/create-api-key) for step-by-step instructions. # Introduction Source: https://docs.ai21.com/reference/introduction The AI21 API reference provides the technical details you need to authenticate, send requests, and interpret responses when working with AI21’s APIs.\ \ It covers multiple products such as our: Jamba Family of Open Models, AI21 Maestro, which is AI21 Maestro is a dynamic planning system that determines the optimal sequence of actions to solve a given task during inference time.\ \ To get started, visit the [Authentication](https://docs.ai21.com/reference/authentication) page and review the endpoint-specific reference sections in the navigation menu.\ \ If you have any questions, feel free to reach out to our support team via [**email**](mailto:support@ai21.com) or click the chat icon in the lower right corner. # Chat request Source: https://docs.ai21.com/reference/jamba-1-6-api-ref POST https://api.ai21.com/studio/v1/chat/completions ## Overview The Jamba API provides access to a set of instruction-following chat models. It describes the details for interacting with the chat model via the API endpoint and provides specifications for request and response structures. *** ## Request body The name of the model to use.\ You can call our model without specifying a version by using the following model names: * `jamba-large` * `jamba-mini` For more information on the available model versions, [click here](/docs/jamba-foundation-models). A list of messages representing the conversation history. The structure of the message object depends on the type: An initial system message is optional but recommended to set the tone of the chat. The role of the entity that is creating the message. The content of the message. Input provided by the user. The role of the entity that is creating the message, in this case the user. The content of the message. Response generated by the model. Include this in your request to provide context for future answers. The role of the entity that is creating the message, in this case the assistant. The content of the message. The function calls generated by the model, such as tool invocations. The id of the tool call. The type of tool. The function invoked by the model. The name of the function. The parameters of the function as a JSON schema. Contains the output of a tool. Add the function output for user-implemented tools to enable a user-friendly model response. If included, ensure an assistant message with a tool\_calls entry with a matching id exists. The role of the entity that is creating the message, in this case the tool. The content of the message. The message is a response to this tool call. A list of tools that the model can use when generating a response.\ Currently, the only function type tools are supported. The type of tool. Currently, the only supported value is "function". Describes a function to call. Currently, all functions must be described by the user; there are no built-in functions. An example function template is given below. The name of the function. Provide a complete description of what the function does, what it returns, and any limitations. Each function parameter has a name, a type ("string", "integer", "float", "array", "boolean", or "enum"), and a description. The document parameter accepts a list of objects, each containing multiple fields. The content of this "document". Key-value pairs describing the document: Type of metadata, like 'author', 'date', 'url', etc. Should be things the model understands. Value of the metadata. An object defining the output format required from the model.\ Setting it to `{ "type": "json_object" }` activates JSON mode, ensuring the generated message adheres to valid JSON structure. The maximum number of tokens the model can generate in its response.\ For Jamba models, the maximum allowed value is 4096 tokens. Controls the variety of responses provided—a higher value results in more diverse answers.\ **Default:** 0.4, **Range:** 0.0–2.0\ [More information](https://ai21-demo.mintlify.app/v4.2/docs/large-language-models) Limit the pool of next tokens in each step to the top N percentile of possible tokens, where 1.0 means the pool of all possible tokens, and 0.01 means the pool of only the most likely next tokens. \ **Default**: 1.0, **Range**: 0 \<= value \<=1.0\ [More information](/v4.2/docs/large-language-models) End the message when the model generates one of these strings. The stop sequence is not included in the generated message. Each sequence can be up to 64K long, and can contain newlines as `n` characters. * **Single stop string with a word and a period**: "monkeys." * **Multiple stop strings and a newline**: \["cat", "dog", " .", "####", "\n"] How many chat responses to generate. *Default:1, Range: 1 – 16.* \ **Notes**: * If `n > 1`, setting `temperature = 0` will fail because all answers are guaranteed to be duplicates. * `n` must be 1 when `stream = True` Stream results one token at a time using server-sent events. Useful for long results to avoid long wait times. If `True`, `n` must be 1. Must be `False` if using `tools`. ```python Python theme={"system"} from ai21 import AI21Client from ai21.models.chat import ChatMessage messages = [ ChatMessage(role="user", content="Hello how are you?"), ] client = AI21Client() client.chat.completions.create( messages=messages, model="jamba-large", max_tokens=1024, ) ``` ```javascript JavaScript theme={"system"} import { AI21 } from 'ai21'; const client = new AI21({ apiKey: process.env.AI21_API_KEY, // You can also hardcode your API key here }); const response = await client.chat.completions.create({ model: 'jamba-large', messages: [ { role: 'user', content: 'Hello how are you?' } ], max_tokens: 1024 }); console.log(response); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/chat/completions", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "{\n" . " \"model\": \"jamba-large\",\n" . " \"messages\": [\n" . " {\n" . " \"role\": \"user\",\n" . " \"content\": \"Hello how are you?\"\n" . " }\n" . " ],\n" . " \"max_tokens\": 1024\n" . "}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json", "Authorization: Bearer YOUR_API_KEY" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; ``` ```bash cURL theme={"system"} curl https://api.ai21.com/studio/v1/chat/completions \ --header "Authorization: Bearer $AI21_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "jamba-large", "max_tokens": 1024, "messages": [ {"role": "user", "content": "Hello, how are you?"} ] }' ``` ```go Go theme={"system"} package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://api.ai21.com/studio/v1/chat/completions" payload := strings.NewReader("{\n" + " \"model\": \"jamba-large\",\n" + " \"messages\": [\n" + " {\n" + " \"role\": \"user\",\n" + " \"content\": \"Hello how are you?\"\n" + " }\n" + " ],\n" + " \"max_tokens\": 1024\n" + "}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") req.Header.Add("Authorization", "Bearer YOUR_API_KEY") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) ``` ```java Java theme={"system"} import kong.unirest.HttpResponse; import kong.unirest.Unirest; public class AI21Chat { public static void main(String[] args) { HttpResponse response = Unirest.post("https://api.ai21.com/studio/v1/chat/completions") .header("Content-Type", "application/json") .header("Authorization", "Bearer YOUR_API_KEY") .body("{\n" + " \"max_tokens\": 1024,\n" + " \"messages\": [\n" + " {\n" + " \"role\": \"user\",\n" + " \"content\": \"Hello, how are you?\"\n" + " }\n" + " ],\n" + " \"model\": \"jamba-large\"\n" + "}") .asString(); System.out.println(response.getStatus()); System.out.println(response.getBody()); } } ``` ```json JSON theme={"system"} { "model": "jamba-large", "messages": [ { "role": "user", "content": "Hello how are you?" } ], "max_tokens": 1024 } ``` # Chat response Source: https://docs.ai21.com/reference/jamba-api-response ## Response details ### Non-streaming results A successful non-streamed response includes the following members: Unique ID for each request (not message). Same ID for all responses in a streaming response. One or more responses, depending on the `n` parameter from the request. Each response includes the following members. Zero-based index of the message in the list of messages. Note that this might not correspond with the position in the response list. The message generated by the model. Includes two fields: `role` and `content`. Tool calls only occur if a tools parameter was specified in the request. These tool calls apply solely to the current message, and returned values should be added to the message thread in both the assistant message tool\_calls fields and the tool message. ID of the tool call, generated by the model. The type of tool called. Currently the only possible value is "function". The invoked function. The name of the function, which you specified in your request. A JSON object containing the function's parameters and values. Why the message ended. The response ended naturally as a complete answer (due to end-of-sequence token) or because the model generated a stop sequence provided in the request. The response ended by reaching max\_tokens. The token counts for this request. Per-token billing is based on the prompt token and completion token counts and rates. Number of tokens in the prompt for this request. The prompt token contains the entire message history and extra tokens for combining messages, proportional to the number of messages. Number of tokens in the response message. prompt\_tokens and completion\_tokens. ### Streamed results Setting `stream = true` in the request will return a stream of messages, each containing one token. You can read more about streaming calls using the [SDK](https://github.com/AI21Labs/ai21-python/blob/main/README.md#Streaming). The final message will be `data: [DONE]`. All other messages will have `data` set to a JSON object with the following fields: An object containing either an object with the following members, or the string "DONE" for the last message. Unique ID for each request (not message). Same ID for all streaming responses. An array with one object containing the following fields: Always zero. * The first message in the stream will be an object set to `{"role":"assistant"}`. * Subsequent messages will have an object `{"content": **token**}` with the generated token. Why the message ended. The last message includes this field, which shows the total token counts for the request. Per-token billing is based on the prompt token and completion token counts and rates. When present, it contains a null value except for the last chunk which contains the token usage statistics for the entire request. Number of tokens in the prompt for this request. The prompt token contains the entire message history and extra tokens for combining messages, proportional to the number of messages. Number of tokens in the response message. prompt\_tokens and completion\_tokens. `usage` will be `null` except for the last chunk which contains the token usage statistics for the entire request. ```python Python (Non-streaming results) theme={"system"} import asyncio from ai21 import AsyncAI21Client from ai21.models.chat import ChatMessage messages = [ChatMessage(content="What is the meaning of life?", role="user")] client = AsyncAI21Client() async def main(): response = await client.chat.completions.create( messages=messages, model="jamba-large", stream=True, ) async for chunk in response: print(chunk.choices[0].delta.content, end="") asyncio.run(main()) ``` ```python Python (Streamed results) theme={"system"} from ai21 import AI21Client from ai21.models.chat import ChatMessage messages = [ChatMessage(content="What is the meaning of life?", role="user")] client = AI21Client() response = client.chat.completions.create( messages=messages, model="jamba-large", stream=True, ) for chunk in response: print(chunk.choices[0].delta.content, end="") ``` *** ## Error Codes 500 - Internal Server Error\ 429 - Too Many Requests (You are sending requests too quickly.)\ 503 - Service Unavailable (The engine is currently overloaded, please try again later)\ 401 - Unauthorized (Incorrect API key provided/Invalid Authentication)\ 403 - Access Denied\ 422 - Unprocurable Entity (Request body is malformed) *** # Create run Source: https://docs.ai21.com/reference/maestro-create-run POST https://api.ai21.com/studio/v1/maestro/runs ## Request body 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. 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. The textual content of the message. A high\_level instruction that defines AI21 Maestro's overall behavior, role, opreating systems and response style throughout the run.\ \ Common use cases include:\ **Degining identity**: e.g "You are an expert financial analyst". \ **Providing context**: e.g "Today's date is November 10, 2025". \ **Guiding interactions**: e.g "if the user's question is vague, as a clatifying question before answering". **Deciding whether to use** `requirements` or `system_prompt`\ \ To avoid conflicts and ensure predictable behavior, always prefer using `requirements` for output conditions, and make sure they don’t contradict the `system_prompt`. `system_prompt` defines the agent’s identity, tone, and core reasoning principles. It shapes how Maestro behaves throughout the entire run. `requirements`, on the other hand, specify the exact conditions the output must satisfy. 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. The requirement's name, which allows users to reference it in their applications later. 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. 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 requirements** Conflicts may reduce run quality or prevent fulfillment. 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. The string has to be `mcp`. Unique name for the MCP server within the session. Fully qualified URL of the MCP server endpoint. Authentication headers (e.g., bearer tokens). 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. The string has to be `http`. Describes the callable function interface of the tool. A unique identifier for the tool. Should clearly reflect the action it performs. An explanation of what the tool does and when it should be used. A JSON Schema describing the input parameters this tool accepts.\ Each parameter should preferably include a description. Defines how to construct the HTTP request. The endpoint URL the tool should call. HTTP headers to include in the request, typically used for authorization or content-type declarations. Only `POST`requests are currently supported. \ For more information on how the request is made, see the following example. **JSON Example** ```json theme={"system"} { "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. The string has to be `file_search`. Restrict file search to files with these labels.\ If not provided, search is not restricted by label. 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. The string has to be `web_search`. 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. 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**](https://studio.ai21.com/v2?tab=third_party_models). 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. 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. 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. 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](/reference/run-object) ```python Python theme={"system"} 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") ``` ```javascript Javascript theme={"system"} // TypeScript example using AI21 Labs TypeScript SDK // Install deps first: npm i ai21 ts-node typescript // If the import path differs in your SDK version, adjust it per the SDK docs. import { AI21} from "ai21"; const apiKey = process.env.AI21_API_KEY; if (!apiKey) { throw new Error("AI21_API_KEY is not set. Please export it as an environment variable."); } const client = new AI21({ apiKey, }); const body = { input: [ { role: "user", content: "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/", ], }, ], budget: "low", include: ["requirements_result", "data_sources"], }; async function main() { const result = await client.beta.maestro.runs.createAndPoll(body, { interval: 1000, timeout: 100000 }); console.log(JSON.stringify(result, null, 2)); } main().catch((err) => { console.error(err); process.exit(1); }); ``` ```php PHP theme={"system"} 'https://api.ai21.com/studio/v1/maestro/runs', CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => true, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => array( 'Authorization: Bearer YOUR_API_KEY_HERE', 'Content-Type: application/json' ), CURLOPT_POSTFIELDS => '{ "input": [ { "role": "user", "content": "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/" ] } ] }' )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` ```bash cURL theme={"system"} curl --location --request POST 'https://api.ai21.com/studio/v1/maestro/runs' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "input": [ { "role": "user", "content": "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/" ] } ], "budget": "medium", "include": ["requirements_result", "data_sources"] }' ``` ```java Java theme={"system"} HttpResponse response = Unirest.post("https://api.ai21.com/studio/v1/maestro/runs") .header("Content-Type", "application/json") .body("{\n \"input\": [\n {\n \"role\": \"\",\n \"content\": \"\"\n }\n ],\n \"requirements\": [\n {\n \"name\": \"\",\n \"description\": \"\"\n }\n ],\n \"tool_resources\": {\n \"file_search\": {\n \"labels\": [\n \"\"\n ],\n \"file_ids\": [\n \"\"\n ]\n },\n \"web_search\": {\n \"urls\": [\n \"\"\n ]\n }\n },\n \"models\": [\n \"\"\n ],\n \"budget\": \"\",\n \"include\": [\n \"\"\n ],\n \"response_language\": {}\n}") .asString(); ``` ```json JSON theme={"system"} { "input": [ { "role": "user", "content": "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/" ] } ], "budget": "medium", "include": ["requirements_result", "data_sources"] } ``` # File Library Source: https://docs.ai21.com/reference/manage-library-ref ## Overview The library can hold an unlimited number of files, but a maximum of 1GB of files. Files support the following metadata: The unique identifier of the file, generated by AI21. The name of the file specified by you. An arbitrary file-path-like string you can assign to indicate the content of a file. The type of the file. The size of the file in bytes. The labels associated with the file. You can apply arbitrary string labels to your files and limit queries to files with one or more labels. Similar to paths, but labels do not prefix match. Labels are case-sensitive. The public URL of the file, specified by you. This URL is not validated by AI21 or used in any way. It is strictly a piece of metadata that you can optionally attach to a file. The identifier of the user who uploaded the file. The date when the file was uploaded. The last update date of the file in the library. Where was the file uploaded from. The status of the file in the library. | Value | Description | | -------------------------------------- | ------------------------------------------------------------------------- | | `DB_RECORD_CREATED` | The file record has been created in the database. | | `UPLOADED` | The file has been uploaded and is being processed. | | `UPLOAD_FAILED` | The file upload has failed. | | `PROCESSING` | The file is currently being processed. | | `PROCESSED` | The file has been processed and is ready for use. | | `FILE_DOWNLOAD_FAILED` | The file download has failed. | | `PARSING_FAILED` | Parsing the file has failed. | | `SEGMENTATION_FAILED` | File segmentation has failed. | | `EMBEDDING_FAILED` | Embedding the file segments has failed. | | `VECTORS_DB_UPSERT_FAILED` | Updating the vector database has failed. | | `VECTOR_DATA_UPLOAD_TO_STORAGE_FAILED` | Uploading the file’s embedding vectors to the storage has failed. | | `SEGMENTS_UPLOAD_TO_DB_FAILED` | Uploading the file’s segments to the database has failed. | | `PROCESSING_FAILED` | The processing of the file has failed. | | `DELETION_FAILED` | The deletion of the file has failed. | | `RE_PROCESS_CANDIDATE` | The file is a candidate for re-processing. | | `RE_PROCESSING` | The file is currently being re-processed. | | `DELETING` | The file is in the process of being deleted. | | `DELETED_FROM_VECTOR_DB` | The file has been deleted from the vector database. | | `DELETE_REQUEST_DURING_PROCESSING` | A delete request was received during processing. | | `MAX_RETRIES_REACHED` | The maximum number of retries has been reached, the operation has failed. | #### Filtering file results When you create or update a file, you can optionally apply `path` and/or `label` values to a file. You can later search, query, or list files based on matching paths or labels. This can be useful to query subsets of documents. For example, you can assign a path of either `/financial/USA` or `/financial/UK` to certain documents and later query only US financial documents, only UK financial documents, or query all financial documents by specifying `/financial/` as the path. # Delete file Source: https://docs.ai21.com/reference/manage-library-ref/delete-file DELETE https://api.ai21.com/studio/v1/library/files/{file_id} Delete the specified file from the library. **Restrictions**: Files in `PROCESSING` status cannot be deleted. Attempts to delete such files will result in a 422 error. ## Responses ### Response 200 Successful deletion. No body content. ### Response 422 File by this ID does not exist. ```python Python theme={"system"} from ai21 import AI21Client # Initialize the client client = AI21Client( api_key="your_api_key_here" # or use environment variable AI21_API_KEY ) # Delete a file by its ID try: client.library.files.delete("your-file-id-here") print("File deleted successfully") except Exception as e: print(f"Error deleting file: {e}") ``` ```javascript JavaScript theme={"system"} const axios = require('axios'); const apiKey = 'your_api_key_here'; const fileId = 'your-file-id-here'; axios.delete(`https://api.ai21.com/studio/v1/library/files/${fileId}`, { headers: { 'Authorization': `Bearer ${apiKey}` } }) .then(() => console.log('File deleted successfully')) .catch(error => console.error('Error deleting file:', error.message)); ``` ```php PHP theme={"system"} ``` ```go Go theme={"system"} package main import ( "fmt" "net/http" ) func main() { apiKey := "your_api_key_here" fileId := "your-file-id-here" req, _ := http.NewRequest("DELETE", "https://api.ai21.com/studio/v1/library/files/"+fileId, nil) req.Header.Set("Authorization", "Bearer "+apiKey) client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Println("Error deleting file:", err) } else { fmt.Println("File deleted successfully") resp.Body.Close() } } ``` ```bash cURL theme={"system"} curl -X DELETE https://api.ai21.com/studio/v1/library/files/your-file-id-here \ -H "Authorization: Bearer your_api_key_here" ``` ```java Java theme={"system"} import okhttp3.*; public class DeleteFile { public static void main(String[] args) throws Exception { String apiKey = "your_api_key_here"; String fileId = "your-file-id-here"; OkHttpClient client = new OkHttpClient(); Request request = new Request.Builder() .url("https://api.ai21.com/studio/v1/library/files/" + fileId) .delete() .addHeader("Authorization", "Bearer " + apiKey) .build(); try (Response response = client.newCall(request).execute()) { if (response.isSuccessful()) { System.out.println("File deleted successfully"); } else { System.out.println("Error deleting file: " + response.message()); } } } } ``` # Get file download link Source: https://docs.ai21.com/reference/manage-library-ref/get-file-download-link GET https://api.ai21.com/studio/v1/library/files/{file_id}/download Retrieve a signed URL you can use to download a file’s contents from your workspace library. ## Path parameters The unique ID of the file to download. ## Response 200 Returns a string containing the signed download URL for the requested file. Example response: ```json theme={"system"} "https://storage.ai21.com/files/file_123abc/download?token=xyz" ``` ### Response 422 No matching ID is found. ```python Python theme={"system"} import requests file_id = "your_file_id_here" url = f"https://api.ai21.com/studio/v1/library/files/{file_id}/download" headers = {"Authorization": "Bearer your_api_key_here"} response = requests.get(url) if response.status_code == 200: print("Download URL:", response.text) else: print("Error:", response.status_code, response.text) ``` ```javascript JavaScript theme={"system"} const file_id = "your_file_id_here"; fetch(`https://api.ai21.com/studio/v1/library/files/${file_id}/download`, { method: "GET", headers: { "Authorization": "Bearer YOUR_API_KEY", }, }) .then(res => res.text()) .then(link => console.log("Download URL:", link)) .catch(err => console.error("Error:", err)); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/library/files/$file_id/download", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer YOUR_API_KEY" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo "Download URL: " . $response; } ``` ```go Go theme={"system"} package main import ( "fmt" "io/ioutil" "net/http" ) func main() { fileID := "your_file_id_here" url := fmt.Sprintf("https://api.ai21.com/studio/v1/library/files/%s/download", fileID) req, err := http.NewRequest("GET", url, nil) if err != nil { fmt.Println("Error creating request:", err) return } req.Header.Add("Authorization", "Bearer YOUR_API_KEY") client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Println("Error sending request:", err) ``` ```cURL theme={"system"} curl -X GET "https://api.ai21.com/studio/v1/library/files/{file_id}/download" \ -H "Authorization: Bearer YOUR_API_KEY" ``` # Get workspace file Source: https://docs.ai21.com/reference/manage-library-ref/get-workspace-files GET https://api.ai21.com/studio/v1/library/files/{file_id} Retrieve metadata about a specific file. The `file_id` is generated by AI21 when you upload the file. ## Path Parameters The unique ID of the file to retrieve. ## Responses ### Response 200 A successful response returns metadata about the requested file. The file ID. The file name. File size in bytes. File creation timestamp. Labels assigned to the file Error code, if any. Error message, if any. ### Response 422 No matching ID is found. ```python Python theme={"system"} from ai21 import AI21Client client = AI21Client() # Replace with your actual file_id file_id = "file_123abc" # Retrieve file metadata file_metadata = client.library.files.get(file_id=file_id) print(file_metadata) ``` ```javascript JavaScript theme={"system"} const options = {method: 'GET'}; fetch('https://api.ai21.com/studio/v1/library/files/{file_id}', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/library/files/{file_id}", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```go Go theme={"system"} package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://api.ai21.com/studio/v1/library/files/{file_id}" req, _ := http.NewRequest("GET", url, nil) res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```bash cURL theme={"system"} curl --request GET \ --url https://api.ai21.com/studio/v1/library/files/{file_id} ``` ```java Java theme={"system"} HttpResponse response = Unirest.get("https://api.ai21.com/studio/v1/library/files/{file_id}") .asString(); ``` ```json JSON theme={"system"} { "id": "file_123abc", "name": "customer_data.pdf", "size": 204800, "created_at": "2025-10-20T14:23:11Z", "labels": ["invoices", "Q3"] } ``` # List library files Source: https://docs.ai21.com/reference/manage-library-ref/list-library-files GET https://api.ai21.com/studio/v1/library/files Retrieve a list of documents in the user's library. You can optionally specify a filter to return only files with matching labels. When specifying qualifiers with your request, only files that match all qualifiers will be returned. For example, if you specify `label='financial'` and `status='UPLOADED'`, only files with the label 'financial' **and** status 'UPLOADED' will be returned. ## Request parameters The following optional parameters can be used to filter your results. The full name of the uploaded file, without any path parameters. So: "mydoc.txt", not "/users/benfranklyn/Documents/mydoc.txt". Does not match name substrings, so "doc.txt" does not match "mydoc.txt". Status of the file in the library. Supported values: * `DB_RECORD_CREATED` * `UPLOADED` * `UPLOAD_FAILED` * `PROCESSED` * `PROCESSING_FAILED` Return only files with this label. Label matching is case-sensitive, and will not match substrings. By default, the endpoint returns up to 10000 files. Pagination can be controlled using the following parameters: The number of files to skip. The number of files to retrieve (maximum 1,000, default 1,000) ## Responses ### Response 200 A successful response returns an array of file metadata items. ```python Python theme={"system"} import requests url = "https://api.ai21.com/studio/v1/library/files" payload = { "name": "", "status": "", "label": [""], "Pagination": { "offset": 123, "limit": 123 } } headers = {"Content-Type": "application/json"} response = requests.request("GET", url, json=payload, headers=headers) print(response.text) ``` ```javascript JavaScript theme={"system"} const options = { method: 'GET', headers: {'Content-Type': 'application/json'}, body: '{"name":"","path":"","status":"","label":[""],"Pagination":{"offset":123,"limit":123}}' }; fetch('https://api.ai21.com/studio/v1/library/files', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/library/files", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_POSTFIELDS => "{\n \"name\": \"\",\n \"path\": \"\",\n \"status\": \"\",\n \"label\": [\n \"\"\n ],\n \"Pagination\": {\n \"offset\": 123,\n \"limit\": 123\n }\n}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); ``` ```go Go theme={"system"} package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://api.ai21.com/studio/v1/library/files" payload := strings.NewReader("{\n \"name\": \"\",\n \"path\": \"\",\n \"status\": \"\",\n \"label\": [\n \"\"\n ],\n \"Pagination\": {\n \"offset\": 123,\n \"limit\": 123\n }\n}") req, _ := http.NewRequest("GET", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```bash cURL theme={"system"} curl --request GET \ --url https://api.ai21.com/studio/v1/library/files \ --header 'Content-Type: application/json' \ --data '{ "name": "", "path": "", "status": "", "label": [ "" ], "Pagination": { "offset": 123, "limit": 123 } ``` ```java Java theme={"system"} HttpResponse response = Unirest.get("https://api.ai21.com/studio/v1/library/files") .header("Content-Type", "application/json") .queryString("name", "") .queryString("path", "") .queryString("status", "") .queryString("label", "") .queryString("offset", 123) .queryString("limit", 123) .asString(); ``` # Update file Source: https://docs.ai21.com/reference/manage-library-ref/update-file PUT https://api.ai21.com/studio/v1/library/files/{file_id} Update the specified parameters of a specific document in the user's library. This operation currently supports updating the publicUrl and labels parameters. ## Request body The updated public URL of the document. The updated labels associated with the file. Separate multiple labels with commas. ## Responses If the update is successful, the server will return an HTTP status code 200 with no body content. If the document ID does not exist, a 422 error message will be returned. ```python Python theme={"system"} from ai21 import AI21Client client = AI21Client() file_id = client.library.files.create( labels=["label1", "label2"], public_url="www.example.com", ) uploaded_file = client.library.files.get(file_id) ``` ```javascript JavaScript theme={"system"} const options = { method: 'PUT', headers: {'Content-Type': 'application/json'}, body: '{"publicUrl":"","labels":[""]}' }; fetch('https://api.ai21.com/studio/v1/library/files/{file_id}', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err)); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/library/files/{file_id}", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "PUT", CURLOPT_POSTFIELDS => "{\n \"publicUrl\": \"\",\n \"labels\": [\n \"\"\n ]\n}", CURLOPT_HTTPHEADER => [ "Content-Type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```go Go theme={"system"} package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://api.ai21.com/studio/v1/library/files/{file_id}" payload := strings.NewReader("{\n \"publicUrl\": \"\",\n \"labels\": [\n \"\"\n ]\n}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```bash cURL theme={"system"} curl --request PUT \ --url https://api.ai21.com/studio/v1/library/files/{file_id} \ --header 'Content-Type: application/json' \ --data '{ "publicUrl": "", "labels": [ "" ] }' ``` ```java Java theme={"system"} HttpResponse response = Unirest.put("https://api.ai21.com/studio/v1/library/files/{file_id}") .header("Content-Type", "application/json") .body("{\n \"publicUrl\": \"\",\n \"labels\": [\n \"\"\n ]\n}") .asString(); ``` # Upload workspace files Source: https://docs.ai21.com/reference/manage-library-ref/upload-workspace-files POST https://api.ai21.com/studio/v1/library/files Upload files to use. You can assign metadata to your files to limit searches to specific files by file metadata. There is no bulk upload method; files must be loaded one at a time. * **Max number of files:** No limit. The playground limits bulk uploads to 50 files per request. * **Max total library size:** 1 GB. * **Max file size:** 5 MB. * **Supported file types:** PDF, DocX, HTML, TXT, Markdown. ## Request body fields Raw file bytes. Every uploaded file must have a unique file name. Specifying file labels will find only files with *both* the specified name and label. Arbitrary string labels that describe the contents of this file. Labels are case-sensitive. Specifying labels or labels + name will return only files with both any of the specified labels and the specified name. A public URL associated with the file, if any. Only used as metadata, to indicate the location of the source file. For example, if implementing a search engine against a website, specifying a URL for each uploaded file is a simple way to present the link to the file in the search results presented to the user. ## Responses ### Response 200 A unique identifier for the uploaded file. Use this later to request, modify, or delete the file. You don't need to store the value though, as it is returned along with all file information in a GET /files request. **Type:** UUID. Example: da13301a-14e4-4487-aa2f-cc6048e73cdc // file-uuid ### Error: Unsupported document type 422 Error message: ```json theme={"system"} { "detail": "Invalid file type: image/png. Supported file types are: text/plain, text/html, application/docx, application/pdf" } ``` ```json 200 theme={"system"} { "id": "da13301a-14e4-4487-aa2f-cc6048e73cdc", } ``` ```json 422 Unsupported document type theme={"system"} { "detail": "Invalid file type: image/png. Supported file types are: text/plain, text/html, application/docx, application/pdf" } ``` ```python Python theme={"system"} rom ai21 import AI21Client client = AI21Client() # Option 1: Upload a local file file_from_disk = client.library.files.create( labels=["label1", "label2"], ) # Option 2: Upload a file from a public URL file_from_url = client.library.files.create( public_url="https://www.example.com/file.pdf", labels=["label1", "label2"], ) # Retrieve uploaded file metadata (example) uploaded_file = client.library.files.get(file_from_disk.id) ``` ```javascript JavaScript theme={"system"} const payload = { path: "docs/file-from-url.pdf", labels: ["label1", "label2"], publicUrl: "https://www.example.com/file.pdf" }; fetch("https://api.ai21.com/studio/v1/library/files", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify(payload) }) .then(response => response.json()) .then(response => console.log(response)) .catch(error => console.error(error)); ``` ```php PHP theme={"system"} "docs/file-from-url.pdf", "labels" => ["label1", "label2"], "publicUrl" => "https://www.example.com/file.pdf" ]); $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.ai21.com/studio/v1/library/files", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => $payload, CURLOPT_HTTPHEADER => [ "Authorization: Bearer YOUR_API_KEY", "Content-Type: application/json" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```go Go theme={"system"} package main import ( "bytes" "encoding/json" "fmt" "io/ioutil" "net/http" ) func main() { url := "https://api.ai21.com/studio/v1/library/files" payload := map[string]interface{}{ "path": "docs/file-from-url.pdf", "labels": []string{"label1", "label2"}, "publicUrl": "https://www.example.com/file.pdf", } jsonData, err := json.Marshal(payload) if err != nil { panic(err) } req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData)) if err != nil { panic(err) } req.Header.Add("Content-Type", "application/json") req.Header.Add("Authorization", "Bearer YOUR_API_KEY") client := &http.Client{} res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { panic(err) ``` ```bash cURI theme={"system"} curl --request POST \ --url https://api.ai21.com/studio/v1/library/files \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data '{ "path": "docs/file-from-url.pdf", "labels": ["label1", "label2"], "publicUrl": "https://www.example.com/file.pdf" }' ``` ```java Java theme={"system"} HttpResponse response = Unirest.post("https://api.ai21.com/studio/v1/library/files") .header("Content-Type", "application/json") .header("Authorization", "Bearer YOUR_API_KEY") .body("{" + "\"path\": \"docs/file-from-url.pdf\"," + "\"labels\": [\"label1\", \"label2\"]," + "\"publicUrl\": \"https://www.example.com/file.pdf\"" + "}") .asString(); ``` # Retrieve run status Source: https://docs.ai21.com/reference/retrieve-run GET https://api.ai21.com/studio/v1/maestro/runs/{run_id} Retrieves the status of the run execution based on its ID. The status can be `completed`, `failed`, or `in_progress`. ## Path parameters A unique identifier of the run you wish to retrieve. ## Returns The [run object](/reference/run-object) matches the specified ID. ```python Python theme={"system"} from ai21 import AI21Client client = AI21Client(api_key="your-api-key") # Replace with your API key run_id = "your_run_id_here" # Retrieve the Maestro run by ID retrieved_run = client.beta.maestro.runs.retrieve(run_id) print(retrieved_run) ``` ```javascript JavaScript theme={"system"} const runId = "your_run_id_here"; fetch(`https://api.ai21.com/studio/v1/maestro/runs/${runId}`, { method: "GET", headers: { "Authorization": "Bearer your-api-key", "Content-Type": "application/json" } }) .then(res => res.json()) .then(data => console.log(data)) .catch(err => console.error(err)); ``` ```php PHP theme={"system"} "https://api.ai21.com/studio/v1/maestro/runs/$run_id", CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "Authorization: Bearer your-api-key", "Content-Type: application/json" ], ]); $response = curl_exec($curl); $error = curl_error($curl); curl_close($curl); if ($error) { echo "cURL Error: " . $error; } else { echo $response; } ``` ```go Go theme={"system"} package main import ( "fmt" "io/ioutil" "net/http" ) func main() { runID := "your_run_id_here" url := fmt.Sprintf("https://api.ai21.com/studio/v1/maestro/runs/%s", runID) req, err := http.NewRequest("GET", url, nil) if err != nil { panic(err) } req.Header.Add("Authorization", "Bearer your-api-key") req.Header.Add("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { panic(err) } fmt.Println("Status:", res.Status) fmt.Println("Response:", string(body)) } ``` ```bash cURL theme={"system"} curl --request GET \ --url https://api.ai21.com/studio/v1/maestro/runs/{run_id} \ --header "Authorization: Bearer your-api-key" \ --header "Content-Type: application/json" ``` ```java Java theme={"system"} String runId = "your_run_id_here"; HttpResponse response = Unirest.get("https://api.ai21.com/studio/v1/maestro/runs/" + runId) .header("Authorization", "Bearer your-api-key") .header("Content-Type", "application/json") .asString(); System.out.println(response.getBody()); ``` # Run object Source: https://docs.ai21.com/reference/run-object ## Run Object ID of the task that a user can use for polling its status any of `completed`, `failed`, `in_progress` The final result object, may vary based on task type. Contains the retrieved contextual information used during the run.\ Includes optional `web_search`, `file_search`, and `tool_calls` result arrays. A list of web search results retrieved during the run. The URL address returned by the search. The extracted text from the URL that was used as context. Relevancy score from 0 to 1. A list of file search results retrieved during the run. The ID of the file that contains relevant text. The name of the retrieved file. The retrieved text segment.\ When `null`, it indicates that the entire file was retrieved. Relevancy score from 0 to 1. The order of the retrieved segments when multiple results come from the same file. A list of tool call results executed during the run. The name of the tool that was called. The type of tool invoked: `"mcp"` or `"http"`. When the tool belongs to an MCP server, indicates which server provided the tool. A JSON object representing the parameters sent to the tool. The JSON response returned by the tool. Detailed results for each requirement. A value between 0 and 1 indicating how well the requirement was fulfilled. A textual reason what happened - one of `Perfect score` or `Budget exhausted`. A list of search requirement shown in the report. The name provided (or default name) of the requirement requested to be fulfilled When a user provides the requirement explicitly, it's what the user provided A value between 0 and 1 indicating how well the requirement was fulfilled. A textual reason about why the requirement didn't reach a perfect score. An object that provides details about why the run failed. Returns `null` if the run completed successfully. A descriptive message explaining the reason for the failure. The example below shows a fully completed run object, including the `requirements_result`, `data_sources`, and `error` fields. These fields are **not included by default** and will only appear in the response if you explicitly request them using the include parameter. For details on how to use this parameter, see the `include` [parameter documentation](https://docs.ai21.com/reference/endpoints#param-include). ### Example: ```json theme={"system"} { "id": "dba286ef-5067-4c6e-b215-5483500da8df", "status": "completed", "result": "- example 1\n- example 2\n- example 3", "requirements_result": { "score": 1, "finish_reason": "Perfect result achieved", "requirements": [ { "name": "bullets", "description": "Return a bulleted list where each field is a bullet", "is_mandatory": false, "score": 1, "reason": "None" } ] }, "data_sources": { "web_search": [ { "id": "0686b7a3-6cb6-7128-8000-146778a91763", "text": "web search result text", "url": "https://example.com", "score": 0.01461567 } ], "file_search": [ { "text": "file search result text", "file_id": "aa50de3e-1624-4e9f-a6f4-488a1aa16759", "file_name": "example.pdf", "score": 0.7331293 } ] }, "error": { "message": "The run failed due to an unexpected server error." } } ```