Call social data from an AI agent

What the agent sees

The MCP guide groups endpoints so the client is not handed one tool per route. The tools it lists:

• get_transcript, search, get_profile, get_post, get_comments. The platform is an argument. These are the common jobs.
• One tool per platform, such as github or facebook. resource picks the data (user, profile.posts, and so on). Parameters match the API.
• describe. Exact parameters, allowed values, price and example arguments for any endpoint. Free, and it makes no API call.
• call_endpoint, batch, get_job, monitors, get_credits. Any endpoint by id, up to 100 requests in one call, long jobs, webhooks and the balance.

The guide says only built endpoints appear, because the tool list is generated from the same registry as the reference. A stub that is not in the reference is not a tool. The feature page repeats this set.

describe is the tool an agent should use before it invents a parameter. The same facts are on each endpoint page and in the API reference.

The guide also says a result line reports credits charged and credits remaining, that trim defaults to true to keep context short, and that agents should pass max_age_days when freshness is not critical.

Those two query flags already work on the HTTP API. You do not need MCP to use them.

The same call over HTTP

Give the agent a key and the base URL https://api.socialscrape.dev. The key is the x-api-key header, never a query parameter. Create one key per agent so you can see its usage and revoke it alone.

Keys belong to a team. A team can hold up to 20 active keys. The owner and admins create them. See authentication and teams.

A profile lookup is the smallest useful tool. GET /v1/tiktok/profile with handle:

1curl -G "https://api.socialscrape.dev/v1/tiktok/profile" \2  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \3  --data-urlencode "handle=khaby.lame"

1import os2import requests34params = {5    "handle": "khaby.lame",6}7res = requests.get(8    "https://api.socialscrape.dev/v1/tiktok/profile",9    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},10    params=params,11)12body = res.json()1314if body["ok"]:15    print(body["data"])16else:17    print(body["error"]["code"], body["error"]["message"])

1const url = new URL("https://api.socialscrape.dev/v1/tiktok/profile");2url.search = new URLSearchParams({3  "handle": "khaby.lame"4}).toString();5const res = await fetch(url, {6  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },7});8const body = await res.json();910if (body.ok) {11  console.log(body.data);12} else {13  console.error(body.error.code, body.error.message);14}

Tell the agent to read ok first. On success, data is the profile: handle, name, bio, stats.followers, stats.following, stats.posts, stats.likes, url, verified. credits_charged is 1 on a fresh hit and 0 on a cached one.

credits_remaining is the team balance. On failure, read error.code and error.retryable. Do not retry not_found or invalid_params. Do retry rate_limited after retry-after seconds. The message text can change. The code should not.

The same pattern covers every other GET. The path and the parameters are on the reference. Examples on this blog: Instagram comments, YouTube channels, Ad Library search, a listening pass.

llms.txt and llms-full.txt are the docs in a form a model can read. They are linked from the MCP guide. Draft pages stay out of llms.txt.

Credits, on purpose

An agent will loop. Cap it with the team balance, not with a prompt. New accounts get 100 credits once, no card. A pack is a one-time buy. Starter is $13 for 1,000 credits. Monthly Starter is $27 for 18,000, and those credits reset. The rest of the table is pricing.

Plan credits are spent before pack credits. A request is charged only when it succeeds, so parallel calls cannot overdraw. Too few credits is 402 insufficient_credits. The credits guide says that response can include payment details an agent with a card can act on.

This post does not walk through a payment. Read that guide before you let an agent buy anything. A failure costs 0 either way.

max_age_days is how you keep a research agent from paying twice for the same profile. Set it when this morning's copy is fine. Omit it when the count has to be fresh. Cache rules are in caching.

A batch of up to 100 requests is POST /v1/batch. It saves round trips. Each item still counts toward the requests in progress and, on success, toward credits. See batch and jobs. Packs and plans have no rate limits; free accounts have a lower one, per team. See rate limits.