Utility

The utility platform is the API describing itself. Five endpoints answer "what can I call", "how do I call this one", "how do I make my first request", "give my agent everything it needs to know", and "which calls does this job need". All five are free, cost 0 credits, and never consume credits.

Base URL: /v1/utility/...

What is in here, and when you need it

Quickstart

curl "https://www.socialcrawl.dev/v1/utility/quickstart?platform=tiktok" \
  -H "x-api-key: YOUR_API_KEY"

# Everything callable, filterable by platform, keyword, or method
curl "https://www.socialcrawl.dev/v1/utility/endpoints?platform=tiktok&search=comment" \
  -H "x-api-key: YOUR_API_KEY"

# How to call one of them, by id or by path
curl "https://www.socialcrawl.dev/v1/utility/endpoint?url=/v1/tiktok/profile" \
  -H "x-api-key: YOUR_API_KEY"

Discover the surface

endpoint takes either id (tiktok/profile) or url (/v1/tiktok/profile), and one of them is required. Pass method to disambiguate a resource registered under more than one HTTP method: /v1/web/monitors/{monitor_id} is GET, PATCH and DELETE. Omit it and the first registered method wins.

On endpoints, search is a keyword search over endpoint paths, summaries, parameter names and descriptions, and tags, so search=sentiment finds the comment endpoints that take label=sentiment. Every word has to match somewhere, and results whose path or summary contains the whole search come first. Results come back in keyword order, and data.ranking says keyword.

The guide from endpoint also lists params.featured: up to three parameters worth sending, each with a one-line reason, and the example request already sends them (they never raise the price). Its related list names the endpoints that do more of the same job, each with why: the Prism composite that does it in one call, the batch variant, or the same data on another platform.

Which endpoints support a parameter

The index lists the label= presets separately for comments, posts and reviews (free_values run on every page at no extra credits, metered_values cost a credit per started 25 rows judged), relevance=, judgments=, include=, since= and stop_at_id=, recent_days=, the row filters, seen=, trim=, download_media=, market= and fit=. Pass param=relevance for one entry; an unknown name is a 404 that lists the valid ones.

curl "https://www.socialcrawl.dev/v1/utility/capabilities?param=label" \
  -H "x-api-key: YOUR_API_KEY"

How often is each field filled?

endpoint also returns a quality block: the share of rows that carried a value for each response field over the last 7 days, measured with production calls that bypass the cache. Use it to see which fields you can rely on before you build on one.

curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=instagram/search/hashtag" \
  -H "x-api-key: YOUR_API_KEY"

This quality block is shortened to a few fields:

{
  "quality": {
    "measured": true,
    "window_days": 7,
    "measured_from": "2026-09-23",
    "measured_to": "2026-09-23",
    "sampled_calls": 1,
    "fill_rate": {
      "post.engagement.comments": 1,
      "post.engagement.likes": 0.79,
      "post.content.duration_seconds": 0.71
    },
    "null_by_design": [
      {
        "leaf": "post.engagement.views",
        "reason": "A hashtag feed mixes photos and reels, and a photo has no play count",
        "when": "photo rows"
      }
    ],
    "by_rung": [],
    "freshness_hours": 3.4,
    "method": "Production calls made with the endpoint's example inputs, bypassing the cache; ..."
  }
}

An endpoint with no sample in the last 7 days returns "measured": false with a reason and its null_by_design list, never a stale rate.

Bootstrap an agent

An agent holding nothing but a key can learn the surface in one call rather than scraping documentation pages. format defaults to markdown. platform narrows the corpus to one platform when the full context is more than the agent needs.

curl "https://www.socialcrawl.dev/v1/utility/llms?platform=youtube&format=json" \
  -H "x-api-key: YOUR_API_KEY"

Plan the calls for a job

Write the job in plain words in query, in any language. The planner covers four jobs today: monitoring a brand, one creator's profile and posts, a topic search, and a saved search on a monitor. A question that one endpoint answers returns that one call. Nothing is run, and the plan itself costs 0 credits.

curl -G "https://www.socialcrawl.dev/v1/utility/plan" \
  --data-urlencode "query=Combine @nike's TikTok profile with their recent videos and the comments on them" \
  -H "x-api-key: YOUR_API_KEY"

The response carries kind: "call_plan" and a steps list. This one is shortened to the fields you act on:

{
  "success": true,
  "data": {
    "kind": "call_plan",
    "recipe": "creator_profile",
    "uncertain": false,
    "steps": [
      {
        "id": "tiktok_profile",
        "method": "GET",
        "path": "/v1/tiktok/profile",
        "params": { "handle": "nike" },
        "missing": [],
        "credits": 1,
        "run": "ready"
      },
      {
        "id": "tiktok_posts",
        "method": "GET",
        "path": "/v1/tiktok/profile/videos",
        "params": { "handle": "nike" },
        "missing": [],
        "credits": 1,
        "run": "after_approval"
      },
      {
        "id": "tiktok_comments",
        "method": "GET",
        "path": "/v1/tiktok/post/comments",
        "params": {},
        "missing": ["url"],
        "binds": { "url": "tiktok_posts.items[].post.url" },
        "credits": 1,
        "run": "blocked"
      }
    ],
    "ask": [],
    "cannot": []
  },
  "credits_used": 0
}

A job that should repeat (for example "every day") adds a POST /v1/monitors row, described in Webhooks. A question with a date window adds a note to each step: the parameter that sets the window, or where to stop paging when the endpoint has no such parameter. Sending query empty or leaving it out is a 400.

All endpoints

12 endpoints available.

Platform notes

• All five endpoints are free. They cost 0 credits and never consume credits, so polling them is safe.
• endpoint requires id or url. Sending neither is a 400.
• plan requires query. A plan lists calls and runs none of them; each call it lists is billed at its own price when you make it.
• All endpoints use GET with query parameters, authenticate with the x-api-key header, and return the unified SocialCrawl envelope.

Next steps