> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration.

## This page

- **On-site (HTML):** <https://www.socialfetch.dev/docs/cli-and-agents>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/docs/cli-and-agents.mdx>

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` 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>

## 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()`.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages.
- [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples.
- [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths.
- [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 1112 endpoint tools, plus docs_search/docs_read for implementation help.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples.
- [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start.
- [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog.
- [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI).
- [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls).
- [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist.
- [`/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.
- [Authentication](https://www.socialfetch.dev/docs/authentication.mdx) — `x-api-key` header, the `SOCIALFETCH_API_KEY` environment variable, and a curl check.
- [Rate limits](https://www.socialfetch.dev/docs/rate-limits.mdx) — no per-minute cap on paid lookups with a key, 200 in flight per workspace, per-minute limits on free and keyless routes, `429`/`503` and `Retry-After`.
- [CLI and agents](https://www.socialfetch.dev/docs/cli-and-agents.mdx) — curl and jq, the `socialfetch` CLI, MCP and the agent skill from a terminal.
- [`/pricing.json`](https://www.socialfetch.dev/pricing.json) — machine-readable pricing: credit packs, plans, free credits and each endpoint's credit cost.
- 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`).
- Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`).

---
# CLI and agents (https://www.socialfetch.dev/docs/cli-and-agents)

Social Fetch works headless. Once you have an API key, everything below runs from a terminal, a CI job or a coding agent such as Claude Code, Codex or Cursor. Responses are JSON.

## 1. Set your key

Create a key at [app.socialfetch.dev/api-keys](https://app.socialfetch.dev/api-keys) (new accounts get free credits, no card needed), then:

```bash
export SOCIALFETCH_API_KEY=sfk_...
```

Every example here reads that variable. See [Authentication](/docs/authentication) for `.env` files and PowerShell.

## 2. Call the API with curl

Check the key (free):

```bash
curl -sS -H "x-api-key: $SOCIALFETCH_API_KEY" \
  "https://api.socialfetch.dev/v1/whoami"
```

Look up a profile and pull one field out with `jq` (1 credit):

```bash
curl -sS -H "x-api-key: $SOCIALFETCH_API_KEY" \
  "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio" \
  | jq '.data.metrics.followers'
```

Read the cost of the last request from `meta.creditsCharged`, and your balance for free:

```bash
curl -sS -H "x-api-key: $SOCIALFETCH_API_KEY" \
  "https://api.socialfetch.dev/v1/balance"
```

Every endpoint's page in the [API reference](/docs/api) has a curl example. Paginate list routes by sending `data.page.nextCursor` back as the `cursor` query parameter until `data.page.hasMore` is `false`.

## 3. The `socialfetch` CLI

`@socialfetch/sdk` ships a `socialfetch` command. Today it has one command, `listen`, which forwards [monitor](/docs/monitors) webhook deliveries to a local URL while you develop:

```bash
npm install @socialfetch/sdk
npx socialfetch listen --forward-to http://localhost:3000/api/webhooks/socialfetch
```

It reads `SOCIALFETCH_API_KEY`, or `--api-key <key>`. Run `npx socialfetch --help` for every option, and see [Testing webhooks locally](/docs/monitors/testing-locally).

## 4. Connect an agent with MCP

The hosted MCP server at `https://api.socialfetch.dev/mcp` exposes the endpoints as tools. In Claude Code:

```bash
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp
```

That signs in with OAuth in your browser. For a headless machine, send the key instead:

```bash
claude mcp add --transport http socialfetch https://api.socialfetch.dev/mcp --header "x-api-key: $SOCIALFETCH_API_KEY"
```

Apps that only run local (stdio) servers can bridge with:

```bash
npx mcp-remote https://api.socialfetch.dev/mcp
```

Other clients are in [MCP](/docs/integrations/mcp).

## 5. Give your agent the skill

The agent skill tells a coding agent how to call Social Fetch well. Download it into the folder your agent reads:

```bash
mkdir -p .agents/skills/socialfetch
curl -fsSL https://www.socialfetch.dev/skill.md -o .agents/skills/socialfetch/SKILL.md
```

For Claude Code, use `.claude/skills/socialfetch`. See [Agent Skills](/docs/integrations/skills).

## Machine-readable files

Agents can read these without a key:

| File                                                                          | What's in it                                                      |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [`/llms.txt`](https://www.socialfetch.dev/llms.txt)                           | Orientation and links for LLMs                                    |
| [`/agents.txt`](https://www.socialfetch.dev/agents.txt)                       | Agent onboarding and crawl rules                                  |
| [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt)       | Every endpoint, with credits and doc links                        |
| [`/openapi.json`](https://www.socialfetch.dev/openapi.json)                   | The OpenAPI document                                              |
| [`/pricing.json`](https://www.socialfetch.dev/pricing.json)                   | Credit packs, plans, free credits and each endpoint's credit cost |
| [`/.well-known/apis.json`](https://www.socialfetch.dev/.well-known/apis.json) | APIs.json catalogue                                               |

Every docs page also has a markdown copy: add `.mdx` to its URL.

Limits on request rates are in [Rate limits](/docs/rate-limits).