# AI Agent Integration (/docs/ai-agents)

Machine-readable discovery files, Markdown twins, and the OpenAPI spec that let an agent learn the API on its own

Every response is the same JSON envelope, every endpoint takes one header, and the whole catalogue is published as machine-readable files an agent can read before it writes a request.

  If you only wire up one thing, point your agent at
  [`/llms-full.txt`](/llms-full.txt). It is the complete, self-contained
  reference.

## Prerequisites

- Nothing to install. Every discovery file below is public and needs no key.
- An API key from [socialcrawl.dev](https://www.socialcrawl.dev) (Dashboard → API Keys) for any call that returns data. New accounts start with 100 free credits.
- Using an MCP client or an agent skill instead? [Skills & MCP](/docs/skills-and-mcp.md) is a one-line setup that skips the plumbing on this page.

When an endpoint supports a computed field and the required source inputs are present, its response includes that optional field. Depending on the endpoint, these fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md).

## How do AI agents discover SocialCrawl?

Four machine-readable files describe the API, in increasing detail. Point your agent at [`/llms-full.txt`](/llms-full.txt) for everything it needs: the entire 679-endpoint catalogue is included.

| File                               | What it holds                                                                                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | Compact overview of the API                                                                                                                                |
| [`/llms-full.txt`](/llms-full.txt) | Complete self-contained reference, including the `GET /v1/credits/balance` meta endpoint, idempotency semantics, `oneOf` constraints, and every error code |
| [`/llms.json`](/llms.json)         | Machine-readable catalog: per-platform endpoint counts, auth, credit tiers, response envelope                                                              |
| [`/agents.txt`](/agents.txt)       | AI agent access file: capabilities, quick start, and crawl guidance in one place                                                                           |

## How do I read a docs page as Markdown?

Append `.md` to any docs URL:

- `/docs` becomes [`/docs.md`](/docs.md)
- `/docs/quickstart` becomes [`/docs/quickstart.md`](/docs/quickstart.md)
- `/docs/api-reference` becomes [`/docs/api-reference.md`](/docs/api-reference.md)

You can also send `Accept: text/markdown` on the HTML URL. Every docs page carries an "AI agent or LLM? Read this page as markdown" link pointing at the same twin. Twins are served as `text/plain`, marked `X-Robots-Tag: noindex`, and listed in [`/sitemaps/llm.xml`](/sitemaps/llm.xml).

## How can agents use the OpenAPI specification?

The full OpenAPI 3.1 specification is available in both formats:

- [`/v1/openapi.json`](/v1/openapi.json)
- [`/v1/openapi.yaml`](/v1/openapi.yaml)

The full spec covers every endpoint, so it is large. When you need one platform, fetch its own OpenAPI document instead, for example [`/openapi/tiktok.json`](/openapi/tiktok.json): the same contract for that platform's endpoints, a few MB at most. [`/openapi/index.json`](/openapi/index.json) lists every document with its endpoint count. Code generators and Postman imports work the same way.

Discover's whole lifecycle (the call, its `202` answer, the run routes, resume, cancel and `results.jsonl`) has its own OpenAPI 3.1 slice at [`/openapi/prism-discover.json`](/openapi/prism-discover.json).

## Which endpoint answers a question about several platforms?

To search one platform, call that platform's own search. To search several platforms over a date window with every row judged and de-duplicated, call `/v1/prism/discover`. For a quick fused sweep at a flat 20 credits, call `/v1/search/everywhere`, which drops rows outside `from_date`, `to_date`, `since` or `until` but reads one page per source, so a past window can come back thin. Discover answers in the call, or answers `202` with a run the agent follows at `data.next.status_url`, so one call always works. [Discover for agents](/docs/prism/discover-agents.md) has the two tool definitions, the retry policy and three worked transcripts.

## Which endpoint finds creators or influencers?

To find creators or influencers (by topic, market, size, or a product to promote), lookalikes of creators, or to measure and rank a list of creators you already have, call `/v1/prism/creators`. For shops, businesses and sellers, call `/v1/prism/discover` with `view=accounts`. It answers in the call, or answers `202` with a run the agent follows at `data.next.status_url`. [Creator search](/docs/prism/creators.md) has the two agent tools, the retry policy and the canonical requests, and its whole lifecycle has its own OpenAPI 3.1 slice at [`/openapi/prism-creators.json`](/openapi/prism-creators.json).

## Which call tells an agent when something new appears?

To be told when something new appears, match the ask to its job: for a recurring digest of what is new about a topic, keyword or brand, every 1h or slower, call `POST /v1/prism/discover` with `schedule` (every `1h` or slower, `dry_run` first), read through `GET /v1/events` or a webhook endpoint; for the new posts or comments of an account or post you already know, call `POST /v1/monitors` with `webhook_rows: "new"`; for a one-off check of what is new since your last check, on an endpoint that takes `since` or `since_id`, call the endpoint's own `since` or `since_id` (for example `GET /v1/twitter/tweet/replies` with `since_id`, which returns an empty list and costs nothing when nothing is new); for metric snapshots of accounts you name (followers, views, likes), taken on a schedule, call `POST /v1/monitors` with a `track` metric; for reading what your watches produced, from a feed you poll or an endpoint that receives a signed push, call `GET /v1/events` with a named `consumer` for reading, and `/v1/webhook-endpoints` for push; for what a keyword or boolean topic listener would cost each month and how it reads the rule, before it is created, call `POST /v1/listening/streams?dry_run=1` with the listener body, which costs 0 credits and creates nothing; for each new mention of keywords or a boolean topic delivered one by one, every 30 minutes or slower, with boolean groups, a monthly cap and usage per client, and with `comments: "new_posts"` the comments under the Reddit posts it keeps, call `POST /v1/listening/streams?dry_run=1` to price it, then `POST /v1/listening/streams` to create the listener; for the new posts of up to 1,000 named business, brand, creator or organisation accounts that match a topic, every 30 minutes or slower, call `POST /v1/listening/streams?dry_run=1` with `accounts` (each a `platform:handle` such as `reddit:nasa` or `youtube:@Google`, or a profile URL), `schedule.purpose` (`business`, `brand`, `creator` or `organisation`) and `keywords`, then `POST /v1/listening/streams` to create the listener; for what is new on your listeners since the last read, in a later session or on a schedule you run yourself, call `GET /v1/events` with a named `consumer` and `types=mention.*`, then acknowledge each page with its `pagination.next_cursor`. A watch checks on a schedule and reports what that check found. Read what a watch produced with the [event feed](/docs/events.md) or receive it at a signed [webhook endpoint](/docs/webhook-endpoints.md); the schedule is explained in [discover schedules](/docs/prism/discover.md#schedules) and the account watch in [Monitor webhooks](/docs/webhooks.md#only-the-new-rows).

## How does an agent find out that something needs its attention?

Read `GET /v1/notifications?unread=true` once a minute or less. It lists a paused Monitor webhook, a failed Discover run, a call refused for credits and similar items, each with a plain `title`, `message` and one concrete `next_step`, so the agent does not have to know the kinds. After it acts, it sends the item ids to `POST /v1/notifications/read`. Both calls are free. See [Notifications](/docs/notifications.md).

## What per-platform documentation is available?

Fetch only the endpoints you need. There is one file per active platform.

| Platform         | Reference File                                             |
| ---------------- | ---------------------------------------------------------- |
| TikTok           | [`/llms-tiktok.txt`](/llms-tiktok.txt)                     |
| Instagram        | [`/llms-instagram.txt`](/llms-instagram.txt)               |
| YouTube          | [`/llms-youtube.txt`](/llms-youtube.txt)                   |
| Facebook         | [`/llms-facebook.txt`](/llms-facebook.txt)                 |
| Twitter/X        | [`/llms-twitter.txt`](/llms-twitter.txt)                   |
| LinkedIn         | [`/llms-linkedin.txt`](/llms-linkedin.txt)                 |
| Reddit           | [`/llms-reddit.txt`](/llms-reddit.txt)                     |
| Threads          | [`/llms-threads.txt`](/llms-threads.txt)                   |
| Bluesky          | [`/llms-bluesky.txt`](/llms-bluesky.txt)                   |
| Pinterest        | [`/llms-pinterest.txt`](/llms-pinterest.txt)               |
| Snapchat         | [`/llms-snapchat.txt`](/llms-snapchat.txt)                 |
| Truth Social     | [`/llms-truthsocial.txt`](/llms-truthsocial.txt)           |
| Twitch           | [`/llms-twitch.txt`](/llms-twitch.txt)                     |
| Kick             | [`/llms-kick.txt`](/llms-kick.txt)                         |
| Rumble           | [`/llms-rumble.txt`](/llms-rumble.txt)                     |
| Kwai             | [`/llms-kwai.txt`](/llms-kwai.txt)                         |
| Spotify          | [`/llms-spotify.txt`](/llms-spotify.txt)                   |
| Apple Music      | [`/llms-apple_music.txt`](/llms-apple_music.txt)           |
| GitHub           | [`/llms-github.txt`](/llms-github.txt)                     |
| Hacker News      | [`/llms-hackernews.txt`](/llms-hackernews.txt)             |
| Naver            | [`/llms-naver.txt`](/llms-naver.txt)                       |
| Polymarket       | [`/llms-polymarket.txt`](/llms-polymarket.txt)             |
| Amazon           | [`/llms-amazon.txt`](/llms-amazon.txt)                     |
| Walmart          | [`/llms-walmart.txt`](/llms-walmart.txt)                   |
| Target           | [`/llms-target.txt`](/llms-target.txt)                     |
| eBay             | [`/llms-ebay.txt`](/llms-ebay.txt)                         |
| Home Depot       | [`/llms-home_depot.txt`](/llms-home_depot.txt)             |
| Wayfair          | [`/llms-wayfair.txt`](/llms-wayfair.txt)                   |
| TikTok Shop      | [`/llms-tiktokshop.txt`](/llms-tiktokshop.txt)             |
| Google Shopping  | [`/llms-google_shopping.txt`](/llms-google_shopping.txt)   |
| Google Play      | [`/llms-google_play.txt`](/llms-google_play.txt)           |
| Apple App Store  | [`/llms-app_store.txt`](/llms-app_store.txt)               |
| Trustpilot       | [`/llms-trustpilot.txt`](/llms-trustpilot.txt)             |
| Tripadvisor      | [`/llms-tripadvisor.txt`](/llms-tripadvisor.txt)           |
| Google           | [`/llms-google.txt`](/llms-google.txt)                     |
| Google News      | [`/llms-google_news.txt`](/llms-google_news.txt)           |
| Google Finance   | [`/llms-google_finance.txt`](/llms-google_finance.txt)     |
| Google Trends    | [`/llms-google_trends.txt`](/llms-google_trends.txt)       |
| Perplexity       | [`/llms-perplexity.txt`](/llms-perplexity.txt)             |
| Tavily           | [`/llms-tavily.txt`](/llms-tavily.txt)                     |
| Web Scraping     | [`/llms-web.txt`](/llms-web.txt)                           |
| Content Analysis | [`/llms-content_analysis.txt`](/llms-content_analysis.txt) |
| Universal Search | [`/llms-search.txt`](/llms-search.txt)                     |
| Prism composites | [`/llms-prism.txt`](/llms-prism.txt)                       |
| Utility          | [`/llms-utility.txt`](/llms-utility.txt)                   |
| Linktree         | [`/llms-linktree.txt`](/llms-linktree.txt)                 |
| LinkBio          | [`/llms-linkbio.txt`](/llms-linkbio.txt)                   |
| LinkMe           | [`/llms-linkme.txt`](/llms-linkme.txt)                     |
| Komi             | [`/llms-komi.txt`](/llms-komi.txt)                         |
| Pillar           | [`/llms-pillar.txt`](/llms-pillar.txt)                     |

Each file contains only that platform's endpoints, with parameters, descriptions, and cURL examples. [`/llms.txt`](/llms.txt) links the current list; treat that as the source of truth if this table ever trails a new platform launch.

## How do I integrate SocialCrawl with my AI agent?

### Read your key from the environment

Never inline a key in agent code or a prompt.

```typescript title="TypeScript"
const apiKey = process.env.SOCIALCRAWL_API_KEY;
if (!apiKey) throw new Error("Set SOCIALCRAWL_API_KEY");
```

### Call the endpoint with `x-api-key`

```typescript title="TypeScript"
const response = await fetch(
  "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
  { headers: { "x-api-key": apiKey } },
);
const json = await response.json();
```

### Branch on `success` before you hand anything to the model

```typescript title="TypeScript"
if (!json.success) {
  // Machine-readable failure: branch on error.type, follow error.doc_url.
  throw new Error(`${json.error.type}: ${json.error.message}`);
}
// json.data is structured and ready for AI reasoning
```

Never hand a raw `{ "success": false, ... }` envelope back to a model as if it were data. It will reason around the error instead of retrying or reporting it. Use `error.type` to decide what to do, and honour the `Retry-After` header on a `429` or `503`. The full list is on the [Errors](/docs/errors.md) page.

## Troubleshooting

**The agent invented an endpoint that does not exist**

It is guessing rather than reading. Give it [`/llms-full.txt`](/llms-full.txt), or the single platform file it needs, before it plans a call. An MCP client gets this for free: the server validates the platform, endpoint, and required parameters locally and refuses a bad call without spending a credit.

**The agent treats an error as data**

Its tool wrapper is returning the whole envelope. Check `success` inside the tool and return a short directive instead, for example `SocialCrawl error NOT_FOUND: ... See <doc_url>`. The [LangChain](/docs/langchain.md) and [Vercel AI SDK](/docs/vercel-ai-sdk.md) pages show the pattern.

**The agent burns credits looping on the same call**

Read `credits_remaining` from the envelope after each call and stop on a budget. Before following `next_cursor`, compare `pagination.next_page_credits` with what the budget has left, and stop when the next page would go over it. Cap the tool loop as well: both framework pages set an explicit step limit. Empty results and upstream errors are auto-refunded, but a retry storm on a valid endpoint is not.

**The agent's tool times out on a slow call**

Some calls take longer than the tool waits: the MCP server and many HTTP tools stop at 30 seconds, while `youtube/channel/about`, the transcript endpoints and `twitter/ai-search` can take longer. Have the agent add `async=true` to the query (or the header `Prefer: respond-async`). The call answers `202` at once with a `job_id`, and `GET /v1/prism/jobs/{job_id}` returns the finished response, free, in `results[0].response`. See [Async requests](/docs/async.md).

**A docs Markdown twin returns HTML**

The `.md` suffix goes on the path, not the query string: `/docs/quickstart.md`, not `/docs/quickstart?format=md`. Sending `Accept: text/markdown` on the HTML URL works too.

## Official AI framework documentation

- [Anthropic Claude tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
- [OpenAI function calling](https://platform.openai.com/docs/guides/function-calling)
- [Vercel AI SDK](https://sdk.vercel.ai/docs)
- [LangChain](https://python.langchain.com/docs/introduction/)

## Which calls should an agent make before it writes code?

Three free calls replace guessing. Each costs 0 credits, answers in about 150 ms, and is generated from the endpoint registry at request time, so an agent that reads them never invents a path or a parameter.

```bash title="cURL"
# Find the endpoint for a job
curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \
  -H "x-api-key: YOUR_API_KEY"

# Read its exact parameters, cost, paging rule, and an example call
curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=tiktok/post/comments" \
  -H "x-api-key: YOUR_API_KEY"

# Confirm the key works and see the balance
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

Put those three lines at the top of any agent prompt or system instruction that touches SocialCrawl. The MCP server and the Agent Skill already do this before every request.

## Next steps

- [Skills & MCP](/docs/skills-and-mcp.md): One-line setup for any MCP client or agent skill.
- [LangChain](/docs/langchain.md): Wrap the API in a single LangChain tool.
- [Vercel AI SDK](/docs/vercel-ai-sdk.md): The same pattern with tool() and generateText.
- [Errors](/docs/errors.md): Every error type, what it means, and whether to retry.