​
Run Object

​
id
string
ID of the task that a user can use for polling its status
​
status
string
any of completed, failed, in_progress
​
result
object | null
The final result object, may vary based on task type.
​
data_sources
object | null
Specifies the data sources used to retrieve contextual information for a run. Contains optional web_search and file_search results.
​
file_search
object
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a 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
object
When provided, this object defines filters that AI21 Maestro will apply whenever it performs a 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.
​
requirements_result
object | null
Detailed results for each requirement.
​
error
object | null
An object that provides details about why the run failed. Returns null if the run completed successfully.
​
message
string
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.

​
Example:

{
  "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."
  }
}