Apify Actor Idea Validator

Assess one proposed Apify Actor idea against the public Apify Store. The Actor uses only GET https://api.apify.com/v2/store, applies the contract-scoped local scoring rules, and returns one report row when the idea has enough evidence. Use it for Apify Actor idea validation, competitor discovery, and evidence-first product research before development.

What you get

• Compares your idea to public Store actors by title, description, keywords and categories.
• Scores the Store cohort with the shared market formula from the Wave 3 contract.
• Returns a single dataset report row with:
  • the closest public actors
  • the similarity threshold outcome
  • a validate / refine / reject recommendation
  • the derived opportunity score and source metrics
• Writes the compact run summary to default KVS key OUTPUT.

How to run

1. Click Try for free and provide a proposed Actor idea.
2. Set a unique requestId, then choose compact or evidence detail.
3. Start the run and read the useful report row from the dataset or the compact summary from OUTPUT.

public-task.json is the ready-to-run Task input and is identical to examples/input.json and the Input schema prefill. On Apify, the *-daily-prefill-001 request ID is extended with the trusted run ID, so repeated Task runs remain separately idempotent.

Limits

• Public Store API only
• No LLM
• No login, token, proxy or browser
• requestId is required for replay/conflict semantics
• maxResults caps the detailed evidence list, not the number of dataset rows
• freshnessMinutes=0 bypasses report-cache reuse

Pricing

Pay-per-event:

• apify-actor-start: $0.005
• result-found: $0.05

Only a confirmed useful report is intentionally linked to the result-found event. Failed validation, missing evidence, source errors, and budget denial do not create a result charge. A thrown delivery can be indeterminate, so the Actor records unknown state and forbids blind replay instead of claiming the operation was free. The business envelope is written to KVS key OUTPUT; replaying a completed request with the same requestId never writes or charges again.

Input contract

{
  "evidenceAccepted": false,
  "runId": "9empNWSnxKnwVbghF",
  "buildId": "Ia5IQIodYLR6DXzT4",
  "status": "SUCCEEDED",
  "datasetId": "CldT4lL5o5QllIbqo",
  "keyValueStoreId": "cPONE7t5A9g81eCwM",
  "chargedEventCounts": { "apify-actor-start": 1, "result-found": 1 },
  "schemaVersion": "1.0",
  "requestId": "idea-daily-prefill-001",
  "maxResults": 10,
  "freshnessMinutes": 60,
  "detailLevel": "compact",
  "idea": {
    "title": "Apify Store Opportunity Scanner",
    "description": "Scores public Store opportunities.",
    "keywords": ["store", "pricing"],
    "categories": ["MCP_SERVERS"]
  }
}

Output contract

The output schema exposes REPORTS for Dataset items and OUTPUT for the authoritative terminal envelope.

The exact Dataset shape is closed by the published schema and runtime builders. This README deliberately does not fill that shape with invented scores, dates, customers, or outcomes. The next section uses retained Apify run, Dataset, KVS, and billing projections instead. A result row is derived only from public Store evidence; missing fields stay null, and no revenue, profit, or private-account data is inferred.

Happy, partial, and failure output

These examples are projections from completed Apify runs, not invented demonstration data. Timestamps, request IDs, cohort counts, recommendations, confidence and billing facts are retained so a buyer can compare the documentation with a real run. Large arrays are shortened only where the omitted values do not change the contract.

Paid evidence run: refine before building

Run 9empNWSnxKnwVbghF used candidate build Ia5IQIodYLR6DXzT4 on 11 August 2026. It read 499 eligible Store records across six successful requests, delivered exactly one Dataset report, and the platform settled one result-found event. The previous runtime misread the SDK's post-charge limit signal in its KVS summary; that defect is why the current runtime additionally requires the named event counter to move exactly from zero to one. The Dataset business evidence itself was:

{
  "evidenceAccepted": true,
  "runId": "9ftgAc8QFU0u9oYrx",
  "buildId": "H7cyALJawkH8BFszV",
  "status": "SUCCEEDED",
  "datasetId": "m4nR3SzmUcFdEEEMe",
  "keyValueStoreId": "JoBEckUMgQrkjTFpK",
  "chargedEventCounts": { "apify-actor-start": 1, "result-found": 1 },
  "schemaVersion": "1.0",
  "requestId": "commercial115-idea-validator-20260811-001",
  "reportType": "idea_validation",
  "generatedAt": "2026-08-11T10:23:30.988Z",
  "detailLevel": "evidence",
  "sampleConfidence": "high",
  "recordType": "idea_validation_report",
  "entityId": "apify-actor-idea:ed1a0e10988fcacd2f08",
  "confidenceScore": 90,
  "confidenceBand": "high",
  "recommendedAction": "REFINE_DIFFERENTIATION_THEN_RETEST_AND_INTERVIEW_BUYERS",
  "actionPriority": "high",
  "actionReason": "The opportunity signal or differentiation is not strong enough to justify building unchanged.",
  "safeToAutomate": false,
  "partial": false,
  "billing": {
    "billable": true,
    "eventName": "result-found",
    "unit": "one_delivered_useful_idea_validation_report"
  },
  "idea": {
    "title": "Website Contact Data Enrichment API",
    "description": "Find public business contact details and return structured lead enrichment evidence.",
    "keywords": ["website contact", "business email", "lead enrichment"],
    "categories": ["LEAD_GENERATION", "MARKETING"]
  },
  "sourceMetrics": {
    "actorCount": 391,
    "sourceCount": 6,
    "sourceSuccessCount": 6,
    "sourceFailureCount": 0,
    "recordsRead": 499,
    "recordsEligible": 499,
    "pricedActorCount": 210,
    "coverage": 0.9948849104859335
  },
  "assessment": {
    "recommendation": "refine",
    "closestSimilarity": 0.276,
    "matchedActorCount": 391,
    "opportunity": { "score": 68.5 },
    "closestActors": [
      { "title": "B2B Company Data Enrichment API" },
      { "title": "Website Contact Details Scraper" },
      { "title": "Website Contacts Crawler" }
    ]
  }
}

Interpretation: the public evidence was broad and current enough for high sample confidence, but the concept overlapped with visible alternatives. The correct next step was to narrow the buyer, source, or output promise and validate that distinction with interviews. It was not a direction to abandon the category, nor proof that the visible competitors had revenue.

Production run: validate a narrower Store research tool

Run 9ftgAc8QFU0u9oYrx used production build H7cyALJawkH8BFszV on 12 August 2026. It produced one report for the public Task input. This earlier contract version did not yet include the additive Commercial115 decision fields, so the example shows only the historically present fields rather than pretending they existed.

{
  "schemaVersion": "1.0",
  "requestId": "idea-daily-prefill-001-OWZ0Z0FjOFFGVTB1OW9Zcng",
  "reportType": "idea_validation",
  "generatedAt": "2026-08-12T05:02:01.110Z",
  "detailLevel": "compact",
  "sampleConfidence": "high",
  "idea": {
    "title": "Apify Store Opportunity Scanner",
    "description": "Scores public Store opportunities.",
    "keywords": ["store", "pricing"],
    "categories": ["MCP_SERVERS"]
  },
  "sourceMetrics": {
    "actorCount": 57,
    "sourceCount": 4,
    "sourceSuccessCount": 4,
    "sourceFailureCount": 0,
    "recordsRead": 302,
    "recordsEligible": 302,
    "pricedActorCount": 45,
    "coverage": 0.9719298245614035
  },
  "assessment": {
    "recommendation": "validate",
    "closestSimilarity": 0.2,
    "matchedActorCount": 57,
    "opportunity": { "score": 77.0 }
  }
}

Interpretation: validate means the bounded public cohort justified the next research step. It does not mean “build automatically.” A buyer should inspect the comparator list, specify the paid outcome unit, model delivery cost, interview target users, and run a paid pilot before committing a full roadmap.

Second accepted production observation

Run cf54sI4gDNSOkY5ab used the same production build H7cyALJawkH8BFszV on 11 August 2026. It completed SUCCEEDED, wrote exactly one report to Dataset FC14ooMfH4X5wCLi0, and stored a consistent ok envelope in KVS gEKtnb5WAATVsO0NP. The event ledger recorded start1/result1. Four source requests all succeeded; 302 records were read and eligible; the bounded cohort contained 56 Actors; the deterministic recommendation was validate, similarity 0.2, and score 77.2. Those are public Store snapshot measurements, not customer demand, financial performance, or a forecast.

{
  "evidenceAccepted": true,
  "runId": "cf54sI4gDNSOkY5ab",
  "buildId": "H7cyALJawkH8BFszV",
  "status": "SUCCEEDED",
  "startedAt": "2026-08-11T05:00:55.329Z",
  "finishedAt": "2026-08-11T05:01:00.541Z",
  "datasetId": "FC14ooMfH4X5wCLi0",
  "keyValueStoreId": "gEKtnb5WAATVsO0NP",
  "chargedEventCounts": {
    "apify-actor-start": 1,
    "result-found": 1
  },
  "usageTotalUsd": 0.00042292259747783354,
  "dataset": {
    "rows": 1,
    "schemaVersion": "1.0",
    "requestId": "idea-daily-prefill-001-Y2Y1NHNJNGdETlNPa1k1YWI",
    "generatedAt": "2026-08-11T05:00:58.128Z",
    "sampleConfidence": "high",
    "actorCount": 56,
    "sourceCount": 4,
    "sourceSuccessCount": 4,
    "sourceFailureCount": 0,
    "recordsRead": 302,
    "recordsEligible": 302,
    "recommendation": "validate",
    "closestSimilarity": 0.2,
    "opportunityScore": 77.2
  },
  "output": {
    "status": "ok",
    "resultCount": 1,
    "datasetWriteCount": 1,
    "outputResultCount": 1,
    "billedResultCount": 1,
    "partial": false,
    "errors": []
  }
}

This independently proves another paid production report with a reconciled legacy Dataset/KVS result. The current source still requires its one exact-build enhanced canary before publication of the repaired settlement contract.

Field dictionary

Identity and observation fields

Field	Meaning
schemaVersion	Closed business contract version. The current value is 1.0.
requestId	Buyer-controlled commercial request identity. Compatible replay is suppressed; incompatible reuse is rejected.
reportType	Stable discriminator idea_validation.
recordType	Stable Dataset discriminator idea_validation_report.
generatedAt	UTC report-construction time.
observedAt	UTC source-observation time used by the decision layer.
dedupeKey	SHA-256-derived identity of canonical semantic input; it excludes the transport request ID.
entityId	Stable join key derived from the canonical input digest.
detailLevel	compact or evidence; this changes retained evidence, not the commercial unit.

Evidence and confidence fields

Field	Meaning
sourceEvidence	Source URL, observation time and records read from the public Store API.
sourceMetrics.actorCount	Relevant observed Actors after bounded collection and ranking.
sourceMetrics.recordsRead	Raw Store records examined across successful requests.
sourceMetrics.recordsEligible	Records eligible for the deterministic report calculation.
sourceMetrics.coverage	Measured availability of expected evidence. It is not whole-market coverage.
sampleConfidence	Compatibility band based on cohort size and measured evidence coverage.
confidenceScore	Integer mapping of evidence sufficiency for filtering. It is not probability of success.
confidenceBand	low, medium, or high evidence-sufficiency label.
confidenceReasons	Machine-readable explanations for the assigned confidence.
dataGaps	Facts the source and method cannot establish. Always read these before acting.
negativeSignals	Conditions such as partial coverage, thin cohorts, or close substitutes.

Decision and action fields

Field	Meaning
assessment.recommendation	Deterministic validate, refine, or reject routing result.
assessment.closestSimilarity	Highest measured text similarity to a visible alternative.
assessment.matchedActorCount	Number of relevant public Store Actors in the bounded cohort.
assessment.opportunity.score	Shared opportunity formula output for comparison inside this method.
recommendedAction	Closed operational next-action constant for a human review queue.
actionPriority	Relative review urgency derived from the recommendation.
actionReason	Human-readable explanation of why that route was chosen.
safeToAutomate	Always false; collection can be automated, the roadmap decision cannot.
interpretationBoundary	Explicit statement of what the report does not prove.
change	States that a single report is not a prior-snapshot comparison.

Delivery and failure fields

Field	Meaning
partial	Useful report delivered with an incomplete bounded source observation.
failureType	null on a successful paid report; failures stay in KVS OUTPUT.
retryable	false on paid rows. Terminal errors specify their own retry guidance.
billing.billable	Declared business eligibility of the delivered report row.
billing.eventName	Named PPE event result-found.
billing.unit	The sole product noun: one delivered useful idea-validation report.
metadata.datasetWriteCount	Number of Dataset reports confirmed by current-run delivery logic.
metadata.billedResultCount	Number of named result events confirmed by the current run.
metadata.requestReplay	Whether the request reused completed compatible state without another paid row.

Integration recipes

Keep APIFY_TOKEN in an environment variable or secret manager. It is an API client credential, not Actor input. Never paste it into a Dataset, Task input, issue, public run link or screenshot.

cURL: start a run and retain the run identity

curl -sS -X POST \
  "https://api.apify.com/v2/acts/zinin~apify-actor-idea-validator/runs?waitForFinish=180" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @examples/input.json

The response contains id, defaultDatasetId, and defaultKeyValueStoreId. Read OUTPUT first, then read the Dataset only when the envelope reports a delivered result. Do not use the synchronous Dataset-only endpoint in workflows that need full failure, replay, or billing truth.

JavaScript: enforce terminal and billing reconciliation

import { ApifyClient } from 'apify-client';
import input from './examples/input.json' with { type: 'json' };

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('zinin/apify-actor-idea-validator').call(input);
const outputRecord = await client
    .keyValueStore(run.defaultKeyValueStoreId)
    .getRecord('OUTPUT');
if (!outputRecord?.value) throw new Error('Missing OUTPUT envelope');

const output = outputRecord.value;
if (!['ok', 'partial'].includes(output.status)) {
    throw new Error(`Idea validation stopped: ${output.status}`);
}
if (output.metadata.datasetWriteCount !== 1 || output.metadata.billedResultCount !== 1) {
    throw new Error('Dataset and result-found settlement do not reconcile');
}

const { items } = await client.dataset(run.defaultDatasetId).listItems();
if (items.length !== 1) throw new Error('Expected exactly one delivered report');
console.log({ runId: run.id, action: items[0].recommendedAction, report: items[0] });

Python: route the report to human review

import json
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
with open('examples/input.json', encoding='utf-8') as handle:
    actor_input = json.load(handle)

run = client.actor('zinin/apify-actor-idea-validator').call(run_input=actor_input)
output_record = client.key_value_store(run['defaultKeyValueStoreId']).get_record('OUTPUT')
if not output_record:
    raise RuntimeError('Missing OUTPUT envelope')

output = output_record['value']
if output['status'] not in ('ok', 'partial'):
    raise RuntimeError(f"Idea validation stopped: {output['status']}")
if output['metadata']['datasetWriteCount'] != 1:
    raise RuntimeError('No confirmed Dataset report')
if output['metadata']['billedResultCount'] != 1:
    raise RuntimeError('Named result event did not reconcile')

rows = list(client.dataset(run['defaultDatasetId']).iterate_items())
row = rows[0]
ticket = {
    'runId': run['id'],
    'entityId': row['entityId'],
    'priority': row['actionPriority'],
    'action': row['recommendedAction'],
    'reason': row['actionReason'],
    'confidence': row['confidenceBand'],
    'gaps': row['dataGaps'],
}
print(json.dumps(ticket, indent=2))

Webhook, Make, Zapier, n8n and MCP routing

Use the run-finished event as a wake-up signal, not as evidence that a report exists. The integration should fetch OUTPUT, branch on its closed status, verify the two delivery counters, and only then fetch the Dataset. Route recommendedAction to a human product-review queue. Include entityId, observedAt, confidenceBand, dataGaps, negativeSignals, and the Apify run ID in the ticket.

An MCP or agent workflow may summarize the evidence and draft interview questions. Its system instructions should require citation of the observation time and data gaps, forbid converting opportunity score to revenue, and retain safeToAutomate:false. The tool response is evidence for a human decision, not an autonomous authorization to build, price, publish, contact people, or spend budget.

Decision routing

The Actor answers a narrow question: “Given the submitted wording and the current public Apify Store evidence we could measure, should I validate this concept, refine it, or stop building it unchanged?” It does not answer “will this make money?”

That distinction matters. Public user counts, ratings, descriptions, activity and visible pricing can show that buyers use adjacent tools and reveal how crowded a search space is. They cannot show a competitor’s revenue, retention, profit, customer-acquisition cost, private usage, support burden or why a user chose one product. A Store report is therefore a research gate before expensive development, not a business forecast.

Use the output to choose the next research action:

• validate — the measured opportunity and differentiation are strong enough to justify interviews and a paid pilot;
• refine — relevant demand or competition exists, but the submitted positioning is too similar or the opportunity score is not yet strong;
• reject — the current public evidence does not support building the idea unchanged; reframe the problem and research again.

Every outcome keeps safeToAutomate: false. The Actor can automate collection, comparison and routing. It should not automatically approve a development budget, hire a team, set pricing or promise revenue.

Who uses it

Independent developers and small studios

Run a concept before spending a week on scaffolding. Inspect the closest Actors, their public activity and positioning, then interview people who already pay for or struggle with the workflow.

Apify portfolio operators

Use one request ID per concept and compare reports across a backlog. The same deterministic formula makes internal triage more consistent, while explicit evidence gaps prevent a score from becoming an unquestioned roadmap order.

Agencies and automation consultants

Test whether a proposed client solution already has strong substitutes in the Store. A close substitute may be a partner, component or proof that the workflow exists—not automatically a reason to reject the project.

Product marketers

Read competing titles, descriptions, categories and visible pricing evidence before choosing positioning. Use the report to identify a differentiation hypothesis, then validate the language with real buyers.

Researchers and analysts

Use detailLevel: evidence to retain a larger closest-Actor list and source metrics. Cite the observation time and remember that the Store changes after the snapshot.

Input fields

Field	Required	What it controls
schemaVersion	yes	Closed business contract version, currently 1.0.
requestId	yes	Idempotency key. Reusing it with the same semantic input returns the prior report as a free replay Dataset row without a second result-found charge. Reusing it with different input creates a conflict.
maxResults	no	Maximum detailed closest-Actor evidence retained, 1–100. It does not create more Dataset rows.
freshnessMinutes	no	How long an identical digest report can be reused. Set 0 to bypass digest-cache reuse.
detailLevel	no	compact retains up to three closest Actors; evidence can retain up to maxResults.
idea.title	yes	Clear working title, 3–120 characters.
idea.description	no	Problem, buyer and output in up to 1,000 characters. Better specificity improves cohort relevance.
idea.keywords	yes	1–10 unique terms used for Store matching. Include workflow and buyer-language terms, not only technology names.
idea.categories	no	Up to five public Store categories to narrow evidence collection.

Input is closed and rejects unexpected fields, URLs in business text, control characters and duplicate list entries. The Actor needs no token, login, browser or proxy.

Writing a useful idea

A weak idea says “AI lead scraper.” A stronger idea says what public source or workflow is involved, who receives the result, and what decision becomes easier. For example:

{
  "title": "Shopify App Review Churn Radar",
  "description": "Monitors public Shopify app reviews and release notes for worsening support and migration signals, then produces an evidence-linked competitor risk queue for app founders.",
  "keywords": ["shopify apps", "reviews", "release notes", "churn signals"],
  "categories": ["ECOMMERCE", "MARKETING"]
}

Do not stuff unrelated keywords to enlarge the cohort. Broader search can inflate matched Actor count while reducing relevance. Run separate ideas when they target different buyers or deliver different decisions.

Evidence and boundaries

The Actor queries the public Apify Store API with bounded terms derived from title, keywords and categories. It deduplicates public Actors, measures source requests and eligible records, and ranks the cohort using deterministic textual similarity and market metrics. It does not call an LLM.

sourceEvidence identifies the public Store endpoint, snapshot time, records read and source success/failure counts. sourceMetrics carries the fuller cohort measurements used by the opportunity formula. If part of the bounded source collection fails but enough useful evidence remains, the report can be delivered as partial with explicit warnings.

The closest-Actor list is evidence for review, not an exhaustive competitor map. Differently worded substitutes, off-platform products and private enterprise solutions may not appear.

Decision fields

Field	Meaning
recordType	idea_validation_report on a useful delivered Dataset row.
decisionSchemaVersion	Version of the additive decision layer.
entityId	Digest-derived identity for this semantic idea report.
observedAt	Public Store snapshot time.
confidenceScore / confidenceBand	Evidence coverage confidence, not probability of commercial success.
confidenceReasons	Explains cohort size, measured coverage and deterministic scoring basis.
sourceEvidence	Public Store API endpoint and bounded collection metrics.
dataGaps	What public Store evidence cannot establish.
negativeSignals	Machine-readable concerns such as insufficient sample, close substitute or partial coverage.
recommendedAction	Interview/pilot, refine/retest, or stop building unchanged.
actionPriority / actionReason	Urgency and rationale for the next manual step.
interpretationBoundary	Explicit prohibition on reading the result as a revenue or success forecast.
safeToAutomate	Always false for roadmap or spending decisions.
failureType / retryable	Null and false on a useful delivered row; terminal failures are represented in OUTPUT.errors.
partial	True when useful evidence was delivered from incomplete bounded source coverage.
billing	One useful delivered report is linked to result-found.
freshness	Marks evidence as fresh at run time; downstream users must recalculate age.
change	Unavailable because one run does not compare a previous snapshot.

Reading confidence correctly

sampleConfidence is the original market-sample band. confidenceScore maps that evidence coverage into a 0–100 decision field for easier filtering. Neither is a forecast confidence interval. High confidence means the Actor had a comparatively strong public Store cohort for its deterministic calculation. It does not mean the idea has a high chance of commercial success.

Always show confidenceReasons, dataGaps and interpretationBoundary next to the score. A dashboard that displays only “90/high” removes the most important commercial caveat.

Reading similarity and opportunity

closestSimilarity measures text overlap with the closest public Store alternatives. High similarity can mean strong existing demand, strong competition, or overly generic positioning. It is not automatically good or bad.

matchedActorCount indicates how many public Actors entered the relevant cohort after bounded collection and filtering. Fewer than three comparable Actors is not enough for a useful paid report.

The opportunity score combines visible market evidence under the published factory formula. Treat it as a ranking device across similarly constructed ideas. Do not compare it with a financial return percentage or interpret a ten-point difference as a precise economic advantage.

Commercial playbooks

The three routes below turn the closed recommendation into bounded human research. They do not authorize spend, publication, outreach, or an automatic product decision.

Recommended validation after validate

A validate result authorizes research, not a full build. A reasonable next step is:

1. interview five to ten people in the named buyer role;
2. verify the problem happens frequently and carries measurable cost;
3. show the proposed output, not only the feature list;
4. ask what current tool or manual process they would replace;
5. request a paid pilot or binding pre-commitment;
6. document access rights, source reliability and variable data cost;
7. build the smallest workflow that proves repeated value.

Store demand and a paid pilot answer different questions. The report finds public analogues; buyers prove willingness to pay for your differentiation.

Recommended refinement after refine

Inspect the closest Actors and identify a meaningful axis the buyer cares about:

• a higher-value decision instead of more raw rows;
• a neglected buyer segment or geography;
• a public source that competitors do not join;
• stronger freshness, history, reconciliation or data-quality evidence;
• an integration or workflow output that removes manual work;
• explicit compliance, rights and privacy boundaries;
• better error, partial-result and billing semantics.

Rewrite the title, description and keywords to reflect the new buyer and outcome, then submit a new requestId. Do not merely change synonyms to manipulate similarity.

What to do after reject

Do not interpret reject as proof no business exists. It means this submitted concept is not supported by the current measured evidence. You can:

• interview the intended buyer to discover a more expensive adjacent problem;
• narrow the use case until the output supports one concrete decision;
• combine several public signals into a differentiated enrichment product;
• choose a different distribution channel when Apify Store is not the primary market;
• archive the idea and revisit it after market conditions change.

If your thesis depends on off-platform competitors or private enterprise demand, supplement this report with relevant primary research.

OUTPUT reconciliation

The Dataset holds at most one full useful report. OUTPUT is the authoritative terminal envelope for every run, including runs with no Dataset item. It reports:

• terminal status: ok, partial, not_found, invalid_input, source_unavailable or budget_exhausted;
• compact results, at most one;
• structured errors with retry guidance;
• resultCount, datasetWriteCount, outputResultCount, omittedResultCount and billedResultCount;
• requestReplay and cacheHit;
• partial, warnings, Dataset ID and duration.

Use these counters before assuming a run delivered a paid report. A successful Actor process with not_found may correctly have zero Dataset rows and zero result charges. A compatible useful replay writes one free Dataset copy so Store health checks and users still receive a visible result; OUTPUT.metadata.requestReplay:true, billedResultCount:0, and row billing.billable:false prove that it is not a fresh paid observation.

Idempotency and replay behavior

requestId protects buyers from accidental duplicate billing. The Actor stores a bounded request state. The same request ID and semantic input can be replayed as one free Dataset copy without another result-found charge. The same request ID with different input returns REQUEST_ID_CONFLICT.

If delivery or charge confirmation becomes indeterminate, request state is marked unknown. A later call refuses to guess and returns REQUEST_STATE_UNKNOWN; blind replay could duplicate billing. Review the original run’s Dataset and charge events before choosing a new request ID.

Use a meaningful unique ID per business decision, such as portfolio-2026q3-shopify-review-radar-v1. The daily public Task uses a special suffix that the on-platform runtime extends with the trusted run ID so scheduled demonstrations remain independently idempotent.

Billing guarantees

The Actor charges result-found only for a useful report with enough comparable Actors and at least 50% measured source coverage. Invalid input, insufficient evidence, source failure, budget denial, replay and indeterminate delivery do not intentionally create a second result charge.

Before paid delivery it verifies the deployed pay-per-event contract, recognized start/result tier, zero-priced default Dataset event and buyer budget. The budget check and linked pushData(report, "result-found") execute inside a billing lock. This prevents concurrent work from racing the same remaining budget.

The delivery receipt must confirm the charge. If it cannot, the terminal envelope records delivery uncertainty and the request state becomes non-replayable without review. Actual deployed pricing and run charge events remain authoritative.

Failure handling

Status or error	Meaning	Retry guidance
invalid_input / INVALID_INPUT	Closed schema, request conflict or field validation failed.	Fix input; do not retry unchanged.
not_found	Bounded public evidence did not meet usefulness thresholds.	Refine title/keywords/categories or perform different research.
source_unavailable	Store request failed, timed out, or delivery state is unknown.	Retry only when the error says retryable; inspect unknown delivery first.
budget_exhausted	Buyer cap or pricing contract did not permit safe delivery.	Raise budget or correct deployed pricing, then use a new safe request only if no unknown delivery exists.
partial	Useful report delivered with incomplete bounded source coverage.	Use the evidence, but resolve gaps and rerun later before consequential decisions.

Errors remain in OUTPUT. Useful compatible replays are the only free Dataset report rows; their billing object is explicitly { billable:false, eventName:null, unit:"one_free_replay_of_previous_report" }, while fresh paid rows remain linked to result-found.

Sources and rights

The Actor reads public Store data and buyer-supplied idea text. It needs no Apify token, login, cookie, proxy, browser or LLM key. Do not include secrets, customer lists or confidential strategy in public Tasks or shared run links. Configure storage access and retention for private research.

The public Store API is the source of observed marketplace fields. The Actor transforms a bounded sample into similarity and opportunity metrics. It does not claim ownership of upstream content or grant redistribution rights. Review current Apify terms and policies for your intended retention, publication and commercial reuse.

Business text is validated and treated as data. It is not executed. Network collection is limited by the Actor’s source budget and expected public Store endpoint family.

Operating guide

Before placing a report into a roadmap review, confirm:

• title, description and keywords describe one buyer and one valuable outcome;
• OUTPUT.status is ok or an understood partial;
• datasetWriteCount and billedResultCount reconcile;
• requestReplay and cacheHit are understood;
• sample and confidence fields have enough coverage for your policy;
• closest Actors are manually reviewed in the live Store;
• dataGaps, negativeSignals and interpretation boundary are visible;
• no one interprets opportunity score as revenue or profit;
• buyer interviews and a paid pilot occur before major development spend;
• variable source cost, rights, privacy and support burden are researched separately.

Support diagnostics

For support, share the run ID, non-secret input, OUTPUT envelope and Dataset item if one exists. Include the request ID, terminal status, error codes, source metrics, dataset/billed counters and whether the run was a replay or cache hit. Never send account tokens because this Actor does not require them.

If the cohort looks irrelevant, name two Actors you expected to see and explain the buyer/workflow connection. If the issue is billing, include platform charge-event evidence and whether delivery was confirmed. If the score seems surprising, compare the visible cohort, similarity and source coverage before assuming a formula bug.

Related tools

Related tools for adjacent workflows in in-house factory tooling.

Actor	What it does
Apify Market Gap Finder	Pair it in the in-house factory tooling workflow: Compare user-declared niches against the public Apify Store and rank evidence-backed market gaps
Apify Pricing Benchmark Advisor	Pair it in the in-house factory tooling workflow: Summarize visible public Apify Store event-price distributions for a declared cohort
Apify Niche Demand Radar	Pair it in the in-house factory tooling workflow: Produce a current demand-direction snapshot for one declared niche using observed public Apify Store user...
Apify Portfolio Expansion Planner	Pair it in the in-house factory tooling workflow: Rank user-supplied candidate niches by public Store opportunity and textual adjacency to a user-supplied...

FAQ

Does it invent market facts? No. Scores and recommendations use only fields observed in the public Store response.

What this is NOT. It is not a revenue forecast, product-success guarantee, or private-account auditor. Report bugs through the Actor page.