---
title: "Quickstart · Docs · SocialToAI"
canonical: https://socialtoai.app/docs/
updated: 2026-11-20
---

# Quickstart

> The public REST API and MCP are not yet available on socialtoai.app. The signed-in console supports Xiaohongshu comment reports.

SocialToAI is an API and MCP server that lets AI tools read publicly visible social media content (posts, comments, profiles and trends) from 18 platforms, including TikTok, Instagram, X (Twitter), Reddit, YouTube, Xiaohongshu (RedNote), Douyin, Weibo. It is billed in prepaid credits, and failed calls are free.

- Page: https://socialtoai.app/docs/
- Last updated: 2026-11-20

Get a key, make one call, connect your AI. Everything on this page runs on the 100 free credits you get when you sign up.

- REST: `https://socialtoai.app/v1/<action>`
- MCP: `https://socialtoai.app/mcp`

### The facts

- Platforms (18): TikTok, Instagram, X (Twitter), Reddit, YouTube, Facebook, LinkedIn, Threads, Telegram, Pinterest, Xiaohongshu (RedNote), Douyin, Weibo, WeChat Articles, Bilibili, Zhihu, Kuaishou, WeChat Channels
- Ad libraries (2): Meta Ad Library, Google Ads Transparency
- Actions (6): search, trending, detail, comments, user_profile, user_posts, plus a catalog of platform-specific interfaces (find / call)
- Tools (7): Brand buzz, Comment analysis, Account snapshot, Find creators, Creator profile, Bulk link data, Viral finder
- API: https://socialtoai.app/v1 · MCP (Streamable HTTP): https://socialtoai.app/mcp · Auth: sign-in (OAuth) in ChatGPT, Claude, Claude Code, Codex and Cursor; an API key in a header for scripts and servers
- No key needed for: capabilities, find, OpenAPI
- Price: $10 = 3,000 credits · $50 = 20,000 · $200 = 100,000 · any amount from $10 to $2,000
- Per call: most calls cost 2 credits (range 1–102); from $0.002 per call
- Free: 100 credits on sign-up, no card. Credits never expire. No subscription. No refunds.
- Charged: successful calls, including a search that ran and found nothing, and a lookup of something that is not there where the platform's source charges for it (the answer says so). Not charged: failed calls.
- Limits: 5 requests per second per key; 20 per second after the first purchase
- Payment: card or Alipay, priced in USD
- Data: content and account information publicly visible on the platform; commenters are anonymised
- Updated: 2026-11-20 · price version pv_0f22059fed3e

## 1. Get a key

Sign in (https://socialtoai.app/sign-in/) with Google, or with your email: we send a one-time code. There is no password to set. A new account starts with 100 credits and needs no card.

In the console, open API keys and create a key. It starts with `stai_live_` and is shown once, so copy it right away. Then keep it in an environment variable:

**Terminal**

```
export SOCIALTOAI_API_KEY="<YOUR_API_KEY>"
```

> **Keep it secret** Send the key in the `Authorization` header. Treat it like a password: keep it out of chats, screenshots and shared code. If a key leaks, revoke it in the console and create a new one.

## 2. Make your first call

Every action is one `POST` to `https://socialtoai.app/v1/<action>` with a JSON body. This one is `/v1/search`: find posts by keyword: text, author, likes, comment count and publish time, on LinkedIn.

**cURL**

```
curl https://socialtoai.app/v1/search \
  -H "Authorization: Bearer $SOCIALTOAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "query": "AI SDR"
  }'
```

**Python**

```
import os
import uuid
import requests

response = requests.post(
    "https://socialtoai.app/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIALTOAI_API_KEY']}",
        # A new key for each request; the same one again retries it without paying twice.
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "platform": "linkedin",
        "query": "AI SDR",
    },
)
print(response.json())
```

You get this back:

**Response** (200 OK, 2 credits)

```
{
  "status": "ok",
  "action": "search",
  "platform": "linkedin",
  "items": [
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/adamschoenfeld_ai-sdrs-had-a-false-start-now-theres-a-activity-7519050542090768384-UK-T",
      "text": "The first wave was overhyped back in 2023-2024. We all got sick of the \"replace humans\" pitches, the over-prom",
      "metrics": {
        "likes": 234,
        "comments": 93,
        "views": null
      }
    },
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/ashleyekramer_the-best-way-to-understand-where-agents-add-activity-7505733465905152000-xKuc",
      "text": "At ElevenLabs, we started with inbound qualification. Leads can choose to speak with Dom, our AI SDR, and get",
      "metrics": {
        "likes": 536,
        "comments": 28,
        "views": null
      }
    },
    {
      "platform": "linkedin",
      "type": "content",
      "url": "https://www.linkedin.com/posts/jasonmlemkin_if-you-hook-up-an-ai-sdr-and-go-away-and-activity-7344825206001082368-Cqhd",
      "text": "If you hook up an AI SDR and go away and do nothing, you will get nothing. Zilch. Nada. Nothing. Will fail. If you hook up a",
      "metrics": {
        "likes": 113,
        "comments": 41,
        "views": null
      }
    }
  ],
  "cost_credits": 2
}
```

_A real call, recorded on 2026-10-30: 3 of the 10 items it returned, only the fields shown here, each text cut to its start. Every field of an item is on the response page._

> **Good to know** That call cost 2 credits. Every response ends with `billing`, so you and your AI always know what was spent and what is left.

## 3. Connect your AI over MCP

If you work in an AI client, you do not have to write requests at all. Add an MCP server in your AI with this address: `https://socialtoai.app/mcp`. If a sign-in page opens, sign in with your email and press Allow. If your tool asks for a key instead, put the key you just made in a header: `Authorization: Bearer <YOUR_API_KEY>`.

In a terminal, run the command. In Claude Code, then in Claude Code type /mcp, pick socialtoai and sign in:

**Claude Code**

```
claude mcp add --transport http socialtoai https://socialtoai.app/mcp
```

**Codex**

```
codex mcp add socialtoai --url https://socialtoai.app/mcp
```

Then ask in plain words. Your AI picks the call and tells you what it cost. [Step-by-step for your client](https://socialtoai.app/mcp.md).

## 4. Understand the response shape

Every platform and every action answers in the same shape. Learn these parts once and you can read all 18 platforms plus 2 ad libraries. What a platform does not provide comes back as `null`.

| Part | What it tells you |
| --- | --- |
| `request_id`, `action`, `platform`, `status` | What was called, and whether it worked. |
| `items` | The results. Every kind of item uses the same field names on every platform. |
| `unavailable` | The fields this platform cannot give. They are `null` in every item. |
| `page` | While `has_more` is true, send `cursor` back for the next page. |
| `billing` | What this call cost and your balance after it, in credits. |

[Response format](https://socialtoai.app/docs/api/response.md) lists every field of the envelope and of each kind of item.

## 5. Errors and what is not charged

Failed calls are free. A call that ran is charged, even if it found nothing; a few interfaces also charge for looking up something that does not exist, and the answer then carries `charged: true`. A request we refuse before it runs gets an HTTP error status. Trouble on the platform's side still comes back as HTTP `200`, with `status` and `error` in the body and `cost_credits` of `0`. Every error carries `request_id` and `fix`, which says how to correct the call.

| Code | HTTP | What happened, and what to do | Retry | Charged |
| --- | --- | --- | --- | --- |
| `invalid_params` | 400 | A parameter is missing or wrong. Nothing ran. Correct it using `fix` in the response. | No | No |
| `unauthorized` | 401 | The key is missing, wrong, expired or suspended. Send a current key in a header. `reason` says which case it is. | No | No |
| `insufficient_balance` | 402 | Not enough credits for this call. Nothing ran. Buy credits, then send it again. | No | No |
| `not_found` | 200 / 404 | The post or account does not exist, is private or was deleted; `why` says which when the platform tells, and `platform_says` gives its own words. Where the platform's source charges for the lookup, the call is charged its price and the error says `charged: true`. Nothing to retry. An unknown path also answers with this code. | No | At price, where the source charges |
| `daily_limit_reached` | 429 | A daily limit is reached. Nothing ran. The limit is on the key or the account and starts again at `resets_at`. | No | No |
| `rate_limited` | 429 | Too many calls per second for this key, or too many running at once. Wait for `Retry-After`, then send it again. | Yes | No |
| `temporarily_unavailable` | 200 / 503 | This call is paused for now. The status page says why. Try again later. | Yes | No |
| `invalid_target` | 200 | The link or ID does not point at a valid target. Check the value named in `fix.param`. | No | At price, where the source charges |
| `upstream_error` | 200 | No result came from the platform this time; it was already tried up to three times on our side. When `retryable` is true, send it once more after `retry_after_seconds`. If the same request fails again, the content itself most likely cannot be had: change the input. | Depends | No |
| `timeout` | 200 | No result in time, and we cannot tell whether it ran. We cover the cost. We never retry on our own (`X-Should-Retry: false`). Send a new request if you still need it. | No | No |

> **Good to know** Not an error: a search that runs and finds nothing. `status` is `empty`, `items` is empty, and the call is charged as usual.

[Errors](https://socialtoai.app/docs/api/errors.md) has every code with its cases.

## Next steps

- [API reference](https://socialtoai.app/docs/api/search.md): The 6 actions, their parameters and what each call costs.
- [Connect over MCP](https://socialtoai.app/mcp.md): One address for every client, and the steps for each.
- [Authentication](https://socialtoai.app/docs/authentication.md): Signing in from AI apps, where the key goes, and what works without a key.
- [Credits and billing](https://socialtoai.app/docs/credits-and-billing.md): What a credit is, what each call costs, and when you pay nothing.
- [Schedules](https://socialtoai.app/docs/schedules.md): Run the same request every day or every week, within a limit.
- [Webhooks](https://socialtoai.app/docs/webhooks.md): Get a signed message when a run finishes, instead of polling.
- [Batch jobs](https://socialtoai.app/docs/batches.md): Read up to 2,000 links in one job, in the background.
