POST/search

Search people and posts

Search one network from a natural-language query. Cache-first by default; set fresh to call a live provider. Returns up to 100 normalized results with an exact usage receipt.

Request body

platformstringrequired

One of instagram, youtube, tiktok, x, linkedin, or reddit.

querystringrequired

A plain-language description of the people, niche, topic, or public conversation to find.

limitinteger · default 10

Number of results, 1–100.

freshboolean · default false

false reads the Stormy cache at $0.01/result. true calls a live provider at $0.08/result.

min_followersinteger | null

Only people at or above this audience size. Stormy also reads a size stated in the query text, but this is exact.

max_followersinteger | null

Only people at or below this audience size — the way to ask for creators around your own size rather than the biggest accounts in the niche.

Example request

# This call costs $0.10 — 10 results x $0.01 cached. It takes 45-90 seconds.
# Swap to "limit": 25, "fresh": true and the same call costs $2.00.
export STORMY_API_KEY=stm_live_...

curl -X POST 'https://stormy.ai/api/v1/search' \
  -H "Authorization: Bearer $STORMY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: ohio-roofers-2026-07' \
  -d '{
    "platform": "youtube",
    "query": "roofing creators in Ohio",
    "limit": 10,
    "fresh": false
  }'

Response

200 OK · application/json

{
  "ok": true,
  "platform": "youtube",
  "query": "roofing creators in Ohio",
  "fresh": true,
  "results": [
    {
      "channel_id": "UC_example",
      "handle": "@buildwithalex",
      "name": "Build With Alex",
      "url": "https://youtube.com/@buildwithalex",
      "subscribers": 184000,
      "description": "Roofing, restoration, and jobsite systems.",
      "videos_count": 412,
      "total_views": 28940000,
      "country": "US"
    }
  ],
  "usage": {
    "operation": "fresh_discovery",
    "metered_results": 25,
    "billed_results": 25,
    "cost_usd": "2.00",
    "credits": 200,
    "remaining_usage_usd": "23.00"
  }
}

Every response includes a usage receipt: operation · metered_results · billed_results · cost_usd · credits · remaining_usage_usd. Reusing an Idempotency-Key returns the existing receipt instead of charging twice.