CLI and agents

Use Social Fetch from a terminal or a coding agent: set SOCIALFETCH_API_KEY, call the API with curl and jq, run the socialfetch CLI, connect the MCP server and install the agent skill. No browser needed after you have a key.

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 (new accounts get free credits, no card needed), then:

export SOCIALFETCH_API_KEY=sfk_...

Every example here reads that variable. See Authentication for .env files and PowerShell.

2. Call the API with curl

Check the key (free):

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):

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:

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

Every endpoint's page in the API reference 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 webhook deliveries to a local URL while you develop:

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.

4. Connect an agent with MCP

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

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:

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:

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

Other clients are in 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:

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.

Machine-readable files

Agents can read these without a key:

FileWhat's in it
/llms.txtOrientation and links for LLMs
/agents.txtAgent onboarding and crawl rules
/llms-endpoints.txtEvery endpoint, with credits and doc links
/openapi.jsonThe OpenAPI document
/pricing.jsonCredit packs, plans, free credits and each endpoint's credit cost
/.well-known/apis.jsonAPIs.json catalogue

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

Limits on request rates are in Rate limits.

On this page