Multi-platform search

Send one query to GET /v1/search/multi and it runs on each platform's own search endpoint at once. Every row is the row that platform's search endpoint returns, with platform added, and each platform costs its own page price, charged only when it came back with rows.

curl "https://www.socialcrawl.dev/v1/search/multi?query=matcha+latte&platforms=tiktok,instagram,youtube" \
  -H "x-api-key: YOUR_API_KEY"

This call searched three platforms. Their rows arrive together in data.items, grouped by platform in the order you listed them, and a post URL that already appeared is left out. data.sources reports what each platform returned and cost, and gives you its cursor for the next page.

Which platforms

platforms is a comma-separated list. Without it the call searches TikTok, Instagram, YouTube, Reddit and Threads.

A name outside this list is a 400 INVALID_REQUEST that names the accepted values and costs nothing.

Request parameters

since is sent to the platform as its own date filter where one exists (Threads and Facebook start_date, the X since: search operator), and is applied to each row's post.published_at on every platform.

Per-platform filters

Put the platform in front of the filter name, for example tiktok.region=US or reddit.sort=new. Each one is sent to that platform's endpoint exactly as that endpoint takes it, and a filter for a platform you did not request is not used. A value outside a filter's list is a free 400.

What you get back

{
  "success": true,
  "platform": "search",
  "endpoint": "/v1/search/multi",
  "data": {
    "query": "matcha latte",
    "platforms": ["tiktok", "instagram", "youtube"],
    "since": null,
    "sources": {
      "tiktok": {
        "endpoint": "/v1/tiktok/search",
        "status": "ok",
        "http_status": 200,
        "rows": 20,
        "rows_kept": 20,
        "credits": 1,
        "next_cursor": "sc.eyJ2IjoyLCJjIjoiMjAifQ",
        "has_more": true
      },
      "instagram": {
        "endpoint": "/v1/instagram/search/reels",
        "status": "empty",
        "http_status": 200,
        "rows": 0,
        "rows_kept": 0,
        "credits": 0,
        "next_cursor": null,
        "has_more": false
      },
      "youtube": {
        "endpoint": "/v1/youtube/search",
        "status": "ok",
        "http_status": 200,
        "rows": 19,
        "rows_kept": 18,
        "credits": 1,
        "next_cursor": "sc.eyJ2IjoyLCJjIjoiRWdJUUFR…",
        "has_more": true
      }
    },
    "methodology_version": "search-multi/1.0",
    "search_status": "complete",
    "items": [
      { "platform": "tiktok", "post": { "id": "…", "url": "…" }, "computed": { } }
    ],
    "total": 38,
    "duplicates_removed": 1,
    "credits_charged": 2
  },
  "credits_used": 2,
  "credits_remaining": 4998,
  "request_id": "req-XXXXX",
  "cached": false
}

A platform whose search found nothing reports empty, not failed, and costs nothing.

How do I get the next page?

This endpoint returns one page per platform and does not page itself, so sending it cursor is a 400. To go deeper on one platform, call that platform's own endpoint (sources.<platform>.endpoint) with the same query and send sources.<platform>.next_cursor as cursor:

curl "https://www.socialcrawl.dev/v1/tiktok/search?query=matcha+latte&cursor=sc.eyJ2IjoyLCJjIjoiMjAifQ" \
  -H "x-api-key: YOUR_API_KEY"

From there the walk is the ordinary one described in Pagination.

Billing

Metered, 1-12 credits. Each platform costs its own endpoint's page price, and only when its page came back with rows. The call holds the sum of the requested platforms' prices up front and refunds every platform that failed or found nothing. The default five platforms hold 5 credits.

Relevance and labels

Rows carry the same judged fields as the single search endpoints, and they are judged across all platforms at once, so a TikTok row and a Reddit row can be compared on one scale. Every row carries computed.relevance against your query and the default labels at no extra credit. relevance=score, relevance=filter, relevant_to= and label= work as they do on the single search endpoints, and their extras are priced the same way. See Labels for the field shapes and prices.

Multi or everywhere?

search/multi returns each platform's native rows at native prices, with no planning and no reranking. Use it when you would otherwise call three or four search endpoints yourself. Universal social search is a different product at a flat 20 credits: it plans your query, searches more sources, reads top comments, and ranks and clusters the merged results into one answer.

Next steps