Run object

string

ID of the task that a user can use for polling its status

string

any of completed, failed, in_progress

object | null

The final result object, may vary based on task type.

object | null

Contains the retrieved contextual information used during the run.
Includes optional web_search, file_search, and tool_calls result arrays.

Show properties

object[] | null

A list of web search results retrieved during the run.

Show properties

string

The URL address returned by the search.

string

The extracted text from the URL that was used as context.

number

Relevancy score from 0 to 1.

object[] | null

A list of file search results retrieved during the run.

Show properties

string

The ID of the file that contains relevant text.

string

The name of the retrieved file.

string | null

The retrieved text segment.
When null, it indicates that the entire file was retrieved.

number

Relevancy score from 0 to 1.

integer

The order of the retrieved segments when multiple results come from the same file.

object[] | null

A list of tool call results executed during the run.

Show properties

string

The name of the tool that was called.

string

The type of tool invoked: "mcp" or "http".

string | null

When the tool belongs to an MCP server, indicates which server provided the tool.

object

A JSON object representing the parameters sent to the tool.

object

The JSON response returned by the tool.

object | null

Detailed results for each requirement.

Show properties

float | null

A value between 0 and 1 indicating how well the requirement was fulfilled.

string | null

A textual reason what happened - one of Perfect score or Budget exhausted.

object[]

A list of search requirement shown in the report.

Show properties

string | null

The name provided (or default name) of the requirement requested to be fulfilled

string | null

When a user provides the requirement explicitly, it’s what the user provided

float | null

A value between 0 and 1 indicating how well the requirement was fulfilled.

string | null

A textual reason about why the requirement didn’t reach a perfect score.

object | null

An object that provides details about why the run failed. Returns null if the run completed successfully.

Show properties

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

Using the APIs

AI21 Maestro

Foundation Models

File Library Management

Run object

Run Object

Example:

​Run Object

​Example:

Run Object

Example: