> **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/credits](https://www.socialfetch.dev/docs/credits)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/credits.mdx](https://www.socialfetch.dev/docs/credits.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`).

---
# Credits (https://www.socialfetch.dev/docs/credits)

Some endpoints consume **credits** from your account balance. The API may return **`402`** when balance is insufficient.

<Callout type="idea" title="Check `meta.creditsCharged`">
  Each successful metered response includes how many credits were billed for that call — use it for client-side accounting and alerts.
</Callout>

How metering works [#how-metering-works]

* Metered routes charge credits when the **lookup attempt completes successfully*&#x2A;, as documented per endpoint. That can include cases where the social profile is private or not found — those outcomes are returned in the &#x2A;*`200`** response body (for example `data.lookupStatus` on TikTok profile lookup), not as HTTP errors.
* The `whoami` endpoint is intended for connectivity checks and **does not** charge credits.
* Use &#x2A;*`GET /v1/balance`** to read your current credit balance over the public API; it **does not** charge credits.
* Response metadata includes `creditsCharged` so you can confirm what was billed for that request.

Planning integrations [#planning-integrations]

* Preflight your balance before high-volume jobs (for example with &#x2A;*`GET /v1/balance`** or your own ledger checks).
* Treat &#x2A;*`402`** as a signal to top up or reduce concurrency.
* See the **API reference** for credit amounts and endpoint identifiers (for example TikTok profile lookup).

<Cards>
  <Card title="Errors" description="Full list of error codes including billing failures." href="/docs/errors" icon="<RefreshCw className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="API reference" description="Per-operation credit and pricing hints from the spec." href="/docs/api" icon="<Gauge className=&#x22;size-5 text-fd-primary&#x22; />" />

  <Card title="Errors" description="Outcome semantics live inside the Errors guide, including `not_found` and `private` in HTTP `200`." href="/docs/errors#outcome-semantics" icon="<Scale className=&#x22;size-5 text-fd-primary&#x22; />" />
</Cards>