Quickstart

This guide takes you from an API key to a working request and shows you how to read the response. The examples below match the API reference language tabs — cURL, Node.js, TypeScript SDK, Python, Go, and Java — all reading your key from the environment variable you set in step 1.

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

Keep the key in an environment variable rather than hardcoding it. Use .env for app code, or export it in your shell for one-off requests.

2. Make your first request

Start with a single profile lookup. It confirms your auth works and returns the standard data + meta envelope you'll see on every endpoint.

A 200 means your key works and you can move on to reading data. A 401 means auth isn't wired up yet — re-check the header and environment variable in step 1.

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 transport level. Anything else: read the { error } body instead.
2. meta.requestId — log it on failures and quote it in support requests.
3. meta.creditsCharged — on metered routes, exactly what this call billed.
4. Outcome fields in data — for profile lookups, check data.lookupStatus. found, private, and not_found all arrive with HTTP 200.

The one rule worth remembering: 200 doesn't always mean "data is present." Many routes report the real outcome inside data, so check it before using the payload.

4. Handle common first-run failures

• 401 unauthorized — the key is missing, invalid, or sent incorrectly. Re-check your x-api-key header and environment variable.
• 402 insufficient_credits — auth is fine, but the account is out of credits for that route. See Credits.
• 503 temporarily_unavailable — the service is briefly unavailable. Retry with backoff instead of hammering it.
• 200 with lookupStatus: "not_found" or "private" — a successful response, just not a "found" outcome. Handle it as data, not as an error.

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

Where to go next