Search

POST /search is the fastest way to see what’s out there on a topic. In a few seconds it returns:

• content: ranked posts matching your query.
• narratives: the narratives those posts belong to.
• creators: who made the posts.

Every id in the response can be passed straight to the detail endpoints. For more than 300 posts or a full analysis, use an intelligence job.

Cost: 0.01 credits per post returned. An empty answer costs nothing. See Pricing & Credits.

Request

POST /search
{
  "query": "sneaker drops",
  "window": "7d",
  "limit": 20
}

curl -X POST "$API_BASE/search" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "query": "sneaker drops", "window": "7d", "limit": 20 }'

Response

{
  "query": "sneaker drops",
  "window": "7d",
  "content": [
    { "uuid": "…", "platform": "TIKTOK", "title": "…", "relevance": 0.83, "narrativeIds": ["4182"], "patternKeys": ["pat_…"] }
  ],
  "narratives": [
    { "id": "4182", "label": "Limited sneaker drop hype", "source": "tracked", "content_count": 1240, "memberOverlap": 6 }
  ],
  "patterns": [],
  "creators": [ { "creatorId": 1234, "platform": "TIKTOK", "hits": 3, "followerCount": 120000 } ],
  "usage": { "credits": 0.2 }
}

• content: ranked posts (see The Content Object). Each one links to its narratives (narrativeIds → GET /narratives/{id}) and visual patterns (patternKeys → GET /intelligence/patterns/{patternKey}).
• narratives: up to 10, only when the evidence supports them. source tells you which kind:
  • tracked: a narrative on the precomputed map. Its id works with GET /narratives/{id}. content_count is its total size in the corpus; memberOverlap is how many of your results belong to it.
  • emergent: formed on the spot from your results. Its id only exists in this response.
• creators: who made the returned posts, sorted by hits (posts in your results), then followerCount. Handles are never exposed.
• usage.credits: what the call cost.

If narratives or creators find nothing in time, they come back empty and the rest of the answer is unaffected.

Retries

Send an Idempotency-Key header with a unique value per request. Retrying with the same key and body within 15 minutes isn’t charged again. Without the header, every call is billed.

Slow searches return 202

A search has about 20 seconds. If it runs over, you’re not charged for the search. Instead, the question is sent to an insights job (100 records), charged at that job’s price, and you get back a jobId:

{ "jobId": "01931f7e-…", "status": "queued", "statusUrl": "/intelligence/jobs/01931f7e-…", "estimated_cost": 1.5, "reason": "sync_budget_exceeded" }

Poll it like any job. A smaller limit or a shorter window makes this less likely.

Errors