Bulk link data (batch_stats)
POST /v1/tools/batch_stats runs Bulk link data, a ready-made tool that returns the numbers of up to 2,000 links to posts or account pages as they are now, and which links no longer work. No AI analysis. It reads 17 platforms and costs from 1 credit per link. Send max_cost_credits and a run that would cost more is refused for free, with the quote. A dead link is not charged.
https://api.socialtoai.com/v1/tools/batch_statsTo fill it in on the site, or to see what its result looks like, open Bulk link data.
Request
A JSON body with the tool's own inputs. The key goes in the Authorization header, as on every call.
| Name | Type | Required | What it is |
|---|---|---|---|
urls | string[] | Yes | 1 to 2,000 links to posts or account pages; they may be of different platforms. |
max_cost_credits | integer | No | Refused, free, with the quote, if the run would cost more. |
confirm | boolean | No | true: run it whatever it costs. false: answer the plan and its price, and run nothing. Left out: a costly run, and one that runs in the background, answers its price first. |
curl https://api.socialtoai.com/v1/tools/batch_stats \ -H "Authorization: Bearer $SOCIALTOAI_KEY" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://x.com/NASA"] }'import osimport requestsresponse = requests.post( "https://api.socialtoai.com/v1/tools/batch_stats", headers={"Authorization": f"Bearer {os.environ['SOCIALTOAI_KEY']}"}, json={ "urls": ["https://x.com/NASA"], },)print(response.json())Credits per link
Each link is one row, priced as one call on its platform.
| Platform | A post link | An account link |
|---|---|---|
| TikTok | 2 | 2 |
| 2 | 2 | |
| X | 1 | 1 |
| 2 | 2 | |
| YouTube | 2 | 2 |
| 2 | 2 | |
| 2 | 2 | |
| Threads | 2 | 2 |
| Telegram | 2 | 2 |
| Xiaohongshu | 12 | 12 |
| Douyin | 2 | 2 |
| 2 | 2 | |
| WeChat Articles | 24 | 12 |
| Bilibili | 2 | 2 |
| Zhihu | 2 | 2 |
| Kuaishou | 2 | 12 |
| WeChat Channels | 12 | 12 |
What a result holds
| Part | What it holds |
|---|---|
| One row per link | The numbers of each link as they are now. |
| Links that no longer work | Links that were deleted or could not be recognised. These rows are not charged. |
| Main number | Engagement of the links that work |
Quote or run: confirm
The same request either runs or comes back as a quote. confirm, a boolean beside the tool's inputs, decides which:
| confirm | What comes back |
|---|---|
false | The quote, always. Free: nothing is reserved, fetched or charged. |
| left out | The run, when it costs at most 100 credits and is answered within the request. Above that, or when the plan runs in the background (quote.mode is background), the quote first. |
true | The run, charged at most what the quote states. A run that cannot be made is refused for free with not_supported; it is never answered with a quote you did not ask for. |
A run's answer carries a handle: for 24 hours the whole result can be read again with it, for free. Results and handles has the details. The same request sent again under its Idempotency-Key returns the first run's answer and costs 0.
The quote
A quote is the plan of exactly this request and the most a run of it is charged. Nothing is reserved, fetched or charged for it. status is quote.
| Field | Type | What it is |
|---|---|---|
request_id | string | The id of this request. |
schema_version | "v1" | The version of the response format. |
tool | string | The tool the quote is for. |
scale | "small" | "medium" | "large" | null | The depth the quote is for; null for a tool priced by the row. |
status | "quote" | quote: nothing was reserved, fetched or charged. |
quote.credits | integer | The most the run is charged. |
quote.parts.data_first | integer | The first half of the fetching price. |
quote.parts.data_second | integer | The second half of the fetching price. Not charged when less than half of the planned reading comes back. |
quote.parts.analysis | integer | The price of the AI analysis. Charged only when at least nine in ten of the delivered rows were analysed. |
quote.mode | "sync" | "background" | sync: answered within the request. background: answered with a handle, and run in waves. |
quote.waves | integer | How many waves a background run is made of; 1 for a run answered within the request. |
quote.estimated_seconds | integer | About how long the run takes. |
quote.free_tier.runnable | boolean | Whether an account that has not bought credits may run it. |
quote.free_tier.reasons | string[] | When it may not, why: cost, duration or paid_only. |
quote.plan | array | Every step in the order it runs: the platform, the action, how many targets and pages or how many batches of analysis, and its credits. |
quote.price_version | string | The price version the quote was made from. |
billing | object | As in every answer: see Credits and billing. |
How a run is charged
- Priced by the row: Each link is one row, at what one call on its platform costs.
- Dead rows are not charged: A row that was deleted, not recognised or skipped is not charged. A row with numbers is, also when they are zero.
- You see the most first: Before it runs you get the most this list can cost. It never costs more.
- A row whose link was deleted, could not be recognised or was skipped is not charged. A row that comes back with numbers is charged, also when the numbers are zero. If you cancel, rows that already finished stay charged and the rest are not.
- The rows on that platform that fail are not charged, and the other rows are not affected. When more than three in ten rows of a batch fail, the rest of the list is not started.
Over MCP
The MCP tool is research, called with tool set to batch_stats. It takes the same inputs and costs the same. The tool list has the description your AI is given.
Last updated: