Quickstart

Get your API key

New accounts get 100 credits on signup and no card is needed. If you are already signed in, your key appears below and is filled into every sample on this page.

Keys start with sc_. Keep the key on the server side and never in a browser or a public repo. You can rename, cap, rotate, or revoke it any time in Authentication.

Make your first call

Pick a language, then copy the sample or press Run to see the real response here. Signed out, Run uses a shared demo key with a small daily allowance. Signed in, it uses your key and your credits.

curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \  -H "x-api-key: YOUR_API_KEY"

There is no token exchange and no per-platform setup. The x-api-key header is the whole credential.

Read the response

Every response has the same top level, which means one parser works for every platform. The platform payload is always under data.

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "author": {
      "username": "charlidamelio",
      "followers": 155000000,
      "following": 1200,
      "likes_count": 11200000000
    },
    "computed": {
      "engagement_rate": null,
      "language": null,
      "content_category": null,
      "estimated_reach": null
    }
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-abc123",
  "cached": false
}

credits_used is the net charge for this request and credits_remaining is your balance after it. A null in computed means a real number could not be derived, and SocialCrawl never substitutes a plausible-looking one. See Computed fields before you branch on any of them.

The same numbers arrive as headers, which is handy in a log line:

Make your first 100 calls

Switching platform is a one-line change, so a loop over platforms is the natural second script. This one reads the same handle on four platforms and prints the follower count and the running cost. It spends about 4 credits.

import os
import requests

KEY = os.environ["SOCIALCRAWL_API_KEY"]
BASE = "https://www.socialcrawl.dev/v1"

calls = [
    ("tiktok/profile", "nasa"),
    ("instagram/profile", "nasa"),
    ("youtube/channel", "nasa"),
    ("twitter/profile", "nasa"),
]

for path, handle in calls:
    res = requests.get(
        f"{BASE}/{path}",
        params={"handle": handle},
        headers={"x-api-key": KEY},
    ).json()
    if not res["success"]:
        print(path, res["error"]["type"], res["error"]["message"])
        continue
    author = res["data"]["author"]
    print(
        f"{path:<20} {author['followers']:>14,} followers"
        f"  cost {res['credits_used']}  left {res['credits_remaining']}"
    )

const KEY = process.env.SOCIALCRAWL_API_KEY!;
const BASE = "https://www.socialcrawl.dev/v1";

const calls = [
  ["tiktok/profile", "nasa"],
  ["instagram/profile", "nasa"],
  ["youtube/channel", "nasa"],
  ["twitter/profile", "nasa"],
] as const;

for (const [path, handle] of calls) {
  const res = await fetch(`${BASE}/${path}?handle=${handle}`, {
    headers: { "x-api-key": KEY },
  });
  const json = await res.json();
  if (!json.success) {
    console.log(path, json.error.type, json.error.message);
    continue;
  }
  const { followers } = json.data.author;
  console.log(
    `${path.padEnd(20)} ${followers.toLocaleString().padStart(14)} followers` +
      `  cost ${json.credits_used}  left ${json.credits_remaining}`,
  );
}

for path in tiktok/profile instagram/profile youtube/channel twitter/profile; do
  curl -s "https://www.socialcrawl.dev/v1/$path?handle=nasa" \
    -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  | python3 -c "import sys, json; r = json.load(sys.stdin); print('$path', r['data']['author']['followers'], 'cost', r['credits_used'])"
done

Want one call instead of a loop? Universal search fans one query out across 14 platforms and merges the results into one list, for 20 credits.

curl "https://www.socialcrawl.dev/v1/search/everywhere?query=artemis%20launch" \
  -H "x-api-key: YOUR_API_KEY"

It waits for every platform to answer, so allow up to 60 seconds and read it with a client timeout to match. See Universal search for streaming the results as they land.

Find any endpoint without leaving your terminal

The catalogue is free. Every /v1/utility/* call and the balance call cost 0 credits, answer in about 150 ms, and are generated from the endpoint registry at request time.

# Search every endpoint by keyword
curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \
  -H "x-api-key: YOUR_API_KEY"

# The full guide for one endpoint: parameters, cost, paging, an example call
curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=tiktok/post/comments" \
  -H "x-api-key: YOUR_API_KEY"

# Your balance
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: YOUR_API_KEY"

If an AI agent writes your code, give it the same three calls. The MCP server and Agent Skill already do this before every request.