Satellite - Hashtag Lookups (TikTok, Instagram & YouTube)

Hashtag lookups give you the same deep-dive treatment Satellite already gives creators and sounds — but applied to every video posted under a hashtag. You get the hashtag's page metadata, the full normalized video list, aggregated stats (views, engagement, velocity, top creators, related hashtags, top sounds, duration distribution), and — when trend_analysis=true — an LLM-derived trends block with mechanically-computed time_windows, resurged, and momentum per trend.

Start Hashtag Lookup

curl -G https://api.virlo.ai/v1/satellite/hashtags/tiktok/cleantok \
  -H "Authorization: Bearer {token}" \
  -d trend_analysis=true

{
  "data": {
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "processing"
  }
}

Poll Hashtag Status

curl https://api.virlo.ai/v1/satellite/hashtags/status/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

{
  "data": { "status": "processing" }
}

Stats block

Computed mechanically from the sampled videos. Not LLM-derived. Because ordering is applied to the collected corpus (see the sort param), stats are identical regardless of the requested sort.

Trends block

Only meaningful when trend_analysis=true. Identical shape to the sound lookup's trends block — the block is always present so polling code can branch on trends.analyzed without optional chaining.

Per-platform coverage

Each platform's hashtag surface exposes a different slice of data. Document-honest field gaps:

Durable runs (re-read for free)

Every completed hashtag lookup is persisted as a satellite_run row (type hashtag_lookup) owned by your team. You can re-read it for free, forever via:

• GET /v1/satellite/runs/:run_id — full result envelope, just like the status poll.
• GET /v1/satellite/runs?type=hashtag_lookup&platform=tiktok — paginated list of your hashtag runs (the type filter enum includes hashtag_lookup).
• GET /v1/satellite/runs/:run_id/videos?limit=50&offset=0 — paginated slice of the videos array (useful when the run has ~300 entries).

The run_id is included on every completed result envelope and never expires, unlike the 24-hour status cache. To refresh data, start a new lookup — that will cost credits again. This is the same "pay once, read forever" contract that applies to every Satellite endpoint.

See the Satellite overview for the run-read endpoints and the Webhooks reference for the satellite.lookup.completed event (with type: "hashtag_lookup" discriminator) that fires on completion or failure.

Error responses

Async workflow & timing

Status flow

processing → completed
           → failed

Timing expectations

Recommended polling interval: Every 10-15 seconds (every 30 seconds for trend_analysis runs).

Notes

• The start endpoint returns within 1–2 seconds. All fetching, normalization, stats computation, and LLM analysis happen in the background.
• The hashtag is normalized to lowercase before collection and dedup — #CleanTok, cleantok, and %23cleantok are the same lookup.
• Re-requesting the same platform + hashtag within 6 hours returns the cached run free (cached: true) — provided the stored run covers the request: same sort, trends already analyzed if you ask for trend_analysis=true, and a stored depth equal to or deeper than the one you request. A request the cache can't satisfy (different sort, a trend upgrade, or a deeper depth) re-scrapes immediately and bills normally.
• sort only changes the order of videos[] (top = views descending, recent = publish date descending). The platforms expose no server-side sort on hashtag feeds, so ordering is applied to the collected corpus; stats are order-independent.
• sample_quality.truncated_by_cap tells you the fetch hit its page cap; pages_fetched and note (insufficient_corpus → deep_corpus) tell you how much corpus backs the stats. Instagram corpora run shallower by design (upstream ~11-page depth cap).
• Trends are intentionally NOT branded as "rising/peaking/fading" — the honest framing is the explicit time_windows[] + resurged + momentum triple, which tells you when each pattern fired and whether it came back stronger.