Actor Dataset Provenance Enricher

Append a stable, versioned provenance object to rows from inline input or user-selected Apify datasets while preserving each original JSON object.

What this does not do

• It does not correct source data.
• It does not make a rights or legal determination.
• It does not automatically discover personal data.
• It does not mutate the original dataset.
• It does not use an external database.
• It does not claim that unknown provenance is complete.

Provenance enrichment records available evidence. It does not independently validate source claims or rights.

Source classes and authorization

The Actor reads either 1-100 inline objects or 1-5 datasets explicitly selected through Apify's read-authorized resource picker. It does not discover datasets, crawl URLs, or mutate an upstream dataset. Dataset reads are ordered, offset-addressed, bounded pages. Before each page, the page limit is reduced to the remaining row and paid-event capacity; after Apify reports the charge cap, no next page is requested.

Five named profiles are supported: AP-003, AP-014, AP-021, AP-027, and AP-002. auto accepts only explicit /actor/id, /actorId, or /schema/actorId markers. A dataset name is never treated as an Actor ID. Unknown rows require explicit fieldMappings and use the generic profile. New provider fields remain under _provenance.unmappedSourceFields until deliberately mapped.

Inputs

Select exactly one of datasetIds and inlineItems. includeOriginal must be true. maxRows defaults to 10,000 and is capped at 100,000. startOffset resumes at a deterministic zero-based row offset; when several datasets are selected, that same offset is applied independently to each dataset. Processing concurrency is one in version 0.1. default_and_named mirrors each successfully written enriched row to outputDatasetName; the paid default-dataset write remains authoritative.

Small public example:

{
  "inlineItems": [{
    "recordType": "result",
    "actor": {"id": "AP-003", "name": "scholarly-correction-monitor"},
    "entity": {"key": "10.1038/s41586-021-03819-2"},
    "sources": [{"sourceId": "crossref", "retrievedAt": "2026-07-14T00:00:00Z"}],
    "data": {"status": "fixture"}
  }],
  "profile": "auto",
  "includeOriginal": true,
  "maxRows": 10
}

Input echoes hash private dataset IDs and inline content. No private storage token or row body is copied into the run manifest.

Outputs

Each admitted row contains a deterministic enrichedRowId, the unchanged JSON object under original, and _provenance. Provenance includes the selected profile and evidence decision; available Actor, run, dataset, source, timestamp, rights, status, and lineage fields; raw and canonical original hashes; a non-recursive enriched-content hash; normalizer version; field-level observed, derived, user_supplied, or unknown classifications; explicit missing/null distinction; and unmapped source fields.

Example fragment:

{
  "recordType": "result",
  "status": "enriched",
  "original": {"actor": {"id": "AP-003"}, "entity": {"key": "demo"}},
  "_provenance": {
    "schemaVersion": "1.0.0",
    "profile": "AP-003",
    "normalizerVersion": "actor-dataset-provenance-normalizer/1.0.0"
  },
  "charge": {"event": "enriched-row", "chargeable": true, "reason": "schema_valid_enriched_row"}
}

KVS contains PROVENANCE_PROFILE.json, RUN_MANIFEST.json, and ARTIFACT_MANIFEST.json. Artifact entries carry content type, byte length, SHA-256, schema version, and generation rule. The artifact manifest excludes its own bytes by an explicit non-recursive self-exclusion rule. An uncharged run-summary row reports profile counts, enriched/rejected totals, exact platform charged count, and field completeness.

Pricing

Only a schema-valid enriched row successfully written by Actor.push_data uses the enriched-row event, priced at $0.001 per enriched row. Ten enriched rows cost at most $0.01 in Actor events; 10,000 cost at most $10.00, plus Apify platform usage. Mapping errors, invalid JSON, denied/deleted datasets, internal hash failures, charge-limit markers, artifacts, named-dataset mirrors, and the run summary are uncharged. Unknown optional fields remain chargeable when explicitly classified as unknown.

State and resume behavior

The Actor is stateless. Deterministic IDs use dataset ID, source offset, selected profile, and canonical original hash. The canonical enriched hash separately excludes run IDs, observation timestamps, dataset offsets, retries, platform metadata, and itself. Resume with the same startOffset; repeated rows keep the same IDs and produce no cross-run baseline writes.

Partial failures and negative results

An unreadable dataset yields an explicit uncharged source-error row without exposing its ID. A row without a supported marker or generic mapping yields an uncharged mapping-error row with its canonical original hash and missing requirements. Missing and explicit null fields remain distinct. Failure in one selected dataset does not hide valid rows from another. A named mirror failure is counted in the summary and does not rewrite the authoritative paid default-dataset result.

Resource limits

The launch range is 256-2048 MB, with 1024 MB default and a 900-second hosted timeout. Rows are limited to 1,000,000 canonical JSON bytes and depth 40. Dataset pages are at most 1,000 rows and are further bounded by remaining rows and charge capacity. The default inline example requires no remote source call and normally completes well within five minutes.

Support

See SUPPORT.md. Do not include dataset contents, private IDs, signed links, or credentials in a support report.