Keyword Fanout — Recursive Long-Tail Discovery

Turn seed phrases into a bounded graph of Google autocomplete keyword ideas. Each dataset row is a unique source-returned phrase with observed seed topics, parent paths, discovery depth, locale hints and collection time. Use it to research content angles and prepare a shortlist for separate keyword-metric analysis.

Start with a small topic

{
  "seedKeywords": ["standing desk"],
  "expansions": ["base", "questions", "comparisons", "prepositions"],
  "maxDepth": 2,
  "branchFactor": 3,
  "maxRequests": 50,
  "maxResults": 200,
  "minWords": 3,
  "language": "en",
  "country": "US"
}

The first level queries each seed with the selected patterns. Deeper levels query up to branchFactor previously unseen suggestions from each response. The frontier is traversed breadth first. At most maxRequests source attempts and maxResults unique result rows are allowed. Default depth is 2; maximum depth is 4. Source calls run sequentially, with a default 300 ms delay and a 10 second timeout. There are no automatic retries or paid provider fallbacks.

What a row means

Every result was returned in an autocomplete response. Merely constructing how standing desk or another modifier query never creates a result. Case, whitespace and equivalent Unicode variants are deduplicated across seeds. The original seed phrases are excluded from results.

This abbreviated illustrative result explains the graph fields:

{
  "keyword": "best standing desk for home office",
  "seedKeywords": ["standing desk"],
  "depth": 1,
  "wordCount": 7,
  "isLongTail": true,
  "intent": "commercial",
  "intentMethod": "english-rule-heuristic-v1",
  "language": "en",
  "country": "US",
  "source": "google-autocomplete",
  "discoveryPaths": [{
    "seedKeyword": "standing desk",
    "parentKeyword": "standing desk",
    "query": "best standing desk",
    "depth": 1,
    "expansion": "comparisons"
  }]
}

Actual rows also include a run-local stable id, retrievedAt, each path's sourceUrl and retrievedAt, and pathsMayBeTruncated. Up to 20 distinct observed paths are retained for each phrase. At later levels, parentKeyword identifies the returned phrase queried to discover the child. seedKeywords groups observed source relationships; it is not an inferred semantic cluster.

intent uses simple English rules and returns unknown when no rule applies or another language is selected. wordCount counts whitespace-separated tokens; isLongTail means three or more such tokens. These are transparent heuristics, not demand measurements. This Actor does not return search volume, CPC, keyword difficulty, SERP rankings or People Also Ask results.

Workflow story

A content planner researching standing desks runs a small discovery job, groups phrases by observed seed and intent, and inspects the parent paths behind a promising angle. They export a shortlist to a volume tool before commissioning an article. A nested suggestion is evidence that the source returned that phrase, not proof of traffic or low competition.

For direct query-by-query suggestion arrays, use Google Autocomplete Suggestions API. To measure a researched shortlist, use Keyword Search Volume API.

International research and filters

Set language and country to the requested market hints. For Arabic, Urdu, Chinese or another language, select expansions: ["base"] and supply native-language suffixes through customModifiers. Built-in question, comparison and preposition patterns use English; alphabet mode uses a–z. Set minWords: 1 for languages that do not separate words with spaces.

excludeKeywords applies literal case-insensitive substring filters before output and recursive scheduling. Short source phrases can still be explored to discover longer children. A separate branchFactor cap chooses the first eligible unseen phrases in source order, so broad coverage may require several focused runs. Seeds are processed in input order; small request caps can leave later seeds untouched.

Output, limits and honest failures

Read OUTPUT and RUN_SUMMARY as well as the dataset. COMPLETE means the configured bounded graph traversal finished. PARTIAL means useful rows were saved but a source request failed or a request, result, deadline or charge boundary stopped work. VALID_EMPTY means zero delivered rows; inspect warnings to distinguish no matching suggestions from a charge cap that prevented work. Invalid inputs return INVALID_INPUT with no row events. If requested source work failed and no useful rows were found, the run fails with UPSTREAM_FAILED. Runtime or configuration failures use CONFIG_ERROR.

Source availability and autocomplete content vary. The undocumented native autocomplete route can change or throttle. Language and country are hints, and source order is not a search-volume ranking. Requests are bounded, not an exhaustive map of every possible phrase.

Progress is stored in the run's key-value store with an input/build fingerprint. Completed query results and delivered rows are reused on resurrection. Interrupted source attempts still consume the request budget. Dataset writes and event charges are not a transaction: an ambiguous pending delivery stops further billing and requires reconciliation against dataset and charge evidence. It is never blindly replayed.

Pricing configuration

This is a local candidate; no live Actor price is configured yet. The draft is $1.50 per 1,000 unique saved keyword rows, plus Apify platform usage, with no startup event. Confirm effective event prices and usage payer in the live Pricing tab after private deployment.

Only accepted dataset rows trigger keyword-discovered. Duplicate suggestions, generated modifiers, filtered phrases, empty responses and failed source calls have no keyword event. Platform usage still accrues for work performed. maxResults: 200 bounds draft keyword events to $0.30; it does not cap platform usage. Set Apify's maximum total charge separately. A low event allowance may limit delivered rows after source research; request caps remain the source-work boundary.

API and AI-agent use

After private deployment, start a run through Apify's API with this Actor's slug and a bearer token, then read the run's default dataset and both summary records:

curl --request POST \
  'https://api.apify.com/v2/acts/khadinakbar~keyword-fanout-longtail/runs' \
  --header "Authorization: Bearer $APIFY_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"seedKeywords":["standing desk"],"maxDepth":2,"maxRequests":20,"maxResults":50}'

Agent prompt: “Discover up to 50 long-tail autocomplete phrases for standing desks in US English using at most 20 requests and depth 2. Return observed parent paths, intent labels and collection times, and report any incomplete branches.”

The batch JSON interface is designed for API and hosted MCP use. Hosted MCP invocation and exposed schema remain unverified until private cloud acceptance. Limited permissions are sufficient for the Actor's own storage; no connected apps, owner-wide account access or runtime AI model is used.

Builder's note

Keeping discovery edges makes recursive expansion auditable: a content planner can see which actual query produced a phrase. Source-returned suggestions and mechanical heuristics remain separate throughout normalization, filtering and output. Prefer a focused seed and modest caps, then inspect the graph before widening the next run.

This is an independent research tool and is not affiliated with or endorsed by Google. Deployment and publication require review of source access, data use, pricing and final-build evidence.