> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/preparation/parser-auto-detection.md).

# Parser Auto-Detection Results

When the system automatically detects the parser for a knowledge base file, parserAutoDetection in the file response includes the selected parser, reason category, and metrics used for the decision. T

When you upload a file to a knowledge base without specifying `parser` (leaving the parser set to “Auto-detect (default)”), the system selects a parser based on the file's content. In the responses from [List files in a knowledge base](https://docs.maiagent.ai/api/en/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-list) and [Retrieve file details](https://docs.maiagent.ai/api/en/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-retrieve), each file's `parserAutoDetection` reports which parser was selected, why, and the metrics calculated during detection. Use it in your own system to distinguish automatically selected parsers from user-selected parsers and display the reason for the selection.

## Fields <a href="#fields" id="fields"></a>

| Field        | Type   | Description                                                                                                                                                                 |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parser`     | object | The parser selected by auto-detection and currently used for this file. Its fields match `parser` in the file response (`id`, `name`, `provider`, `isTimestampSttProvider`) |
| `reason`     | string | Reason category; see [Reason categories](#reasons)                                                                                                                          |
| `facts`      | object | Metrics calculated during detection; see [Detection metrics](#facts). An empty object `{}` when no metrics are available                                                    |
| `detectedAt` | string | Detection time as a Unix timestamp in milliseconds, represented as a string (see [Field format](https://docs.maiagent.ai/api/en/preparation/conventions.md#field-format))   |

The metrics in `facts` are calculated at detection time and are not recalculated afterward. Reparsing with the same parser does not trigger detection again, so the original metrics and detection time are retained.

### When the result is null <a href="#when-null" id="when-null"></a>

A `null` value for `parserAutoDetection` means that the file's current parser was not selected by auto-detection, or no detection result is available yet:

* A parser was explicitly specified during upload or reparsing (selected by the user).
* “Batch reparse files” was used to replace the automatically selected parser with another parser. Reparsing with the same parser retains the original result.
* “Batch reparse files” was used to switch back to auto-detection (the file's entry explicitly includes `"parser": null`), and the new detection is still queued or incomplete. Once detection finishes, the new result replaces it.
* The file was uploaded before this feature was introduced (existing files are not backfilled).

{% hint style="info" %}
When switching back to auto-detection through [Batch reparse files](https://docs.maiagent.ai/api/en/api-reference/zhi-shi-ku-xin-ban.md#knowledge-bases-files-batch-reparse-partial-update), explicitly include `"parser": null` in the file's entry. If the entry has no `parser` key, the file's parser is not changed, the file is not reparsed, and `parserAutoDetection` remains unchanged. During upload, you can simply omit `parser`.
{% endhint %}

## Response examples <a href="#example" id="example"></a>

The PDF has many scanned pages, so the system selects the Vision parser:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "合約掃描檔.pdf",
  "parser": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Vision Parser",
    "provider": "anthropic",
    "isTimestampSttProvider": false
  },
  "parserAutoDetection": {
    "parser": {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Vision Parser",
      "provider": "anthropic",
      "isTimestampSttProvider": false
    },
    "reason": "scanned",
    "facts": {
      "analyzedPages": 50,
      "partial": true,
      "nonBlankPages": 48,
      "scannedPages": 40,
      "imagePages": 42
    },
    "detectedAt": "1760860800000"
  }
}
```

The user selected a parser during upload:

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "filename": "產品手冊.docx",
  "parserAutoDetection": null
}
```

These examples show only the relevant fields. See each endpoint's response schema for other file fields.

## Reason categories <a href="#reasons" id="reasons"></a>

| `reason`                 | Meaning                                                                                                                                   | `facts`                                                                      |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `scanned`                | The content is mostly scanned pages (PDF or Word), requiring image interpretation                                                         | PDF or Word metrics                                                          |
| `image_pages`            | The PDF has enough pages requiring image interpretation (scanned pages or other pages dominated by images)                                | PDF metrics                                                                  |
| `large_images`           | The Word document contains enough large images in its body                                                                                | Word metrics                                                                 |
| `unmeasurable_images`    | The Word document contains images whose dimensions cannot be measured, so it is treated as requiring image interpretation                 | Word metrics, possibly an empty object                                       |
| `presentation`           | A presentation file (PPTX)                                                                                                                | Empty object                                                                 |
| `no_image_content`       | No pages require image interpretation and there are no large images in the body                                                           | PDF or Word metrics; an empty object for Word files with no images at all    |
| `below_threshold`        | Some pages require image interpretation or the body contains large images, but the threshold for selecting the Vision parser is not met   | PDF or Word metrics                                                          |
| `no_content`             | All PDF pages analyzed are blank                                                                                                          | PDF metrics                                                                  |
| `file_type_not_detected` | Content detection is not performed for this file type (such as legacy PPT presentations); the system uses the default parser for the type | Empty object                                                                 |
| `detection_failed`       | An error occurred during detection; the system uses the default parser for the file type                                                  | Empty object                                                                 |
| `vision_unavailable`     | The content requires image interpretation, but no Vision parser is available; `parser` is the parser actually used                        | Same as the content category (PDF or Word metrics; an empty object for PPTX) |

{% hint style="warning" %}
Detection rules may introduce additional reason categories in the future. Avoid hard-coding logic based only on this table. For an unrecognized `reason`, show a generic description (such as “The system automatically selected a parser based on the file's content”) instead of raising an error or skipping the entire file record.
{% endhint %}

## Detection metrics <a href="#facts" id="facts"></a>

The keys in `facts` vary by file type. As shown above, `facts` is an empty object `{}` for PPTX, Word files with no images at all, file types that do not undergo content detection, and detection failures.

**PDF**

| Key             | Type    | Description                                                                                                                 |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `analyzedPages` | integer | Number of pages examined during detection                                                                                   |
| `partial`       | boolean | Whether only the first pages were examined (`true` when the file exceeds the detection limit, currently the first 50 pages) |
| `nonBlankPages` | integer | Number of nonblank pages among the examined pages                                                                           |
| `scannedPages`  | integer | Number of scanned pages among the examined pages                                                                            |
| `imagePages`    | integer | Number of examined pages requiring image interpretation (including scanned pages)                                           |

**Word (DOCX)**

| Key         | Type    | Description                        |
| ----------- | ------- | ---------------------------------- |
| `figures`   | integer | Number of large images in the body |
| `textChars` | integer | Number of characters in the body   |

For Word files with no images at all (`no_image_content`) or whose image dimensions cannot be measured (`unmeasurable_images`), `facts` may be an empty object. Treat each key as optional when reading it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/en/preparation/parser-auto-detection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
