# Quickstart (/docs/quickstart)



Quickstart [#quickstart]

Make your first SocialCrawl API request in under a minute. New accounts get 100 welcome credits — enough to try every standard endpoint without adding a payment method.

1\. Get Your API Key [#1-get-your-api-key]

Sign up at [socialcrawl.dev](https://www.socialcrawl.dev) and create a key in **Dashboard → API Keys**. Keys have the format `sc_` + 32 random bytes (46 characters total) and are shown in full exactly once on creation — copy it somewhere safe.

2\. Make a Request [#2-make-a-request]

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

3\. Read the Response [#3-read-the-response]

Every response follows the same envelope format:

```json
{
  "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
    },
    "_warnings": [
      "computed.engagement_rate: author ratio exceeded 1.0 (raw: 72.258065); returned null — a lifetime likes/followers ratio is not a real engagement rate"
    ]
  },
  "credits_used": 1,
  "credits_remaining": 99,
  "request_id": "req-abc123",
  "cached": false
}
```

Note the `computed` block. Every field in it is either a real number or an honest `null` — we never substitute a plausible-looking figure for one we cannot derive. On a profile response, `estimated_reach` is **always** `null` (a follower count carries no reach signal), and `engagement_rate` is `null` on the platforms that report cumulative lifetime likes, because dividing those by current followers is not an engagement rate. `language` and `content_category` need a bio with enough text to classify. Read [Computed fields](/docs/computed-fields.md) before you branch on any of them, and check `data._warnings` when a value is missing.

Responses also include useful headers: `X-Request-Id`, `X-Credits-Used`, `X-Credits-Remaining`, and `X-Cache` (`HIT` when served from cache — cache hits cost 0 credits).

4\. Retry Safely (Optional) [#4-retry-safely-optional]

Add an `Idempotency-Key` header to make any request safe to retry. Replays return the original response and deduct 0 new credits. For transient failures (`429`, `500`, `502`, `503`), see [Handling retries](/docs/errors.md#handling-retries) for copy-paste backoff loops in cURL, Python, and Node.

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

What should I build next? [#what-should-i-build-next]

* [Authentication](/docs/authentication.md) — manage keys, rotate them, protect them
* [Response Schema](/docs/response-schema.md) — the unified envelope, headers, and `_warnings`
* [Pagination](/docs/pagination.md) — one rule for every list endpoint: send `next_cursor` back as `cursor`, stop when `has_more` is false
* [Credits](/docs/credits.md) — tiers, refunds, free cache hits, balance endpoint
* [Which Endpoint Should I Use?](/docs/choosing-endpoints.md) covers the endpoint pairs developers most often confuse
* [Error Handling](/docs/errors.md) — every error code and when to retry
* [API Reference](/docs/api-reference.md) — try any of the 395 endpoints live

Building an AI agent? See [AI Agent Integration](/docs/ai-agents.md) and [Skills & MCP](/docs/skills-and-mcp.md).