> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai21.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run object

## Run Object

<ParamField body="id" type="string">
  ID of the task that a user can use for polling its status
</ParamField>

<ParamField body="status" type="string">
  any of `completed`, `failed`, `in_progress`
</ParamField>

<ParamField body="result" type="object | null">
  The final result object, may vary based on task type.
</ParamField>

<ParamField body="data_sources" type="object | null">
  Contains the retrieved contextual information used during the run.\
  Includes optional `web_search`, `file_search`, and `tool_calls` result arrays.

  <Accordion title="Show properties">
    <ParamField body="web_search" type="object[] | null">
      A list of web search results retrieved during the run.

      <Accordion title="Show properties">
        <ParamField body="url" type="string">
          The URL address returned by the search.
        </ParamField>

        <ParamField body="text" type="string">
          The extracted text from the URL that was used as context.
        </ParamField>

        <ParamField body="score" type="number">
          Relevancy score from 0 to 1.
        </ParamField>
      </Accordion>
    </ParamField>

    <ParamField body="file_search" type="object[] | null">
      A list of file search results retrieved during the run.

      <Accordion title="Show properties">
        <ParamField body="file_id" type="string">
          The ID of the file that contains relevant text.
        </ParamField>

        <ParamField body="file_name" type="string">
          The name of the retrieved file.
        </ParamField>

        <ParamField body="text" type="string | null">
          The retrieved text segment.\
          When `null`, it indicates that the entire file was retrieved.
        </ParamField>

        <ParamField body="score" type="number">
          Relevancy score from 0 to 1.
        </ParamField>

        <ParamField body="order" type="integer">
          The order of the retrieved segments when multiple results come from the same file.
        </ParamField>
      </Accordion>
    </ParamField>

    <ParamField body="tool_calls" type="object[] | null">
      A list of tool call results executed during the run.

      <Accordion title="Show properties">
        <ParamField body="tool_name" type="string">
          The name of the tool that was called.
        </ParamField>

        <ParamField body="tool_type" type="string">
          The type of tool invoked: `"mcp"` or `"http"`.
        </ParamField>

        <ParamField body="server_label" type="string | null">
          When the tool belongs to an MCP server, indicates which server provided the tool.
        </ParamField>

        <ParamField body="parameters" type="object">
          A JSON object representing the parameters sent to the tool.
        </ParamField>

        <ParamField body="response" type="object">
          The JSON response returned by the tool.
        </ParamField>
      </Accordion>
    </ParamField>
  </Accordion>
</ParamField>

<ParamField body="requirements_result" type="object | null">
  Detailed results for each requirement.

  <Expandable title="properties">
    <ParamField body="score" type="float | null">
      A value between 0 and 1 indicating how well the requirement was fulfilled.
    </ParamField>

    <ParamField body="finish_reason" type="string | null">
      A textual reason what happened - one of `Perfect score` or `Budget exhausted`.
    </ParamField>

    <ParamField body="requirements" type="object[]">
      A list of search requirement shown in the report.

      <Expandable title="properties">
        <ParamField body="name" type="string | null">
          The name provided (or default name) of the requirement requested to be fulfilled
        </ParamField>

        <ParamField body="description" type="string | null">
          When a user provides the requirement explicitly, it's what the user provided
        </ParamField>

        <ParamField body="score" type="float | null">
          A value between 0 and 1 indicating how well the requirement was fulfilled.
        </ParamField>

        <ParamField body="reason" type="string | null">
          A textual reason about why the requirement didn't reach a perfect score.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="error" type="object | null">
  An object that provides details about why the run failed. Returns `null` if the run completed successfully.

  <Accordion title="Show properties">
    <ParamField body="message" type="string">
      A descriptive message explaining the reason for the failure.
    </ParamField>
  </Accordion>
</ParamField>

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` [<u>parameter documentation</u>](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."
  }
}
```