Quickstart

Make your first SocialCrawl API request in under a minute. New accounts get 100 welcome credits — enough to try every standard endpoint without adding a payment method.

1. Get Your API Key

Sign up at socialcrawl.dev and create a key in Dashboard → API Keys. Keys have the format sc_ + 32 random bytes (46 characters total) and are shown in full exactly once on creation — copy it somewhere safe.

2. Make a Request

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

3. Read the Response

Every response follows the same envelope format:

{
  "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
    },
    "_warnings": [
      "computed.engagement_rate: author ratio exceeded 1.0 (raw: 72.258065); returned null — a lifetime likes/followers ratio is not a real engagement rate"
    ]
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-abc123",
  "cached": false
}

Note the computed block. Every field in it is either a real number or an honest null — we never substitute a plausible-looking figure for one we cannot derive. On a profile response, estimated_reach is always null (a follower count carries no reach signal), and engagement_rate is null on the platforms that report cumulative lifetime likes, because dividing those by current followers is not an engagement rate. language and content_category need a bio with enough text to classify. Read Computed fields before you branch on any of them, and check data._warnings when a value is missing.

Responses also include useful headers: X-Request-Id, X-Credits-Used, X-Credits-Remaining, and X-Cache (HIT when served from cache — cache hits cost 0 credits).

4. Retry Safely (Optional)

Add an Idempotency-Key header to make any request safe to retry. Replays return the original response and deduct 0 new credits. For transient failures (429, 500, 502, 503), see Handling retries for copy-paste backoff loops in cURL, Python, and Node.

curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

What should I build next?

• Authentication — manage keys, rotate them, protect them
• Response Schema — the unified envelope, headers, and _warnings
• Pagination — one rule for every list endpoint: send next_cursor back as cursor, stop when has_more is false
• Credits — tiers, refunds, free cache hits, balance endpoint
• Which Endpoint Should I Use? covers the endpoint pairs developers most often confuse
• Error Handling — every error code and when to retry
• API Reference — try any of the 400 endpoints live

Building an AI agent? See AI Agent Integration and Skills & MCP.