Patent Evidence Normalizer

Turn patent records you are authorized to use into stable, provenance-linked evidence rows for research queues, portfolio reviews, competitive-intelligence workflows, and data-quality operations.

This Actor does not scrape Google Patents, does not call PatentsView, does not log in to a patent office, and does not make legal conclusions. You supply a buyer-owned, rights-holder-authorized, PatentsView CC BY 4.0, or otherwise licensed export. The Actor validates the records, suppresses duplicates before billing, preserves attribution and change disclosures, adds freshness and evidence limitations, and writes a current-run settlement receipt to OUTPUT.

What you get

For every eligible supplied patent record, the Actor delivers one normalized Dataset row with:

• the legacy product fields: sourceQuery, found, matched, patentId, title, patentDate, assignee, abstractSnippet, url, summary, and checkedAt;
• a stable entityId and deterministic stableId for downstream joins;
• the buyer-declared source context and supplied jurisdiction/status;
• the recorded source name, source URL, licence statement, retrieval time, and description of transformations;
• freshness derived only from the supplied retrieval timestamp and the threshold you set;
• evidence confidence with an explicit basis and gap list;
• an evidence-only decision boundary, priority, and human-review action;
• safeToAutomate:false because a normalized record is not a legal conclusion;
• settlement-neutral Dataset billing metadata; and
• a canonical row digest.

The run also writes a current-run KVS record named OUTPUT. It reconciles requested, unique, duplicate, invalid, attempted, successful, failed, delivered, paid, free, withheld, unknown-delivery, unknown-settlement, partial, budget-stop, fatal-error, and replay-safety state.

Who uses it

Competitive-intelligence analysts

Normalize exports from an approved patent-data source before joining them with product, company, technology, or market datasets. Preserve the source and licence boundary next to every row so downstream users can see what was and was not verified.

Patent operations teams

Create a clean intake layer for a review queue. The Actor can reject malformed records, suppress duplicate (sourceName, patentId) pairs before billing, and attach a stable identity and recommended human-review step.

Product and R&D teams

Convert a permitted search export into a consistent technical-reading list. Use the output to route candidate documents to subject-matter experts. Do not use the confidence score as a legal-risk score.

Data engineering teams

Use the closed input and Dataset contracts as a boundary between upstream exports and downstream warehouses. The request, input, row, and run receipts provide deterministic reconciliation without copying an API secret into Dataset or OUTPUT.

Agencies and research vendors

Process records only when the buyer has a documented right to provide and commercially use them. The Actor records the buyer-declared rights context but does not independently validate the agreement.

What it does not give you

• No Google Patents XHR access.
• No live PatentsView API call.
• No patent-office login or browser automation.
• No article, claim, family, citation, prosecution-history, legal-status, assignment, or maintenance-fee verification.
• No novelty, validity, infringement, enforceability, ownership, inventorship, or freedom-to-operate opinion.
• No guarantee that an assignee string identifies the current owner.
• No guarantee that a supplied date or status is current.
• No guarantee that a recorded HTTPS URL is reachable, official, safe, or unchanged; URLs are recorded but never fetched.
• No hidden enrichment, LLM inference, identity lookup, or external matching.
• No monitoring baseline between runs. Each run is a supplied-export snapshot.
• No permission to use a source. The buyer remains responsible for source access, licence, attribution, privacy, and purpose.

How the workflow works

1. Submit an authorized export. Provide 1–100 records and confirm that you may process and commercially use them.
2. Validate the closed contract. The Actor rejects unknown fields, control characters, impossible dates, credentialed URLs, non-HTTPS URLs, malformed identifiers, unsupported source contexts, and records missing attribution.
3. Suppress duplicates. Records with the same case-insensitive (sourceName, patentId) identity are delivered at most once per run. A free diagnostic reports duplicate suppression.
4. Build evidence rows. Legacy fields are preserved. Provenance, licence, freshness, confidence gaps, actionability, and settlement-neutral billing intent are added.
5. Check the buyer's run cap. The run validates the exact PAY_PER_EVENT map and verifies that another result fits before each paid push.
6. Deliver and settle atomically. One linked Dataset push uses the named event result-found. The Actor checks the named counter before and after and requires an exact +1 delta plus the SDK aggregate receipt.
7. Write OUTPUT. The final KVS receipt binds the current run, Dataset URL, work counts, delivery counts, event counters, partial/failure state, and replay boundary.
8. Review the evidence. Open the recorded source and route material questions to qualified patent counsel or an authorized patent professional.

How to run

Use the Input tab or submit JSON through the Apify API.

{
  "schemaVersion": "2.0",
  "authorization": "I confirm I may process and commercially use these patent records.",
  "sourceContext": "patentsview_cc_by_4_export",
  "watchName": "battery-thermal-management-review",
  "freshnessDays": 30,
  "patents": [
    {
      "sourceQuery": "battery thermal management",
      "patentId": "US12345678B2",
      "title": "Thermal management system for an energy storage assembly",
      "patentDate": "2026-07-14",
      "assignee": "Example Energy Systems Inc.",
      "abstractSnippet": "A supplied excerpt describing a thermal management assembly.",
      "url": "https://patents.google.com/patent/US12345678B2/en",
      "jurisdiction": "US",
      "recordStatus": "granted",
      "sourceName": "PatentsView PatentSearch export",
      "sourceUrl": "https://search.patentsview.org/docs/",
      "sourceLicense": "CC BY 4.0; attribution and indication of changes required.",
      "changesMade": "Selected fields, normalized whitespace, and truncated the supplied abstract excerpt.",
      "sourceRetrievedAt": "2026-08-12T10:00:00.000Z"
    }
  ]
}

The example is a contract fixture, not a claim that the identifier or company represents a current real-world patent. Replace every supplied field with data from your authorized export.

Input contract

The runtime accepts exactly one of two modes.

Mode A: authorized patent records

This is the public product path.

Field	Required	Contract
schemaVersion	No	When supplied, exactly 2.0.
authorization	Yes	Exact confirmation string shown in the schema. It records buyer intent; it is not independent licence verification.
sourceContext	Yes	One of four closed rights contexts.
watchName	No	1–80 nonblank characters; defaults to patent-evidence-review.
freshnessDays	No	Integer 1–3650; defaults to 30.
patents	Yes	Array of 1–100 closed patent record objects.

Accepted sourceContext values:

• buyer_owned_patent_export
• rights_holder_authorized_export
• patentsview_cc_by_4_export
• other_licensed_patent_export

The source context is a declaration. Keep the underlying contract, licence, export receipt, or permission outside this Dataset according to your own records policy.

Patent record fields

Field	Required	Maximum	Meaning
sourceQuery	No	200	Buyer-supplied query or batch label.
patentId	Yes	100	Stable source identifier using letters, digits, ., _, /, or -.
title	Yes	500	Supplied title.
patentDate	No	ISO date	Calendar-valid YYYY-MM-DD; semantics depend on the source.
assignee	No	300	Supplied assignee string, not independently verified current ownership.
abstractSnippet	No	1,000	Supplied excerpt. Do not include unnecessary personal or confidential data.
url	No	2,000	Recorded HTTPS patent URL; never fetched. Credentials, ports, and fragments are rejected.
jurisdiction	No	40	Supplied jurisdiction label.
recordStatus	No	enum	granted, published, application, or unknown. Defaults to unknown.
sourceName	Yes	200	Human-readable source/export name.
sourceUrl	Yes	2,000	Recorded HTTPS source documentation or export origin. Never fetched.
sourceLicense	Yes	700	Rights or licence statement that applies to the supplied record.
changesMade	Yes	500	Your transformation disclosure: selection, normalization, truncation, joining, or other changes.
sourceRetrievedAt	No	ISO time	Buyer-supplied retrieval timestamp used only for freshness.

Mode B: legacy queries

Older integrations may continue to send:

{
  "queries": ["battery thermal management"],
  "sinceDays": 365,
  "limit": 20,
  "maxConcurrency": 3
}

The fields remain accepted so an existing integration receives a structured response instead of an opaque schema rejection. The Actor no longer sends those queries to Google Patents or PatentsView. It writes one free migration diagnostic that explains how to submit an authorized export.

If patentsviewApiKey is still supplied, Apify stores it in the run's secret INPUT because that is how Actor inputs work. This Actor does not read, transmit, log, or copy the key into Dataset or OUTPUT. Remove the legacy key from Tasks and integrations after migrating.

Do not mix patents and queries in one run.

Pricing

This Actor uses PAY_PER_EVENT pricing. The automatic Actor-start event is separate from delivered patent evidence.

The paid unit is:

one normalized patent evidence record successfully delivered to the Dataset with a confirmed result-found settlement

Current six-tier event prices expected by the runtime:

Tier	Actor start	One delivered patent evidence record
FREE	$0.00500	$0.00500
BRONZE	$0.00475	$0.00475
SILVER	$0.00450	$0.00450
GOLD	$0.00425	$0.00425
PLATINUM	$0.00410	$0.00410
DIAMOND	$0.00400	$0.00400

The Actor fails closed if the platform pricing map contains extra events, omits either required event, or differs from an approved tier. The default Dataset event must not be priced separately.

No result-found event is intentionally emitted for:

• legacy-query migration diagnostics;
• rejected records;
• duplicate records suppressed before delivery;
• records withheld before a push because the run charge cap cannot cover another unit;
• pre-push counter failures;
• input, identity, pricing, or KVS failures.

A linked push can have an outcome that cannot be safely classified after an SDK or platform failure. In that case OUTPUT records unknown_delivery, settlement_unknown, or settlement_anomaly, marks the run failed and replaySafe:false after a push attempt, and forbids blind retry. It does not falsely promise that the outcome was free.

Cost examples

At the FREE tier, a run that confirms two delivered records costs the automatic $0.005 start event plus 2 × $0.005 result events, before any separate platform compute or storage charges shown by Apify. At the DIAMOND tier, the same event arithmetic is $0.004 + 2 × $0.004. These are event-price examples, not a forecast of your total bill or usage.

Use maxTotalChargeUsd on the run to create a hard buyer-controlled cap. The Actor checks the current spent amount and next result price before every paid row. A final linked push may report that the charge limit is reached while still confirming that final row; OUTPUT distinguishes a confirmed final row from remaining withheld work.

Happy, partial, and failure output

Happy-path Dataset row

The full canonical row ships as examples/dataset-item.json. Dataset billing fields describe intent; current-run OUTPUT proves settlement. The release workflow binds each accepted artifact with wrappers like these; the wrapper keys are release evidence, not Dataset fields:

{
  "runId": "example-current-run",
  "buildId": "candidate-build-id",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "artifact": "Dataset row"
}

{
  "runId": "example-current-run",
  "buildId": "candidate-build-id",
  "status": "SUCCEEDED",
  "evidenceAccepted": true,
  "artifact": "KVS OUTPUT"
}

Partial and free diagnostic output

Free diagnostic rows have recordType:"patent_evidence_advisory", found:false, matched:0, null patent fields, confidence.score:0, and billing.billingEligible:false. They are delivered through an ordinary Dataset write without a named result event.

Three free diagnostic classes are currently reachable:

failureType	Why it appears	Recommended response
legacy_queries	The request used the old search-query contract.	Export records from an authorized source and submit them through patents.
invalid_patent_records	One or more supplied records failed the closed normalizer.	Correct only the rejected records; valid unique records may still be processed.
duplicate_patent_records	Multiple records resolved to the same case-insensitive (sourceName, patentId) identity.	Inspect upstream deduplication if the duplicates were unexpected.

Example excerpt:

{
  "recordType": "patent_evidence_advisory",
  "found": false,
  "matched": 0,
  "summary": "1 duplicate patent record(s) were suppressed before billing.",
  "decision": {
    "outcome": "no_eligible_result",
    "basis": "duplicate_patent_records",
    "safeToAutomate": false
  },
  "failureDiagnostics": {
    "failureType": "duplicate_patent_records",
    "stage": "input_normalization",
    "retryRecommended": true
  },
  "billing": {
    "billingEligible": false,
    "billingIntent": "free_diagnostic_dataset_write",
    "eventName": null,
    "unit": null,
    "settlementSource": "current_run_kvs_output"
  }
}

When a batch includes diagnostics and paid results, the terminal status is PARTIAL. That does not mean a confirmed paid row is untrustworthy. It means the run also contains non-result, withheld, or failed work that must be considered during reconciliation.

Failure output

Failures before Dataset delivery are written to the current run's OUTPUT whenever the default KVS is available. Examples include:

• run_identity_unavailable
• dataset_identity_unavailable
• input_not_object
• unknown_input_property
• authorization_not_confirmed
• source_context_required
• patent_count_invalid
• pricing_misconfigured
• pre_push_failed
• free_diagnostic_write_failed
• output_write_failed
• exit_failed

Post-push failure classes require special handling:

unknown_delivery

The linked pushData call threw. The Actor cannot prove whether the platform stored or charged the row. The run stops. replaySafe is false. Do not retry automatically.

settlement_unknown

The linked push returned, but the named counter or aggregate settlement evidence could not be read or validated. A positive bounded SDK aggregate proves that the Dataset callback completed, but named-event settlement remains unknown. The run stops and requires manual reconciliation.

settlement_anomaly

The returned Dataset/counter/aggregate facts contradict the allowed settlement lattice. The run stops. Do not reinterpret the row as paid or free from the Dataset metadata alone.

Failure truth lives in both the platform run status and the terminal receipt. If both primary and bounded recovery KVS writes fail, the platform failure status is the remaining authority. Never infer success from the absence of OUTPUT.

Current-run OUTPUT receipt

The terminal KVS record has these top-level fields:

Field	Meaning
schemaVersion	Receipt contract version 2.0.0.
kind	Closed product identifier authorized_patent_evidence_output.
status	COMPLETE, PARTIAL, or FAILED.
runId	Current hosted Actor run identity. A missing identity fails before Dataset delivery.
requestDigest	Digest of the normalized request without a raw legacy key or raw legacy query strings.
watchName	Buyer-provided batch label.
input	Requested, unique, duplicate, invalid, and legacy query counts.
run	Work, delivery, settlement, partial, budget, fatal, and replay counters.
delivery	Named event, before/after counters, exact confirmed delta, Dataset writes, and last attempt.
source	Zero-network mode and buyer-declared source context.
errors	Bounded code/message diagnostics.
resultsUrl	Current run's default Dataset API URL.
startedAt, completedAt	UTC run timestamps.
terminal	KVS write and exit outcome.

input counters

• requestedCount: modern patent records received.
• uniqueCount: valid unique modern patent records eligible for work.
• duplicateCount: valid modern records suppressed by (sourceName, patentId).
• invalidCount: modern records rejected by normalization.
• legacyQueryCount: old query values received. Their raw strings are not copied into the receipt.

For modern input:

requestedCount = uniqueCount + duplicateCount + invalidCount

Legacy queries are kept in a separate counter because they do not represent patent result work.

run counters

• attemptedCount: unique patent rows whose paid-delivery operation began.
• successfulCount: rows with a confirmed named result settlement.
• failedCount: attempted rows without confirmed success.
• deliveredRowCount: confirmed Dataset writes, including free diagnostics and a known Dataset write with unresolved named settlement.
• paidRowCount: exact confirmed named result events.
• freeRowCount: confirmed free diagnostic Dataset writes.
• withheldRowCount: unique normalized patent rows that were definitely not attempted/delivered.
• unknownDeliveryCount: linked operations for which Dataset delivery itself is unknown.
• unknownSettlementCount: known or potentially known Dataset delivery with unresolved settlement.
• normalizedPatentCount: confirmed paid normalized patent records.
• partial: true when diagnostics, withheld work, failed work, unknown state, budget stop, or fatal error exists.
• budgetStopped: true when the buyer's cap prevents more work or a confirmed final row exhausts the event limit.
• fatalError: terminal failure code or null.
• replaySafe: true only while no Dataset push attempt can create duplicate delivery. A new normal run can still incur a new automatic start event.
• safeToAutomate: always false for substantive patent decisions.

delivery fields

• eventName: exactly result-found.
• attemptedPushCount: all Dataset push attempts, including free diagnostics.
• resultChargeCountBefore: named event counter before result work.
• resultChargeCountAfter: last known named event counter.
• confirmedEventDelta: sum of exact named +1 settlements.
• confirmedDatasetWrites: known Dataset writes.
• lastAttempt: closed settlement facts for the most recent Dataset operation.

For a successful one-row canary, status is COMPLETE; requested, unique, attempted, successful, delivered, paid, and normalized counts are all 1; free, withheld, unknown, and failed counts are 0; and the named counter moves exactly 0 → 1. The receipt also binds the current run/Dataset, records networkRequestsMade:0, and sets replaySafe:false because a new run can deliver and charge the row again.

Field dictionary

Legacy compatibility fields

Field	Exact meaning
sourceQuery	Optional supplied grouping label; never executed.
found	True for a structurally accepted record, not an independently found patent.
matched	1 for an evidence row and 0 for a free advisory; not a source total.
patentId, title	Supplied identifier/title after closed validation; existence and status are unverified.
patentDate	Calendar-valid supplied date whose legal meaning remains source-defined.
assignee	Supplied text, not proof of current ownership.
abstractSnippet	Optional supplied excerpt, capped at 1,000 characters; transformations belong in changesMade.
url	Recorded HTTPS reference without credentials, port, or fragment; never fetched or endorsed.
summary	Deterministic review summary, not legal analysis.
checkedAt	Actor processing time, not publication or source-retrieval time.

Identity fields

Field	Exact meaning
stableId	Deterministic hash of lowercased sourceName + patentId; useful for joins, not a family identifier.
entityId	Supplied patentId for evidence rows; null for diagnostics.
rowDigest	SHA-256 of the closed row before the digest field; integrity signal, not source-authenticity proof.

Evidence and decision fields

Field	Exact meaning
sourceContext	Buyer-declared closed rights context; the underlying agreement is not verified.
jurisdiction, recordStatus	Supplied labels, never inferred or checked against a live register.
decision	review_required for evidence or no_eligible_result for diagnostics; always human-reviewed.
freshness	Age of the supplied retrieval timestamp against freshnessDays, not legal currency of the patent.
change	Always not_measured; v2.0 stores no cross-run baseline.
confidence	Mechanical evidence completeness and gaps, never legal, technical, market, or investment confidence.
evidence	Source name/URL/licence/change disclosure, retrieval time, digests, and zero-network fact.
recommendedAction, priority	Human routing derived from evidence/freshness, not patent value or legal risk.
failureDiagnostics	Null for evidence; closed reason/stage/retry detail for a free advisory.
billing	Pre-settlement eligibility/intent; current-run OUTPUT is authoritative for settlement.

Evidence and boundaries

The Actor can establish these mechanical facts:

• the request passed the closed runtime validator;
• unknown fields and malformed values were rejected;
• duplicates were removed with the documented identity key;
• the Dataset row includes the recorded licence and transformation statements;
• the record digest matches the canonical delivered row;
• the runtime made zero external network requests;
• the current-run result counter changed exactly as recorded when settlement is confirmed.

The Actor cannot establish:

• that the buyer had authority to export or submit the data;
• that the source licence statement is correct or applies to every field;
• that the patent office record exists or is current;
• that a named assignee currently owns any right;
• that a document is relevant to a product or technology;
• that a claim is valid, infringed, enforceable, essential, licensed, expired, abandoned, or in force;
• that a portfolio is complete;
• that an omitted record is absent from an authoritative source;
• that a source URL is safe or official;
• that a confidence score supports automated action.

safeToAutomate:false is therefore a contract invariant, not a conservative suggestion.

Sources and rights

Buyer-owned or authorized exports

Use buyer_owned_patent_export or rights_holder_authorized_export only when you have a documented right to process and commercially use the supplied records. A website being public or technically accessible is not itself a redistribution licence.

PatentsView exports

PatentsView documentation identifies the PatentSearch data/API licence as CC BY 4.0. A buyer using patentsview_cc_by_4_export must preserve appropriate credit, a licence reference, and an indication of changes. That is why sourceName, sourceUrl, sourceLicense, and changesMade are required.

Relevant source documentation:

• PatentsView PatentSearch documentation
• Creative Commons Attribution 4.0
• USPTO PatentsView overview

PatentsView research data is not a substitute for an official patent-office record or professional legal research. API availability, keys, limits, data coverage, and licence terms can change; verify them when obtaining the export.

Recorded patent links

The optional url field can point to an authorized source page. The Actor records but never fetches it. A Google Patents URL in a buyer-supplied record does not cause a Google request and does not grant permission to scrape or redistribute Google content.

Other licensed sources

Use other_licensed_patent_export only when the source agreement permits the intended downstream processing and delivery. Put a concise rights statement in sourceLicense and describe transformations in changesMade. Keep the full agreement in your own records rather than copying confidential contract text into public Dataset rows.

Privacy and responsible use

Patent records can contain inventor, applicant, assignee, representative, address, or other person-linked data. Even public-record information can remain personal data when it identifies or profiles a person.

Before running:

• confirm a lawful purpose and your role under applicable privacy law;
• submit only fields needed for that purpose;
• avoid home addresses, personal contact details, signatures, sensitive inferences, and confidential annotations;
• do not use the Actor to deanonymize, harass, profile, score, or target inventors;
• do not use a supplied assignee or inventor string as an employment, credit, insurance, housing, eligibility, or reputation decision;
• set Dataset/KVS retention and deletion policies appropriate to your organization;
• restrict access to runs and exports;
• document correction, objection, and deletion handling where required;
• review downstream joins that can turn an otherwise ordinary record into sensitive profiling.

The Actor does not intentionally log a legacy API key or copy it to results. However, Apify stores Actor input in the run KVS. Do not submit patentsviewApiKey; remove it from legacy Tasks. Rotate any secret that was exposed outside a secret input field.

Decision routing

Route 1: recent, complete evidence row

Use when freshness.status is fresh, provenance fields are complete, and gaps are limited to the universal no-verification/no-legal-analysis boundary.

Action: open the source, confirm the document identity and relevant passages, then add it to a human research queue.

Route 2: stale or timestamp-unknown evidence row

Use when freshness.status is stale or unknown.

Action: refresh the export from the authorized source before relying on status, assignee, or timing.

Route 3: incomplete content

Use when abstractSnippet, patentDate, assignee, jurisdiction, or url is null.

Action: decide whether those fields are necessary. Do not fill them with guesses. Obtain a better authorized export if required.

Route 4: duplicate diagnostic

Action: compare upstream records. If two rows represent different publications or jurisdictions, give them distinct source identifiers. Do not defeat deduplication by adding random suffixes.

Route 5: legacy migration diagnostic

Action: replace queries and any stored key with an authorized export. Keep the old Task only long enough to migrate consumers.

Route 6: unknown delivery or settlement

Action: stop automation. Reconcile the current run ID, Dataset, KVS OUTPUT, platform charged events, and logs. Do not submit the same input again until you know whether the prior operation landed and charged.

Commercial playbooks

Portfolio intake normalization

1. Obtain a permitted export from the portfolio system or licensed source.
2. Map its identifier, title, date, assignee, excerpt, status, and provenance fields to the v2.0 input.
3. Use a stable watchName for the intake batch.
4. Run with a cap that covers the expected unique record count plus the automatic start event.
5. Reconcile requestedCount, uniqueCount, duplicateCount, and invalidCount before importing results.
6. Send review_required rows to the portfolio team; do not treat the Actor's priority as a legal priority.

Competitive landscape reading list

1. Perform the search in a source your organization is authorized to use.
2. Export only the records and excerpts required for the research purpose.
3. Record the exact source name, source URL, licence, retrieval time, and transformations.
4. Normalize the export with this Actor.
5. Group downstream by buyer-declared technology labels, not by invented semantic classifications from this Actor.
6. Ask a subject-matter expert to review the actual documents.

Research vendor delivery QA

1. Require the vendor to identify the source and rights basis.
2. Run the delivered export through the closed schema.
3. Inspect invalid and duplicate diagnostics.
4. Compare the Dataset row count with OUTPUT.run.deliveredRowCount.
5. Verify that all paid rows retain attribution and transformation statements.
6. Reject any delivery that claims external verification this Actor did not perform.

Data warehouse ingestion

1. Store rowDigest, stableId, entityId, requestDigest, and runId as reconciliation keys.
2. Store the whole evidence object or an equivalent normalized provenance table.
3. Keep billing as intent metadata and join settlement from the current-run receipt.
4. Preserve nulls; do not turn missing assignee/date/status into confident values.
5. Version consumers against schemaVersion and reject unexpected major versions.

Integration recipes

Start a run with the Apify API

curl -X POST \
  "https://api.apify.com/v2/acts/zinin~patent-monitor/runs?token=$APIFY_TOKEN&maxTotalChargeUsd=0.015" \
  -H "Content-Type: application/json" \
  --data-binary @examples/input.json

Keep the token in an environment variable or secret manager. Do not place it in source code, logs, screenshots, or Dataset fields.

Poll the run

curl --fail --silent \
  "https://api.apify.com/v2/actor-runs/$RUN_ID?token=$APIFY_TOKEN"

Wait for a terminal platform status. Do not assume a started request succeeded.

Read the current-run receipt

curl --fail --silent \
  "https://api.apify.com/v2/key-value-stores/$KVS_ID/records/OUTPUT?token=$APIFY_TOKEN"

Require the receipt runId to equal the platform run ID. For a complete one-row result require status:COMPLETE, paidRowCount:1, confirmedEventDelta:1, unknownDeliveryCount:0, unknownSettlementCount:0, and no fatal error.

Read Dataset rows

curl --fail --silent \
  "https://api.apify.com/v2/datasets/$DATASET_ID/items?clean=true&format=json&token=$APIFY_TOKEN"

For an automated pipeline, validate each item against contract/dataset-item.schema.json and the semantic rules represented by validateRow. Structural JSON Schema alone cannot recompute the canonical row digest.

Webhook handling

If you attach an Apify run webhook:

1. authenticate the webhook according to your integration policy;
2. use the webhook only as a signal to read the platform run record;
3. require a terminal run status;
4. read current-run OUTPUT;
5. verify the run/Dataset/KVS identities;
6. accept paid records only after exact settlement reconciliation;
7. route partial and failed runs to review;
8. never automatically retry an ambiguous post-push outcome.

Schedule handling

Each scheduled run processes a new supplied snapshot. The Actor does not fetch new data and does not maintain a baseline. Your upstream system must update the patents array before each scheduled run. Reusing the same input creates another delivery attempt and another automatic start event.

Operating guide

Before the first production run

• Archive the source/licence evidence.
• Decide which fields are necessary.
• Remove personal or confidential data that is not necessary.
• Validate the export against the example schema locally.
• Set an Apify retention policy.
• Choose a run cap based on the maximum unique record count.
• Confirm downstream consumers understand that the product does not verify patents or make legal decisions.

After every run

• Confirm the exact Actor build and run status.
• Read OUTPUT from the current KVS.
• Compare Dataset length with deliveredRowCount.
• Compare paid rows with confirmedEventDelta.
• Inspect freeRowCount, withheldRowCount, and unknown counters.
• Review every failureDiagnostics object.
• Confirm source.networkRequestsMade is zero.
• Retain the run ID and hashes needed by your audit policy.

When the batch is partial

Do not discard the whole batch automatically. First identify why partial is true. A free duplicate diagnostic can coexist with valid confirmed paid rows. A budget stop means some normalized records were withheld. An unknown settlement requires manual reconciliation. A fatal input or identity failure means no paid work should have been attempted.

When a source export changes format

Do not map new fields by guessing. Update your exporter or adapter, keep the old fixture, add a new fixture, and verify the normalization. Unknown input fields fail closed so silent source drift cannot become a paid row.

When you need change monitoring

Store normalized rows in your own authorized system and compare stable fields under a documented diff contract. This Actor intentionally reports change.status:not_measured; it does not pretend that a supplied single snapshot proves a change.

When you need legal analysis

Use qualified counsel or an authorized patent professional. Give them the official documents and complete context. A Dataset row is an intake record, not a legal work product.

Acceptance checklist

Before treating a run as an accepted commercial delivery, require all applicable checks:

• Platform run used the intended immutable build.
• Platform status is terminal and consistent with OUTPUT.status.
• OUTPUT.runId equals the current run ID.
• OUTPUT.resultsUrl points to the current default Dataset.
• Source mode is buyer_authorized_export_only.
• Network requests and platform logins are both zero.
• Input work counters reconcile exactly.
• Attempted work reconciles to successful plus failed.
• Dataset rows reconcile to paid plus free plus any explicitly unresolved settlement row.
• Confirmed named event delta equals paid row count.
• No unknown delivery or settlement exists for an automatically accepted run.
• Every paid row has a source name, source URL, licence, change disclosure, and row digest.
• Every row says safeToAutomate:false.
• Duplicate, invalid, and legacy diagnostics are free of the named result event.
• Logs contain no secret and no unexplained source or settlement error.
• The buyer's rights, privacy, and retention controls are documented outside the Actor.

FAQ

Question	Answer
Does it search patents?	No. It normalizes supplied records; legacy queries create a free migration diagnostic and zero external requests.
Can I use a PatentsView export?	Yes only when your use satisfies current access and CC BY 4.0 terms. Preserve attribution, licence, and changesMade.
Does it use my legacy API key?	No. The field is accepted for compatibility but never read or sent. Remove old keys because Apify persists run input.
Does a recorded URL prove permission or current ownership?	No. URLs are never fetched; assignee/status values remain supplied evidence requiring authoritative review.
Is confidence legal confidence?	No. It measures mechanical evidence completeness only. safeToAutomate remains false for substantive decisions.
Are duplicates or invalid records billed?	They emit no named result event. A free diagnostic can report suppression/rejection while valid unique records continue.
What happens at the cap?	The Actor checks before each paid push. Definitely unattempted work is withheld; a final confirmed row remains paid even if it exhausts the event limit.
Can I retry a failed run?	Read the platform run and current-run OUTPUT first. Never blindly retry unknown delivery, settlement, or anomaly states.
Can it replace counsel or process secrets?	No. It is not legal advice. Do not submit confidential, privileged, export-controlled, or trade-secret material without approval.
What proves billing?	Current-run OUTPUT reconciled with platform events. Dataset billing fields express eligibility/intent only. Missing OUTPUT is not success proof.

Version and compatibility policy

Version 2.0 changes the product from live external search to normalization of authorized exports. It preserves the technical Actor slug and legacy Dataset fields. It also accepts the old query-shaped input and returns a structured free migration diagnostic rather than attempting the removed Google/PatentsView network path.

New fields are additive to the legacy Dataset names. Downstream consumers should select fields by name, preserve unknown additive fields, and gate material behavior on schemaVersion and recordType. The v2 contract is closed for inputs and runtime outputs to prevent silent source drift.

Future breaking changes will use a new major schema version. A new runtime must not silently reinterpret an existing field or change the paid unit.

Support information to include

When reporting a problem, include:

• Actor run ID;
• immutable build ID;
• OUTPUT.status and fatalError;
• Dataset and KVS IDs;
• request digest, not secret input;
• counts from input, run, and delivery;
• relevant bounded log lines with personal data removed;
• whether the issue occurred before or after a linked push attempt.

Do not include API tokens, PatentsView keys, private licence agreements, confidential patent text, personal contact details, or full raw platform responses.