Instagram Keyword Scout

Low-cost Apify Actor for finding public Instagram post/reel candidates from niche keywords, influencers, brands, UGC research, and optional alias testing.

This Actor is not a broad Instagram scraper replacement. It is a focused discovery tool: start with keywords only, inspect public candidate pages, resolve a controlled number of post/reel rows, and explain what worked, what was duplicated, and why a target was short. Add aliases later when you want better coverage or cleaner results.

Who It Is For

• K-pop, creator, model, cosplay, local trend, and niche keyword scouting
• brand and UGC candidate discovery before manual review or AI enrichment
• optional alias testing across names, romanized names, usernames, and hashtag variants
• small repeatable research batches where cost, duration, and shortages must be visible

Product Ladder

Preset	Goal	Internal settings
Scout 25	Cheap proof that keyword-only discovery works	target 5 per keyword, total cap 15 media rows
Scout 100	Standard validation batch	target 25 per keyword, total cap 100 media rows
Advanced 300	Slower, higher-cost research batch	target 50 per keyword, total cap 300 media rows, checkpoint on

Keep the customer promise modest: public candidate discovery with diagnostics. Do not promise full Instagram coverage, private data, login bypass, comments at scale, or complete metadata for every row.

Validated Smoke Run

The current Scout 25 alias-assisted flow was validated on Apify Cloud on 2026-07-06.

Run: zgSx3r5DrlXppu5jr
Build: 1.1.45
Dataset: ObazFo7lWpER7yKrf
Duration: 141.105s wall time
Cost: $0.01637
Run options: 2048 MB memory, 1800s timeout
Rows: 19 total, 3 search rows, 15 media rows, 1 runSummary row
Quality: 15/15 usable media rows, 0 failed rows, 0 target shortages
Top candidates: #aespakarina, #kimchaeyeon, #seoulfood

Use this as a smoke-test expectation, not a guarantee. Instagram public-page availability changes, keyword-only runs can be blocked, and some niches benefit from adding aliases after the first run.

Quick Start

npm install
npm run build
npm run dev

For a deployable release build:

$npm run build:release

Plain npm run build only compiles TypeScript. build:release updates package.json, package-lock.json, and .actor/actor.json together. Apify Actor source versions use MAJOR.MINOR, while npm package versions keep semver patch numbers.

Basic Apify Input

The Apify form has only three fields.

Keywords
karina
kim chaeyeon
seoul food

Result size
Scout 25 - cheapest first run

Aliases
Leave empty for the first run.

The Actor automatically tries exact, compact hashtag, underscore hashtag, profile guess, and Instagram keyword-search candidates. For example, kim chaeyeon can produce #kimchaeyeon, #kim_chaeyeon, @kimchaeyeon, and @kim_chaeyeon candidates.

Aliases are optional. Add them after the first run when a niche needs better coverage:

karina: aespakarina, karinaaespa, katarinabluu, yujimin
kim chaeyeon: kimchaeyeon, chaeyeon, tripleschaeyeon, kim chae yeon
seoul food: seoulfood, seoul cafe, korean food, seoul eats

The Store form intentionally hides crawler settings. Result size chooses the internal budget, concurrency, checkpoint, and discovery settings for you.

Mobile Run Flow

When running from a phone, keep the first pass small:

1. Paste 1-3 keywords into Keywords, one per line.
2. Keep Result size at Scout 25 - first low-cost check.
3. Leave Aliases empty, run once, then inspect the runSummary row.
4. Add aliases only for weak keywords or noisy candidates, then rerun.

The fastest mobile decision is the final runSummary: check total rows, usable media rows, failed rows, target shortages, and top candidates before opening the full JSON export.

{
  "keywords": "karina\nkim chaeyeon\nseoul food",
  "resultSize": "scout25",
  "keywordAliases": ""
}

For reusable starting points, see:

• examples/scout-25-input.json
• examples/with-aliases-input.json
• examples/scout-100-input.json
• examples/debug-aliases-input.json for internal troubleshooting
• docs/LAUNCH_CHECKLIST.ko.md
• docs/STORE_LISTING_DRAFT.md
• docs/CLEAN_DEPLOY.md

Interpreting Results

The Actor writes normalized records to the default Apify dataset:

• search: keyword discovery summary
• searchCandidate: individual candidate URL when outputSearchCandidates is enabled
• post or reel: resolved public media row
• profile: direct profile or fallback profile row
• runSummary: final counts, shortages, duplicate counts, and keyword quality
• failed: unsupported, blocked, or unresolved URL

Important diagnostics:

• collection.shortage and collection.shortageReason
• collection.zeroLinkCandidates
• collection.failedCandidates
• quality.loginWallDetected
• usability.usable
• keywordRelevance.score
• runSummary.searchQuality.successPatterns

Runs fail intentionally when a target-bearing keyword run produces zero usable media rows. Smaller target shortages stay as partial results. The dataset still includes search and runSummary rows so the operator can see whether the cause was NO_DISCOVERED_LINKS, login-wall blocking, filtering, or another shortage reason.

Operational Checks

After an Apify run, export the dataset as JSON or JSONL and summarize it locally:

$npm run summarize:dataset -- path\to\dataset-items.json

The summary reports row counts, usable media rate, shortage reasons, top scout candidates, and weak keywords. For machine-readable output:

$npm run summarize:dataset -- path\to\dataset-items.json --json

Before release:

npm run verify
npm run check
npm test
npm run build

The public Store input intentionally exposes only keywords, resultSize, and keywordAliases. The runtime still accepts advanced JSON fields for internal troubleshooting and backwards compatibility.

Recommended Apify default run options:

• memory: 2048 MB
• timeout: 1800 seconds

The last Scout 25 cloud validation peaked near 1 GB of memory, so 1024 MB is too close for stable Playwright runs. 2048 MB keeps roughly 2x headroom while avoiding the avoidable compute cost of 4096 MB. Keep 4096 MB as the maximum for manual recovery runs, not the default.

Advanced Batch Guidance

For 300+ item batches, use resultSize: "advanced300". The Actor turns checkpointing on by default for that preset. Treat these as advanced operations, not the default customer path.

{
  "keywords": "karina\nkim chaeyeon\nkian84\nbeauty\nfood\nfashion\nseoul\nkpop\ncafe\nhotel",
  "resultSize": "advanced300",
  "keywordAliases": ""
}

Architecture

src/main.ts
  -> reads Actor input
  -> coordinates keyword discovery, direct targets, checkpointing, and runSummary

src/router.ts
  -> routes profile, post, reel, and generic page requests
  -> writes normalized records to the default dataset

src/extractors/
  -> page extraction only

src/resolvers/
  -> merges meta, embedded payload, visible signals, search discovery, and relevance

src/state/
  -> budget, dedupe, and checkpoint helpers

src/local/
  -> local web UI for manual URL testing

Cost Strategy

The first version uses Apify Dataset and KeyValueStore only. Add external databases, queues, paid proxies, or AI enrichment only after there is evidence that the Actor needs them.

Deferred until demand is proven:

• automatic login/session operation
• private content access
• deep comment collection
• media file downloads
• AI enrichment
• external databases or queues

Compliance Notes

Use this Actor only for collection that is permitted by applicable law, platform terms, and account permissions. Keep rate limits conservative and avoid collecting private or sensitive personal information unless you have a lawful basis and explicit permission.