# Quickstart (/docs/quickstart)

Get a key, make your first call, then make your first 100 calls across several platforms in one short script

Five short steps. The first call takes under a minute. By the end you will have read several platforms from one script and know how to find any endpoint without leaving your terminal.

## Start with an AI agent

Using Claude, ChatGPT, Cursor, or another coding agent? Paste this prompt and it does the five steps for you. The [Using an AI agent](/docs/quickstart/agents.md) page has the MCP server and Agent Skill as well.

```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
```

## Or do it by hand

### Get your API key

New accounts get 100 credits on signup and no card is needed. If you are already signed in, your key appears below and is filled into every sample on this page.

Get a free API key at https://www.socialcrawl.dev/dashboard/api. New accounts start with 100 welcome credits and no card is needed.

Keys start with `sc_`. Keep the key on the server side and never in a browser or a public repo. You can rename, cap, rotate, or revoke it any time in [Authentication](/docs/authentication.md).

### Make your first call

Pick a language, then copy the sample or press **Run** to see the real response here. Signed out, Run uses a shared demo key with a small daily allowance. Signed in, it uses your key and your credits.

```bash
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"
```

There is no token exchange and no per-platform setup. The `x-api-key` header is the whole credential.

### Read the response

Every response has the same top level, which means one parser works for every platform. The platform payload is always under `data`.

```json title="Response"
{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "author": {
      "username": "charlidamelio",
      "followers": 155000000,
      "following": 1200,
      "likes_count": 11200000000
    },
    "computed": {
      "engagement_rate": null,
      "language": null,
      "content_category": null,
      "estimated_reach": null
    }
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-abc123",
  "cached": false
}
```

`credits_used` is the net charge for this request and `credits_remaining` is your balance after it. A `null` in `computed` means a real number could not be derived, and SocialCrawl never substitutes a plausible-looking one. See [Computed fields](/docs/computed-fields.md) before you branch on any of them.

The same numbers arrive as headers, which is handy in a log line:

| Header                | What it carries                                          |
| --------------------- | -------------------------------------------------------- |
| `X-Request-Id`        | Matches `request_id`. Quote it when contacting support.  |
| `X-Credits-Used`      | Net credits charged for this request.                    |
| `X-Credits-Remaining` | Your balance after the request.                          |
| `X-Cache`             | `HIT` when served from cache. Cache hits cost 0 credits. |

### Make your first 100 calls

Switching platform is a one-line change, so a loop over platforms is the natural second script. This one reads the same handle on four platforms and prints the follower count and the running cost. It spends about 4 credits.

```python title="Python"
import os
import requests

KEY = os.environ["SOCIALCRAWL_API_KEY"]
BASE = "https://www.socialcrawl.dev/v1"

calls = [
    ("tiktok/profile", "nasa"),
    ("instagram/profile", "nasa"),
    ("youtube/channel", "nasa"),
    ("twitter/profile", "nasa"),
]

for path, handle in calls:
    res = requests.get(
        f"{BASE}/{path}",
        params={"handle": handle},
        headers={"x-api-key": KEY},
    ).json()
    if not res["success"]:
        print(path, res["error"]["type"], res["error"]["message"])
        continue
    author = res["data"]["author"]
    print(
        f"{path:<20} {author['followers']:>14,} followers"
        f"  cost {res['credits_used']}  left {res['credits_remaining']}"
    )
```

```typescript title="TypeScript"
const KEY = process.env.SOCIALCRAWL_API_KEY!;
const BASE = "https://www.socialcrawl.dev/v1";

const calls = [
  ["tiktok/profile", "nasa"],
  ["instagram/profile", "nasa"],
  ["youtube/channel", "nasa"],
  ["twitter/profile", "nasa"],
] as const;

for (const [path, handle] of calls) {
  const res = await fetch(`${BASE}/${path}?handle=${handle}`, {
    headers: { "x-api-key": KEY },
  });
  const json = await res.json();
  if (!json.success) {
    console.log(path, json.error.type, json.error.message);
    continue;
  }
  const { followers } = json.data.author;
  console.log(
    `${path.padEnd(20)} ${followers.toLocaleString().padStart(14)} followers` +
      `  cost ${json.credits_used}  left ${json.credits_remaining}`,
  );
}
```

```bash title="cURL"
for path in tiktok/profile instagram/profile youtube/channel twitter/profile; do
  curl -s "https://www.socialcrawl.dev/v1/$path?handle=nasa" \
    -H "x-api-key: $SOCIALCRAWL_API_KEY" \
  | python3 -c "import sys, json; r = json.load(sys.stdin); print('$path', r['data']['author']['followers'], 'cost', r['credits_used'])"
done
```

Want one call instead of a loop? Universal search fans one query out across 15 platforms and merges the results into one list, for 20 credits.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/search/everywhere?query=artemis%20launch" \
  -H "x-api-key: YOUR_API_KEY"
```

It waits for every platform to answer, so allow up to 60 seconds and read it with a client timeout to match. See [Universal search](/docs/search/everywhere.md) for streaming the results as they land.

### Find any endpoint without leaving your terminal

The catalogue is free. Every `/v1/utility/*` call and the balance call cost 0 credits, answer in about 150 ms, and are generated from the endpoint registry at request time.

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

# The full guide for one endpoint: parameters, cost, paging, an example call
curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=tiktok/post/comments" \
  -H "x-api-key: YOUR_API_KEY"

# Your balance
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

If an AI agent writes your code, give it the same three calls. The [MCP server and Agent Skill](/docs/skills-and-mcp.md) already do this before every request.

## How do I make a retry safe?

Add an `Idempotency-Key` header. A replay within 24 hours returns the original response and deducts 0 new credits, so a network timeout cannot bill you twice.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## What if a call fails?

Errors use the same JSON shape with `success: false`. Branch on `error.type`, never on the message string, and follow `error.doc_url` to the fix.

```json title="Response"
{
  "success": false,
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "message": "Your account has 0 credits remaining. This endpoint requires 1 credits.",
    "status": 402,
    "doc_url": "https://www.socialcrawl.dev/docs/errors#insufficient-credits"
  },
  "credits_used": 0,
  "credits_remaining": 0,
  "request_id": "req-abc123"
}
```

Only five codes are worth retrying: `RATE_LIMITED`, `CONCURRENCY_LIMIT`, `UPSTREAM_ERROR`, `SERVICE_UNAVAILABLE`, and `INTERNAL_ERROR`. Everything else is deterministic and will fail the same way on a retry. The full table and copy-paste backoff loops are in [Errors](/docs/errors.md).

## Next steps

- [Pagination](/docs/pagination.md): One rule for every list: send next_cursor back as cursor.
- [Credits](/docs/credits.md): Tier ladder, refunds, free cache hits, and the balance endpoint.
- [Which endpoint should I use?](/docs/choosing-endpoints.md): Side-by-side decision tables for the endpoints that look alike.
- [Recipes](/docs/recipes.md): Runnable builds, from brand monitoring to transcript corpora.