# RAG Dataset Linter (`sebastian-actors/rag-dataset-linter`) Actor

Audit RAG chunks for duplicates, broken ordering, excessive overlap, missing provenance, and malformed content before vector database ingestion.

- **URL**: https://apify.com/sebastian-actors/rag-dataset-linter.md
- **Developed by:** [Sebastián S](https://apify.com/sebastian-actors) (community)
- **Categories:** AI, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 chunk auditeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## RAG Dataset Linter

Audit already-chunked RAG datasets before paying to embed them or sending them into a vector database.

RAG Dataset Linter checks Apify Dataset rows, Actor Run datasets, or inline records for structural defects and retrieval-quality risks. It produces one decision-ready summary, a separate findings dataset, a JSON report, and an optional Markdown report.

### What it catches

- empty, missing, undersized, and oversized chunk text
- exact and near-duplicate chunks
- duplicate chunk IDs
- missing or duplicate chunk indexes
- gaps in per-document chunk sequences
- excessive overlap between adjacent chunks
- missing document and source provenance
- repeated boilerplate across documents
- leaked HTML markup
- substantial chunks without title or heading context
- contextless references such as “shown above”

Structural problems are errors. Conservative linguistic checks are warnings only. Issue codes and evidence are the product; the gate result is a compact automation signal.

### Input

Provide exactly one source:

- `datasetId` for an Apify Dataset selected with read-only resource access
- `runId` for an accessible Actor Run's default dataset
- `records` for a small inline sample

When the Actor is added as an integration, it also accepts Apify's implicit `payload.resource.defaultDatasetId`. An explicit `datasetId` takes precedence over that fallback. Selecting a Dataset grants only read access to that resource; the Actor remains limited-permission and never receives account-wide access.

Resolving `runId` requires access to that Run's metadata. For private Run output, select its default Dataset with `datasetId` or add this Actor as a Dataset integration so Apify can grant the required read-only resource access.

The Actor auto-detects common fields such as `chunkText`, `text`, `chunkId`, `documentId`, `url`, `chunkIndex`, `headingPath`, and `metadata.title`. Use `fieldMapping` dot-path overrides for other schemas.

```json
{
  "datasetId": "YOUR_DATASET_ID",
  "maxItems": 1000,
  "fieldMapping": {
    "text": "chunkText",
    "chunkId": "chunkId",
    "sourceUrl": "url",
    "chunkIndex": "chunkIndex"
  },
  "minTokens": 40,
  "maxTokens": 2000,
  "nearDuplicateSimilarity": 0.95,
  "maxAdjacentOverlapRatio": 0.35,
  "failRunOnError": false
}
````

### Outputs

The default dataset contains exactly one `audit_summary` row with:

- `PASS`, `WARN`, or `FAIL`
- recommended automation action: `continue`, `review`, or `stop`
- item and finding counts
- issue-code counts
- exact and near-duplicate rates
- token-size percentiles
- metadata coverage
- estimated embedding tokens wasted by exact duplication and excess overlap
- applied limit and truncation warnings

The `findings` dataset contains one row per stored finding with a stable ID, source record index, chunk context, code, severity, message, bounded evidence preview, and related-record reference.

Aggregate JSON is stored under `OUTPUT`. When enabled, a human-readable report is stored under `REPORT.md`.

### Automation gate

- `PASS`: no findings
- `WARN`: warning findings only
- `FAIL`: at least one structural error

Set `failRunOnError` to `true` to write every output and then fail the Actor run when the gate is `FAIL`. This allows schedules and workflow tools to stop bad data before embedding or indexing it.

### Limits and safety

- maximum 25,000 audited records
- maximum 50 MB of mapped chunk text
- maximum 20,000 stored findings
- inline input maximum 1,000 records
- fixed 512 MB Actor memory
- evidence previews are bounded; complete source records are never copied into reports
- selected private datasets use an explicit read-only resource grant while the Actor remains limited-permission

The Actor does not crawl websites, call external URLs, create embeddings, use LLMs, mutate the source dataset, write to vector databases, detect contradictions, or produce a repaired corpus.

### Pricing

The Actor charges one custom PPE event, `chunk-audited`, per source record admitted for analysis. Platform usage is included in the event price.

- Free: $1.50 per 1,000 audited chunks
- Bronze: $1.00 per 1,000 audited chunks
- Silver: $0.75 per 1,000 audited chunks
- Gold and above: $0.50 per 1,000 audited chunks

# Actor input Schema

## `datasetId` (type: `string`):

Dataset ID or accessible dataset name to audit. Use exactly one of Dataset ID, Run ID, or Inline records.

## `runId` (type: `string`):

Actor Run whose default dataset should be audited.

## `records` (type: `array`):

Small inline chunk sample for testing. Maximum 1,000 records.

## `maxItems` (type: `integer`):

Maximum source records to audit.

## `fieldMapping` (type: `object`):

Optional dot paths. Leave empty to auto-detect common RAG crawler fields.

## `minTokens` (type: `integer`):

Warn when a valid chunk is below this estimated token count.

## `maxTokens` (type: `integer`):

Fail a chunk when it exceeds this estimated token count.

## `nearDuplicateSimilarity` (type: `number`):

SimHash similarity required to report a near duplicate.

## `maxAdjacentOverlapRatio` (type: `number`):

Warn when matching suffix/prefix tokens exceed this share of the shorter adjacent chunk.

## `enableHeuristicWarnings` (type: `boolean`):

Check for repeated boilerplate, missing context, and HTML leakage. Heuristics never fail a run by themselves.

## `maxFindings` (type: `integer`):

Maximum detailed rows stored in the findings dataset; aggregate counts continue beyond this cap.

## `includeMarkdownReport` (type: `boolean`):

Write a bounded human-readable report under REPORT.md.

## `failRunOnError` (type: `boolean`):

Write all reports first, then fail the Actor run when error-severity findings exist.

## Actor input object example

```json
{
  "records": [
    {
      "chunkId": "guide-0",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 0,
      "title": "Getting started",
      "headingPath": [
        "Getting started"
      ],
      "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
    },
    {
      "chunkId": "guide-1",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 1,
      "title": "Getting started",
      "headingPath": [
        "Getting started"
      ],
      "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
    },
    {
      "chunkId": "guide-3",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 3,
      "title": "Configuration",
      "headingPath": [
        "Configuration"
      ],
      "chunkText": "Configure the index name, embedding dimensions, and metadata fields used for retrieval."
    },
    {
      "chunkId": "overlap-0",
      "documentId": "overlap",
      "sourceUrl": "https://example.com/overlap",
      "chunkIndex": 0,
      "title": "Overlap example",
      "headingPath": [
        "Overlap example"
      ],
      "chunkText": "This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. Verify the source records before embedding them. Keep stable identifiers and source URLs."
    },
    {
      "chunkId": "missing-provenance",
      "chunkIndex": 0,
      "chunkText": "As shown above, use the same configuration for the next operation."
    },
    {
      "chunkId": "overlap-1",
      "documentId": "overlap",
      "sourceUrl": "https://example.com/overlap",
      "chunkIndex": 1,
      "chunkText": "Verify the source records before embedding them. Keep stable identifiers and source URLs. Keep stable identifiers and source URLs for every chunk."
    }
  ],
  "maxItems": 1000,
  "fieldMapping": {},
  "minTokens": 40,
  "maxTokens": 2000,
  "nearDuplicateSimilarity": 0.95,
  "maxAdjacentOverlapRatio": 0.35,
  "enableHeuristicWarnings": true,
  "maxFindings": 5000,
  "includeMarkdownReport": true,
  "failRunOnError": false
}
```

# Actor output Schema

## `summary` (type: `string`):

No description

## `findings` (type: `string`):

No description

## `jsonReport` (type: `string`):

No description

## `markdownReport` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "records": [
        {
            "chunkId": "guide-0",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 0,
            "title": "Getting started",
            "headingPath": [
                "Getting started"
            ],
            "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
        },
        {
            "chunkId": "guide-1",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 1,
            "title": "Getting started",
            "headingPath": [
                "Getting started"
            ],
            "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
        },
        {
            "chunkId": "guide-3",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 3,
            "title": "Configuration",
            "headingPath": [
                "Configuration"
            ],
            "chunkText": "Configure the index name, embedding dimensions, and metadata fields used for retrieval."
        },
        {
            "chunkId": "overlap-0",
            "documentId": "overlap",
            "sourceUrl": "https://example.com/overlap",
            "chunkIndex": 0,
            "title": "Overlap example",
            "headingPath": [
                "Overlap example"
            ],
            "chunkText": "This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. Verify the source records before embedding them. Keep stable identifiers and source URLs."
        },
        {
            "chunkId": "missing-provenance",
            "chunkIndex": 0,
            "chunkText": "As shown above, use the same configuration for the next operation."
        },
        {
            "chunkId": "overlap-1",
            "documentId": "overlap",
            "sourceUrl": "https://example.com/overlap",
            "chunkIndex": 1,
            "chunkText": "Verify the source records before embedding them. Keep stable identifiers and source URLs. Keep stable identifiers and source URLs for every chunk."
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sebastian-actors/rag-dataset-linter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "records": [
        {
            "chunkId": "guide-0",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 0,
            "title": "Getting started",
            "headingPath": ["Getting started"],
            "chunkText": "Install the package, create a client, and verify the connection before indexing production content.",
        },
        {
            "chunkId": "guide-1",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 1,
            "title": "Getting started",
            "headingPath": ["Getting started"],
            "chunkText": "Install the package, create a client, and verify the connection before indexing production content.",
        },
        {
            "chunkId": "guide-3",
            "documentId": "guide",
            "sourceUrl": "https://example.com/guide",
            "chunkIndex": 3,
            "title": "Configuration",
            "headingPath": ["Configuration"],
            "chunkText": "Configure the index name, embedding dimensions, and metadata fields used for retrieval.",
        },
        {
            "chunkId": "overlap-0",
            "documentId": "overlap",
            "sourceUrl": "https://example.com/overlap",
            "chunkIndex": 0,
            "title": "Overlap example",
            "headingPath": ["Overlap example"],
            "chunkText": "This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. Verify the source records before embedding them. Keep stable identifiers and source URLs.",
        },
        {
            "chunkId": "missing-provenance",
            "chunkIndex": 0,
            "chunkText": "As shown above, use the same configuration for the next operation.",
        },
        {
            "chunkId": "overlap-1",
            "documentId": "overlap",
            "sourceUrl": "https://example.com/overlap",
            "chunkIndex": 1,
            "chunkText": "Verify the source records before embedding them. Keep stable identifiers and source URLs. Keep stable identifiers and source URLs for every chunk.",
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("sebastian-actors/rag-dataset-linter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "records": [
    {
      "chunkId": "guide-0",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 0,
      "title": "Getting started",
      "headingPath": [
        "Getting started"
      ],
      "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
    },
    {
      "chunkId": "guide-1",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 1,
      "title": "Getting started",
      "headingPath": [
        "Getting started"
      ],
      "chunkText": "Install the package, create a client, and verify the connection before indexing production content."
    },
    {
      "chunkId": "guide-3",
      "documentId": "guide",
      "sourceUrl": "https://example.com/guide",
      "chunkIndex": 3,
      "title": "Configuration",
      "headingPath": [
        "Configuration"
      ],
      "chunkText": "Configure the index name, embedding dimensions, and metadata fields used for retrieval."
    },
    {
      "chunkId": "overlap-0",
      "documentId": "overlap",
      "sourceUrl": "https://example.com/overlap",
      "chunkIndex": 0,
      "title": "Overlap example",
      "headingPath": [
        "Overlap example"
      ],
      "chunkText": "This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. This intentionally repeated sample demonstrates an oversized chunk. Verify the source records before embedding them. Keep stable identifiers and source URLs."
    },
    {
      "chunkId": "missing-provenance",
      "chunkIndex": 0,
      "chunkText": "As shown above, use the same configuration for the next operation."
    },
    {
      "chunkId": "overlap-1",
      "documentId": "overlap",
      "sourceUrl": "https://example.com/overlap",
      "chunkIndex": 1,
      "chunkText": "Verify the source records before embedding them. Keep stable identifiers and source URLs. Keep stable identifiers and source URLs for every chunk."
    }
  ]
}' |
apify call sebastian-actors/rag-dataset-linter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sebastian-actors/rag-dataset-linter",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "RAG Dataset Linter",
        "description": "Audit RAG chunks for duplicates, broken ordering, excessive overlap, missing provenance, and malformed content before vector database ingestion.",
        "version": "0.1",
        "x-build-id": "eN2aPMyuQ5qqYVkOq"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sebastian-actors~rag-dataset-linter/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sebastian-actors-rag-dataset-linter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/sebastian-actors~rag-dataset-linter/runs": {
            "post": {
                "operationId": "runs-sync-sebastian-actors-rag-dataset-linter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/sebastian-actors~rag-dataset-linter/run-sync": {
            "post": {
                "operationId": "run-sync-sebastian-actors-rag-dataset-linter",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "datasetId": {
                        "title": "Apify Dataset ID",
                        "type": "string",
                        "description": "Dataset ID or accessible dataset name to audit. Use exactly one of Dataset ID, Run ID, or Inline records."
                    },
                    "runId": {
                        "title": "Apify Actor Run ID",
                        "type": "string",
                        "description": "Actor Run whose default dataset should be audited."
                    },
                    "records": {
                        "title": "Inline records",
                        "type": "array",
                        "description": "Small inline chunk sample for testing. Maximum 1,000 records.",
                        "items": {
                            "type": "object",
                            "additionalProperties": true
                        }
                    },
                    "maxItems": {
                        "title": "Maximum chunks",
                        "minimum": 1,
                        "maximum": 25000,
                        "type": "integer",
                        "description": "Maximum source records to audit.",
                        "default": 1000
                    },
                    "fieldMapping": {
                        "title": "Field mapping overrides",
                        "type": "object",
                        "description": "Optional dot paths. Leave empty to auto-detect common RAG crawler fields.",
                        "properties": {
                            "text": {
                                "title": "Text field",
                                "description": "Dot path containing chunk text.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "chunkId": {
                                "title": "Chunk ID field",
                                "description": "Dot path containing the stable chunk identifier.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "documentId": {
                                "title": "Document ID field",
                                "description": "Dot path identifying the source document.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "sourceUrl": {
                                "title": "Source URL field",
                                "description": "Dot path containing the source URL.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "title": {
                                "title": "Title field",
                                "description": "Dot path containing document or chunk title context.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "headingPath": {
                                "title": "Heading path field",
                                "description": "Dot path containing an array or string heading path.",
                                "type": "string",
                                "editor": "textfield"
                            },
                            "chunkIndex": {
                                "title": "Chunk index field",
                                "description": "Dot path containing the numeric position within a document.",
                                "type": "string",
                                "editor": "textfield"
                            }
                        },
                        "default": {},
                        "additionalProperties": false
                    },
                    "minTokens": {
                        "title": "Minimum tokens",
                        "minimum": 0,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Warn when a valid chunk is below this estimated token count.",
                        "default": 40
                    },
                    "maxTokens": {
                        "title": "Maximum tokens",
                        "minimum": 1,
                        "maximum": 20000,
                        "type": "integer",
                        "description": "Fail a chunk when it exceeds this estimated token count.",
                        "default": 2000
                    },
                    "nearDuplicateSimilarity": {
                        "title": "Near-duplicate similarity",
                        "minimum": 0.8,
                        "maximum": 1,
                        "type": "number",
                        "description": "SimHash similarity required to report a near duplicate.",
                        "default": 0.95
                    },
                    "maxAdjacentOverlapRatio": {
                        "title": "Maximum adjacent overlap ratio",
                        "minimum": 0,
                        "maximum": 1,
                        "type": "number",
                        "description": "Warn when matching suffix/prefix tokens exceed this share of the shorter adjacent chunk.",
                        "default": 0.35
                    },
                    "enableHeuristicWarnings": {
                        "title": "Enable heuristic warnings",
                        "type": "boolean",
                        "description": "Check for repeated boilerplate, missing context, and HTML leakage. Heuristics never fail a run by themselves.",
                        "default": true
                    },
                    "maxFindings": {
                        "title": "Maximum finding rows",
                        "minimum": 1,
                        "maximum": 20000,
                        "type": "integer",
                        "description": "Maximum detailed rows stored in the findings dataset; aggregate counts continue beyond this cap.",
                        "default": 5000
                    },
                    "includeMarkdownReport": {
                        "title": "Create Markdown report",
                        "type": "boolean",
                        "description": "Write a bounded human-readable report under REPORT.md.",
                        "default": true
                    },
                    "failRunOnError": {
                        "title": "Fail run when the gate fails",
                        "type": "boolean",
                        "description": "Write all reports first, then fail the Actor run when error-severity findings exist.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
