# Using an AI agent (/docs/quickstart/agents)

Paste one prompt into Claude, ChatGPT, Cursor, or any coding agent and let it set up SocialCrawl and make the first calls for you

You do not have to read the rest of the docs. Copy the prompt below into your agent, or install the MCP server, and the agent reads the free catalogue, verifies your key, and makes the first calls for you.

## Copy the prompt

```text
Set up the SocialCrawl API (https://www.socialcrawl.dev) in this project and make a first successful call.

Facts you can rely on:
- Base URL: https://www.socialcrawl.dev/v1
- Auth: send the header x-api-key: YOUR_API_KEY on every request. Never put the key in a URL or commit it.
- Every response is one JSON envelope: success, platform, endpoint, data, credits_used, credits_remaining, request_id, cached. List responses add pagination { next_cursor, has_more }.
- Most calls cost 1 credit. Cache hits cost 0. Failed calls and empty results are refunded. New accounts start with 100 credits.

Before writing any call, read the free catalogue instead of guessing paths or parameters (0 credits each):
  GET https://www.socialcrawl.dev/v1/utility/quickstart
  GET https://www.socialcrawl.dev/v1/utility/endpoints?search=<topic>
  GET https://www.socialcrawl.dev/v1/utility/endpoint?id=<platform/resource>

Then, in order:
1. Verify the key with GET https://www.socialcrawl.dev/v1/credits/balance and print the balance.
2. Call GET https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio and print data.author.followers and credits_used.
3. Change only the path to read the same handle on instagram/profile, youtube/channel, and twitter/profile. Print one line per platform.
4. Pick one list endpoint from the catalogue and page through it by sending pagination.next_cursor back as ?cursor= until has_more is false.

Branch on error.type, never on the message text. Only RATE_LIMITED, CONCURRENCY_LIMIT, UPSTREAM_ERROR, SERVICE_UNAVAILABLE, and INTERNAL_ERROR are worth a retry.

References (read these, do not summarise from memory):
https://www.socialcrawl.dev/docs/quickstart.md
https://www.socialcrawl.dev/llms.txt
```

The prompt tells the agent the three things it must not guess (the base URL, the header, the response shape), makes it read the free catalogue before it writes a call, and gives it four concrete tasks that end with the same handle read on four platforms. If you are signed in, your key is already in it.

## Or connect the agent directly

An MCP server and an Agent Skill give the agent the same catalogue as tools, so it never has to type a URL by hand.

```bash title="Terminal"
# Hosted server, nothing to install
claude mcp add --transport http socialcrawl https://mcp.socialcrawl.dev/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

# Or the local package
claude mcp add --scope user socialcrawl -e SOCIALCRAWL_API_KEY=YOUR_API_KEY -- npx -y socialcrawl-mcp
```

Add this to the client's MCP configuration. Cursor reads `.cursor/mcp.json`; Claude Desktop, VS Code, and Windsurf use the same shape.

```json title="mcp.json"
{
  "mcpServers": {
    "socialcrawl": {
      "command": "npx",
      "args": ["-y", "socialcrawl-mcp"],
      "env": { "SOCIALCRAWL_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

```bash title="Terminal"
npx skills add socialcrawl/skills
```

The skill teaches the agent the catalogue-first workflow and the response shape. It works in any agent that reads `SKILL.md` files.

Restart the agent after setup so it discovers the new tools. The full client list, with per-client screenshots, is in [Skills and MCP](/docs/skills-and-mcp.md).

## What the agent will do first

Every good agent run on SocialCrawl starts the same way, and you can ask for it by name:

1. `GET /v1/credits/balance` to prove the key works. Costs 0.
2. `GET /v1/utility/endpoints?search=<what you need>` to find the endpoint. Costs 0.
3. `GET /v1/utility/endpoint?id=<platform/resource>` for its parameters, cost, and paging rule. Costs 0.
4. One real call, then the same call on a second platform by changing one path segment.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \
  -H "x-api-key: YOUR_API_KEY"
```

## Give the agent the docs

Every page here is plain Markdown when you append `.md` to its URL, and the whole API is indexed in one file:

- [/llms.txt](/llms.txt): the short index.
- [/llms-full.txt](/llms-full.txt): every endpoint with parameters, costs, and errors.
- `/v1/utility/llms?platform=tiktok`: one platform's context as an API call.
- [/v1/openapi.json](/v1/openapi.json): the OpenAPI 3.1 spec.

## Prefer to do it yourself?

The [step-by-step quickstart](/docs/quickstart.md) walks through the same first calls by hand: your key, the runnable first call, the response shape, and a four-platform script.

}
    title="Get your API key"
    href="/auth/register?redirectTo=%2Fdocs%2Fquickstart%2Fagents"
    description="Free account, 100 credits, and the key is filled into the prompt above."
  />
}
    title="Skills and MCP"
    href="/docs/skills-and-mcp"
    description="Every supported client, with the exact configuration for each."
  />