Quickstart

Before you start

• Base URL: https://api.socialfetch.dev
• API key: create one in API Keys
• Auth header: send x-api-key on every request under /v1
• Security rule: keep the key server-side only; never ship it in browsers or mobile apps

1. Save your API key

If you are starting from JavaScript, put the key in an .env file first. The other tabs show equivalent shell-specific options.

SOCIALFETCH_API_KEY=sfk_...

2. Make your first request

Make one real profile request first. It verifies that your auth works and also shows the standard data + meta response envelope you will see across the API.

const response = await fetch(
  "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio",
  {
    headers: {
      "x-api-key": process.env.SOCIALFETCH_API_KEY,
    },
  }
);

const body = await response.json();

console.log(response.status, body);

If this request returns 401, your auth setup is not correct yet. If it returns 200, your key is working and you can start interpreting data.

3. Read the response

A successful response wraps the endpoint payload in a standard envelope:

{
  "data": {
    "lookupStatus": "found",
    "profile": { "...": "..." },
    "metrics": { "...": "..." }
  },
  "meta": {
    "requestId": "req_01example",
    "creditsCharged": 1,
    "version": "v1"
  }
}

Check these fields in order:

1. HTTP status
   • 200 means the request succeeded at the HTTP level.
   • Non-200 means read the { error } body instead.
2. meta.requestId
   • Log it on failures and include it in support requests.
3. meta.creditsCharged
   • On metered routes, this tells you exactly what was billed.
4. Route-specific outcome fields
   • For profile lookups, inspect fields like data.lookupStatus.
   • found, private, and not_found can all still arrive with HTTP 200.

The most important rule: do not treat every HTTP 200 as “usable data is present.” For many Social Fetch routes, business-level outcomes live inside data.

4. Handle common first-run failures

• 401 unauthorized: the key is missing, invalid, or not being sent correctly. Re-check your x-api-key header and environment variable wiring.
• 402 insufficient_credits: your auth is fine, but the account does not have enough credits for that route. See Credits.
• 503 temporarily_unavailable: the service or upstream source is temporarily unavailable. Retry with backoff rather than hammering the endpoint.
• HTTP 200 with lookupStatus: "not_found" or lookupStatus: "private": this is still a successful API response, just not a “found data” outcome.

For the full error envelope, retry guidance, and request ID semantics, read Errors.

Where to go next