Authentication

Every request to the SocialCrawl API requires an API key passed via the x-api-key header. There is no OAuth flow, no token exchange, and no session — the key is the entire credential.

Getting Your API Key

1. Sign up at socialcrawl.dev — you get 100 welcome credits instantly
2. Navigate to Dashboard → API Keys
3. Click Create Key and give it a descriptive name (e.g. production, staging, local-dev)
4. Copy the key from the one-time reveal dialog — this is the only time the full key is shown

Keys have the format sc_ followed by 32 random bytes (base64url-encoded), so every key is 46 characters long. Only the last 4 characters are displayed in the dashboard after creation.

Using Your Key

Include the x-api-key header with every request:

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

const response = await fetch(
  "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
  { headers: { "x-api-key": "sc_your_api_key_here" } },
);

import requests

response = requests.get(
    "https://www.socialcrawl.dev/v1/tiktok/profile",
    params={"handle": "charlidamelio"},
    headers={"x-api-key": "sc_your_api_key_here"},
)

Missing or malformed keys return 401 MISSING_API_KEY / 401 INVALID_API_KEY. See Error Handling for the full list.

Key Management

Revoke compromised keys from Dashboard → API Keys as soon as possible — a revoked key is rejected on the very next request.

Per-key credit limits

Every key on your account draws on the same credit balance. That is usually what you want — until a test script loops, a CI job misfires, or a new integration is pointed at the wrong endpoint, and the balance your production traffic depends on is gone.

A credit limit caps how many credits one key may ever spend. Set one on a key, and that key stops at the cap while every other key on the account keeps working normally.

Set it in Dashboard → API Keys. When you create a key, tick Set a credit limit for this key and enter a number; leave the box unticked for no limit, which is the default and what a production key normally wants. You can add, change, or remove a limit on an existing key at any time from its ⋯ menu.

Production key   no limit          ← your real traffic, unaffected
Test key         500 credit limit  ← stops at 500, whatever it does

Once a capped key reaches its limit, its requests return 402 KEY_BUDGET_EXCEEDED and nothing is deducted. Your account balance is untouched, so the rest of your integration keeps running.

A few details worth knowing:

• The counter is cumulative, not monthly. It does not reset on its own. When a capped key runs out, raise its limit or hit Reset usage to give it the full allowance again.
• It tracks net spend. Credits refunded for an upstream failure are also given back to the key's counter, so a run of 404s or 502s never quietly eats a test key's budget.
• Free calls are free. Cache hits and zero-cost endpoints do not count against the limit, exactly as they do not count against your balance.
• Lowering a limit below what a key has already spent is allowed, and immediately blocks that key. It is the fastest way to stop a key that is misbehaving right now without revoking it and breaking whatever is holding it.
• The limit applies to the key, not the account. It is a blast-radius control, not a billing plan — it never changes what you are charged, only which key is allowed to do the charging.

Changes take effect on the key's very next request; there is no cache to wait out.

Security Recommendations

• Never embed keys in client-side code. Every request using your key is billed to your account. Use a server proxy when calling from browsers or mobile apps.
• Use separate keys per environment. Revoking a staging key shouldn't take down production.
• Put a credit limit on non-production keys. A test or CI key with a cap cannot drain the balance your production traffic runs on, however badly it misbehaves.
• Store keys in a secret manager (Vercel Encrypted Env, AWS Secrets Manager, 1Password, etc.) — not in git.
• Set an expires_at on any key you issue to a contractor or short-lived job.

Related

• Credits — how billing works
• Response Schema — what comes back
• Error Handling — what to do when things break