# Apify Actor Idea Validator (`zinin/apify-actor-idea-validator`) Actor

Validate one proposed Apify Actor idea against current public Store similarity, activity, quality, competition, and visible pricing evidence. Get source coverage, confidence, gaps, and a manual validation action. Deterministic research without an LLM—not a revenue forecast.

- **URL**: https://apify.com/zinin/apify-actor-idea-validator.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** MCP servers, Developer tools
- **Stats:** 1 total users, 0 monthly users, 7.7% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $42.50 / 1,000 delivered store evidence reports

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

Learn more: https://docs.apify.com/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

## 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.

![Apify Actor Idea Validator: public Store evidence before development spend](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/5e30e56a0a41067879934b997348a37550d32697/commercial115/apify-actor-idea-validator/readme-hero.webp)

### 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`.

![Apify Actor Idea Validator: idea, Store cohort, evidence score and human validation action](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/5e30e56a0a41067879934b997348a37550d32697/commercial115/apify-actor-idea-validator/readme-workflow.webp)

### 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

```json
{
  "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:

```json
{
  "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.

```json
{
  "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.

```json
{
  "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

```bash
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

```javascript
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

```python
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:

```json
{
  "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](https://apify.com/zinin/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](https://apify.com/zinin/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](https://apify.com/zinin/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](https://apify.com/zinin/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.

# Actor input Schema

## `schemaVersion` (type: `string`):

Contract version for the business input.

## `requestId` (type: `string`):

Idempotency key for replay/conflict handling.

## `maxResults` (type: `integer`):

Maximum number of matched actors to keep in the detailed report.

## `freshnessMinutes` (type: `integer`):

Age limit for report-cache reuse. Set to 0 to bypass cache hits.

## `detailLevel` (type: `string`):

Compact or evidence-heavy output in the dataset row.

## `idea` (type: `object`):

Proposed Apify Actor concept to score against the public Store.

## Actor input object example

```json
{
  "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"
    ]
  }
}
```

# Actor output Schema

## `OUTPUT` (type: `string`):

API link to the authoritative terminal envelope in the default key-value store.

## `REPORTS` (type: `string`):

API link to useful validation reports in the default Dataset.

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

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/apify-actor-idea-validator").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 = {
    "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"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("zinin/apify-actor-idea-validator").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 '{
  "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"
    ]
  }
}' |
apify call zinin/apify-actor-idea-validator --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zinin/apify-actor-idea-validator"
        }
    }
}

```

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/JeyRrGG9gh6sUyaZf/builds/wIgY7o3ELTIGg6QCt/openapi.json