> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). The sections below mirror the orientation block in [`/llms.txt`](https://www.socialfetch.dev/llms.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need a structured operation inventory. The catalog covers documented operations with on-site reference pages.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/quickstart](https://www.socialfetch.dev/docs/quickstart)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/quickstart.mdx](https://www.socialfetch.dev/docs/quickstart.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).

---
# Quickstart (https://www.socialfetch.dev/docs/quickstart)

<AgentPrompt />

<Callout type="info" title="Using TypeScript?">
  Use this page to verify your key and understand the raw HTTP API first, then move to the [**TypeScript SDK**](/docs/sdk) if you want typed methods and `Result` handling.
</Callout>

Before you start [#before-you-start]

* **Base URL:** `https://api.socialfetch.dev`
* **API key:** create one in [**API Keys**](https://app.socialfetch.dev/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 [#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.

<Tabs defaultValue="dotenv" className="not-prose my-4">
  <TabsList variant="line">
    <TabsTrigger value="dotenv">
      .env
    </TabsTrigger>

    <TabsTrigger value="bash">
      Bash / zsh
    </TabsTrigger>

    <TabsTrigger value="powershell">
      PowerShell
    </TabsTrigger>
  </TabsList>

  <TabsContent value="dotenv">
    ```dotenv
    SOCIALFETCH_API_KEY=sfk_...
    ```
  </TabsContent>

  <TabsContent value="bash">
    ```bash
    export SOCIALFETCH_API_KEY="sfk_..."
    ```
  </TabsContent>

  <TabsContent value="powershell">
    ```powershell
    $env:SOCIALFETCH_API_KEY = "sfk_..."
    ```
  </TabsContent>
</Tabs>

2\. Make your first request [#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.

<Callout type="warn" title="Metered request">
  This platform lookup can charge credits. If you want a zero-credit auth smoke test instead, use `GET /v1/whoami`. Read [Credits](/docs/credits) before running metered routes at scale.
</Callout>

<Tabs defaultValue="javascript" className="not-prose my-4">
  <TabsList variant="line">
    <TabsTrigger value="javascript">
      JavaScript
    </TabsTrigger>

    <TabsTrigger value="curl">
      cURL
    </TabsTrigger>

    <TabsTrigger value="python">
      Python
    </TabsTrigger>

    <TabsTrigger value="php">
      PHP
    </TabsTrigger>
  </TabsList>

  <TabsContent value="javascript">
    ```js
    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);
    ```
  </TabsContent>

  <TabsContent value="curl">
    ```bash
    curl -sS \
      -H "x-api-key: $SOCIALFETCH_API_KEY" \
      "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio"
    ```
  </TabsContent>

  <TabsContent value="python">
    ```python
    import os
    import requests

    response = requests.get(
        "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio",
        headers={"x-api-key": os.environ["SOCIALFETCH_API_KEY"]},
        timeout=30,
    )

    print(response.status_code)
    print(response.json())
    ```
  </TabsContent>

  <TabsContent value="php">
    ```php
    <?php

    $ch = curl_init("https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio");

    curl_setopt_array($ch, [
        CURLOPT_HTTPHEADER => [
            "x-api-key: " . getenv("SOCIALFETCH_API_KEY"),
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
    ]);

    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    curl_close($ch);

    echo $status . PHP_EOL;
    echo $body . PHP_EOL;
    ```
  </TabsContent>
</Tabs>

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 [#3-read-the-response]

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

```json
{
  "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 [#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](/docs/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](/docs/errors).

Where to go next [#where-to-go-next]

<Cards>
  <Card title="API reference" description="Every documented endpoint, with params, schemas, and per-route behavior." href="/docs/api" icon="<Terminal className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="TypeScript SDK" description="Typed methods, `Result` handling, and `unwrap()` for TypeScript-first integrations." href="/docs/sdk" icon="<Package className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Errors" description="HTTP errors, outcome semantics, request IDs, and retry guidance." href="/docs/errors" icon="<AlertTriangle className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Credits" description="Which routes charge, how to interpret `creditsCharged`, and what `402` means." href="/docs/credits" icon="<WalletCards className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>