# Data Coverage Claim Verifier (`boundedtools/data-coverage-claim-verifier`) Actor

Tests a vendor's explicit coverage claim against an authorized buyer reference set and returns PASS, FAIL, or UNKNOWN with reproducible evidence.

- **URL**: https://apify.com/boundedtools/data-coverage-claim-verifier.md
- **Developed by:** [Sean](https://apify.com/boundedtools) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$32.50 / private audit

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Data Coverage Claim Verifier

**Give me the coverage claim a data vendor made and an authorized reference sample. I will test whether that claim actually holds.**

This Apify Actor turns a specific claim—such as “we cover at least 95% of active companies in this market”—into a pre-registered, deterministic coverage test. It returns **PASS**, **FAIL**, or **UNKNOWN**, the matching evidence and uncertainty behind that result, and a separately labeled commercial suggestion.

Run the bundled synthetic example with one field:

```json
{ "mode": "free_example" }
```

It tests a 90% claim against 20 fictional companies. The synthetic vendor covers 19, so the complete-reference-set result is a reproducible **PASS at 95% coverage**.

### Who this is for

- Developers and data-product teams evaluating external APIs or datasets
- Procurement engineers who need evidence for a buy, renewal, discount, or rejection decision
- Research platforms that need a repeatable vendor-coverage test
- Data publishers auditing their own explicit market-coverage claims

### What it does—and does not do

The Actor supports two narrow claim types:

1. `entity_coverage`: how many authorized reference entities have a normalized exact-key match in the vendor sample.
2. `field_presence`: how many reference entities both match and have one explicitly claimed non-empty vendor field.

It is **not** a generic data-quality score, schema validator, fuzzy entity-resolution engine, truth/accuracy checker, web crawler, or licence-rights evaluator. Field presence does not prove field correctness. It uses no LLM and produces no opaque score.

### Private audit input

The Actor input itself is the audit manifest. This complete five-supplier example passes exactly at its 80% threshold:

```json
{
  "mode": "private_audit",
  "claim": {
    "statement": "Example Data Co. covers at least 80% of our active suppliers.",
    "metric": "entity_coverage",
    "threshold": 0.8,
    "aggregation": "overall"
  },
  "population": {
    "description": "All five active suppliers in the buyer reference set.",
    "basis": "complete_reference_set"
  },
  "referenceSource": {
    "type": "inline",
    "records": [
      { "supplier_id": "SUP-001", "region": "north" },
      { "supplier_id": "SUP-002", "region": "north" },
      { "supplier_id": "SUP-003", "region": "south" },
      { "supplier_id": "SUP-004", "region": "south" },
      { "supplier_id": "SUP-005", "region": "south" }
    ]
  },
  "vendorSource": {
    "type": "inline",
    "records": [
      { "id": "sup-001" }, { "id": "SUP-002" },
      { "id": "SUP-003" }, { "id": "SUP-004" }
    ]
  },
  "matching": {
    "referenceKeys": ["supplier_id"],
    "vendorKeys": ["id"]
  },
  "strata": [{ "name": "region", "referenceField": "region" }],
  "rightsAttestation": {
    "hasAuditRights": true,
    "noAccessControlsBypassed": true,
    "dataMinimized": true,
    "allowCounterexampleOutput": true
  },
  "evidence": { "identifierMode": "hash", "maxCounterexamples": 10 },
  "auditContext": { "datasetVersion": "example-data-co-2026-09" }
}
```

#### Source types

Both `referenceSource` and `vendorSource` accept the same four types:

```json
{ "type": "inline", "records": [{ "id": "A-1" }] }
```

```json
{
  "type": "url",
  "url": "https://data.example.com/authorized-sample.csv",
  "allowedHosts": ["data.example.com"],
  "format": "csv",
  "headers": { "Authorization": "Bearer secret" }
}
```

```json
{ "type": "apify_dataset", "datasetId": "DATASET_ID" }
```

```json
{
  "type": "apify_kv_record",
  "storeId": "STORE_ID",
  "key": "sample.json",
  "format": "json",
  "recordsPath": "data.items"
}
```

When the Actor runs with Apify's limited permission level, select any referenced Dataset or key-value store through the corresponding input resource field. The schema requests `READ` access only; the Actor never modifies those source storages.

URL sources are GET-only, HTTPS-only, restricted to port 443, and require an exact `allowedHosts` entry. Every redirect is checked again. IP-literal, local, private, link-local, reserved, and unapproved destinations are rejected. Authorization and cookie headers are not forwarded across origins. JSON, JSONL, and RFC-style CSV are supported; JSON can use a safe dotted `recordsPath`.

#### Matching and normalization

`referenceKeys` and `vendorKeys` are parallel arrays of one to five safe dotted field paths. More than one path creates a composite key. Version 1 supports only `normalized_exact` matching.

Default normalization is explicit and appears in the output test specification:

```json
{
  "trim": true,
  "unicode": "NFKC",
  "lowercase": true,
  "collapseWhitespace": true,
  "removePunctuation": false
}
```

Normalized duplicate keys in the reference set make the population ambiguous and fail the audit. Vendor duplicates are disclosed and deduplicated for entity coverage. For field-presence coverage, any record under the duplicated vendor key may satisfy the field requirement; this policy is pre-registered in the result.

### Result semantics

- **PASS**: the direct census measurement meets the threshold, or an inferential confidence interval is entirely at or above it.
- **FAIL**: the direct census measurement is below the threshold, or an inferential confidence interval is entirely below it.
- **UNKNOWN**: the inferential interval crosses the threshold or the sample is below the pre-registered minimum.

`complete_reference_set` is treated as a direct measurement of the buyer-defined set. `representative_sample`, or any test downsampled with `sampling.maxRecords`, uses a deterministic Wilson score interval. The default confidence level is 95% and the default minimum inferential sample size is 30.

For `aggregation: "overall"`, the overall rate decides the verdict. With `aggregation: "all_strata"`, every reported stratum must pass; one FAIL makes the claim fail, while unresolved strata produce UNKNOWN unless another stratum already fails.

### Output

One full report is written to the default Dataset and to the `OUTPUT` key-value record. The schema deliberately separates the layers:

```json
{
  "auditId": "dcv_…",
  "factualVerdict": "PASS",
  "exactClaimTested": { "metric": "entity_coverage", "threshold": 0.9 },
  "observedFacts": { "suppliedReferenceRecordCount": 20 },
  "calculations": {
    "testedPopulationSize": 20,
    "matchedAndCoveredCount": 19,
    "observedCoverage": 0.95,
    "uncertainty": { "applicable": false }
  },
  "assumptions": ["…"],
  "recommendation": {
    "nature": "commercial_suggestion_not_factual_verdict",
    "action": "buy",
    "reasons": ["…"]
  },
  "reproducibility": {
    "testSpecificationHash": "sha256:…",
    "referenceContentHash": "sha256:…",
    "vendorContentHash": "sha256:…",
    "resultFingerprint": "sha256:…"
  }
}
```

A failure produces a safe structured `ERROR` key-value record and a failed Actor run; private rows and unexpected exception details are not logged.

#### Counterexamples

Missing reference identifiers are SHA-256 pseudonyms by default. Set `rightsAttestation.allowCounterexampleOutput: true` and `evidence.identifierMode: "raw"` only when the run output is authorized to contain the join keys. At most 100 identifiers can be returned. Full third-party rows are never copied to the result.

#### Commercial suggestion

The factual verdict never changes to accommodate a purchase decision. Optional `commercialRules` can turn configured missing-entity costs into `buy`, `test_more`, `negotiate_or_discount`, or `reject`. This object is explicitly labeled as a suggestion and remains separate from observed facts and calculations.

### API usage

Start a run with the standard Apify Actor API:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/boundedtools~data-coverage-claim-verifier/runs?waitForFinish=120" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @audit_manifest.json
```

The run response exposes links defined by the Actor output schema. Fetch the final JSON from the run's default Dataset or `OUTPUT` record. See Apify's [Actor input/output documentation](https://docs.apify.com/actors/running/input-and-output) for API and integration patterns.

### Pricing

This Actor uses Apify pay per event.

- **Free synthetic example:** $0.00. The free example does not trigger the paid event.
- **Private audit:** $32.50 per successful private run.
- **Failed or invalid private runs:** the paid event is not charged.
- **Platform usage:** included. Users are not charged a separate platform-usage fee.

The `private-audit` event is charged at most once per run and only after the user-visible result has been successfully saved.

### Privacy, retention, and rights

You must have the legal and contractual right to audit every supplied source. The Actor does not bypass authentication, CAPTCHA, robots controls, access controls, or API restrictions. A reachable URL is not evidence of permission. Do not supply unnecessary personal data.

For private audits, `retention.retainInput` defaults to `false`: after loading both sources, the Actor deletes the run's `INPUT` record, including inline rows and request headers. It also attempts that cleanup on handled failures. A hard process/container termination can prevent cleanup, so highly sensitive inputs should use appropriately restricted, short-retention Apify storage. Set `retainInput: true` only as an explicit opt-in; Apify's storage retention settings then apply. Source Apify Datasets/KV records are read but never modified. The Actor retains only aggregate results, hashes, safe provenance without URL query strings, and bounded counterexample identifiers.

Content hashes are reproducibility fingerprints, not copies of the data. Because raw input is deleted by default, the buyer must retain the original authorized samples to rerun the audit. HTTP secret values and URL query strings are deliberately excluded from the configuration hash and provenance; the fetched content itself is hashed.

### Guardrails and limitations

- Maximum 50,000 supplied records per source and 25 MiB of canonical JSON or fetched content per source
- Maximum 20,000 tested reference records; larger tests require deterministic sampling within the 50,000-record source cap
- Maximum 30 levels of record nesting, 2,000 properties per object, five strata, and 50 values per stratum
- Maximum three HTTPS redirects and 30 seconds per remote request
- No pagination, POST endpoints, browser automation, CAPTCHA handling, fuzzy matching, probabilistic entity resolution, or accuracy/freshness verification in version 1
- Exact host allowlisting and DNS pinning reduce SSRF risk, but buyers should prefer inline or Apify-native storage for sensitive audits
- Results are only as defensible as the buyer's reference population, join keys, rights, and sampling assumptions

### Reproducibility notes

Test specification, normalization, duplicate policy, threshold, confidence level, sample cap, and seed are written into every result. Canonical JSON SHA-256 hashes cover the audit configuration, exact ordered source records, and factual result core. Timestamps are excluded from the result fingerprint. Reordering source records intentionally changes their content hashes, while deterministic sample membership is based on normalized keys and the stable seed.

This Actor verifies the configured test. It does not certify a vendor, guarantee a contract outcome, or replace legal, statistical, or procurement advice.

# Actor input Schema

## `mode` (type: `string`):

free\_example ignores all private audit fields and uses bundled synthetic data. private\_audit validates and audits your manifest.

## `claim` (type: `object`):

The quoted claim and the numerical threshold being tested. Only at\_least coverage claims are supported.

## `population` (type: `object`):

Declare whether the supplied reference is the complete buyer-defined set or a representative sample of a larger population.

## `referenceSource` (type: `object`):

An inline record array, an explicitly allowlisted HTTPS JSON/JSONL/CSV URL, an Apify Dataset, or an Apify key-value record.

## `vendorSource` (type: `object`):

An inline record array, an explicitly allowlisted HTTPS JSON/JSONL/CSV URL, an Apify Dataset, or an Apify key-value record.

## `matching` (type: `object`):

Parallel referenceKeys and vendorKeys arrays define one exact or composite join key. No fuzzy or AI matching is performed.

## `strata` (type: `array`):

Up to five reference fields to report separately, for example market or company size.

## `sampling` (type: `object`):

Cap tested reference records and set the stable sampling seed. Maximum 20,000 tested records.

## `uncertainty` (type: `object`):

Wilson confidence intervals apply to representative or downsampled tests; complete reference sets are measured directly.

## `rightsAttestation` (type: `object`):

You must have the right to audit both supplied sources, must not bypass access controls, and must minimize the data supplied.

## `evidence` (type: `object`):

Identifiers are hashed by default. Raw join keys require explicit counterexample-output authorization.

## `commercialRules` (type: `object`):

Optional loss thresholds used only for the separate buy/test\_more/negotiate\_or\_discount/reject suggestion.

## `auditContext` (type: `object`):

A non-personal datasetVersion label supports version-repeat measurement; only its SHA-256 fingerprint is output.

## `retention` (type: `object`):

By default the Actor deletes the run INPUT record after loading it. Set retainInput=true only if you explicitly want Apify run storage to keep it under your account retention settings.

## Actor input object example

```json
{
  "mode": "free_example"
}
```

# Actor output Schema

## `results` (type: `string`):

Machine-readable PASS, FAIL, or UNKNOWN audit report.

## `report` (type: `string`):

The single completed audit report from the default key-value store.

## `failure` (type: `string`):

Present only when validation, source loading, or audit execution fails.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("boundedtools/data-coverage-claim-verifier").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("boundedtools/data-coverage-claim-verifier").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{}' |
apify call boundedtools/data-coverage-claim-verifier --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,boundedtools/data-coverage-claim-verifier"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/7yn1WU3ulWzcaqxQc/builds/yngSX5YncRPCJEdRo/openapi.json