Brand buzz (brand_buzz)
POST /v1/tools/brand_buzz runs Brand buzz, a ready-made tool that returns what people say about a brand or product on each platform: the share of each attitude, what is mentioned most, and the posts with the most engagement, each with its source link. It reads 16 platforms and costs from 16 credits a run. Send max_cost_credits and a run that would cost more is refused for free, with the quote. A run that fetches nothing is not charged.
https://api.socialtoai.com/v1/tools/brand_buzzTo fill it in on the site, or to see what its result looks like, open Brand buzz.
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 |
|---|---|---|---|
brand | string | Yes | The brand, product or topic by its name. |
about | string | No | What it is, in a sentence: keeps out other things of the same name. |
compare_with | string[] | No | Up to 2 competitors. Each is read by the same plan and priced on its own. |
platforms | string[] | No | 1 to 5 platforms. Left out: the usual three for the language the name is written in, as far as each is offered; the answer names them. |
window | string | No | How far back to read. Values: 7d, 30d, 90d (default 30d). |
scale | string | No | small reads up to 40 posts a platform and no comments; medium about 100 posts and 2 pages of comments of 6 of them; large about 200 posts and 3 pages of comments of 15. Values: small, medium, large (default small). |
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/brand_buzz \ -H "Authorization: Bearer $SOCIALTOAI_KEY" \ -H "Content-Type: application/json" \ -d '{ "brand": "Notion", "platforms": ["tiktok"], "window": "30d", "scale": "small" }'import osimport requestsresponse = requests.post( "https://api.socialtoai.com/v1/tools/brand_buzz", headers={"Authorization": f"Bearer {os.environ['SOCIALTOAI_KEY']}"}, json={ "brand": "Notion", "platforms": ["tiktok"], "window": "30d", "scale": "small", },)print(response.json())Depths and credits
scale picks the depth. A depth has one price on each platform, stated before the run.
| Depth | scale | What it reads | From (credits) | How it runs | On the 100 free credits |
|---|---|---|---|---|---|
| Quick | small | Up to 40 posts per platform. No comments. | 16 | runs while you wait | Yes |
| Medium | medium | About 100 posts per platform, plus 2 pages of comments on 6 of them. | 76 | runs while you wait | On 6 of 13 platforms |
| Large | large | About 200 posts per platform, plus 3 pages of comments on 15 of them. | 210 | partly in the background | After your first purchase |
Credits by platform
The table is for one name on one platform. Several platforms add up, and each name you compare adds the same again.
| Platform | Quick | Medium | Large |
|---|---|---|---|
| TikTok | 16 | 140 | 440 |
| 16 | 92 | 254 | |
| X | 16 | 124 | 368 |
| 20 | 76 | 210 | |
| YouTube | 16 | 100 | 284 |
| 20 | — | — | |
| Threads | 16 | — | — |
| 16 | — | — | |
| Xiaohongshu | 36 | 258 | 780 |
| Douyin | 60 | 180 | 420 |
| 20 | 100 | 282 | |
| WeChat Articles | 36 | 270 | 834 |
| Bilibili | 16 | 100 | 284 |
| Zhihu | 18 | 90 | 234 |
| Kuaishou | 60 | 210 | 540 |
| WeChat Channels | 60 | 306 | 906 |
What a result holds
| Part | What it holds |
|---|---|
| How people feel, by platform | The share of positive, neutral and negative posts on each platform, with the number of posts read. |
| What comes up most | The things people mention most, each with its share of the posts and quotes from them. |
| Most-engaged posts | The posts with the most engagement, each with its numbers and its source link. |
| Main number | Relevant posts |
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
- You see the price first: The total is stated before anything starts. It does not grow if there is more to read.
- Nothing fetched, nothing charged: If nothing could be fetched, the run is not charged. If it stops partway, you are charged only for the part that finished.
- Each depth is one price: A depth has a fixed price on each platform. It is not reduced when there turns out to be less to read, so start small and go deeper when you need more.
- If nothing could be fetched, the run is not charged. If content was fetched but the conditions you set filtered all of it out, only the first half of the fetching price is charged. If a run stops partway, you are charged only for the part that finished.
- The run goes on with what could be read, and the result says how much of the plan that was. The price has three parts: two for fetching and one for the AI analysis. When less than half of the planned reading came back, the second fetching part is not charged. The analysis part is charged only when at least nine in ten of the delivered rows were analysed. A call whose outcome is unknown is never retried on our own.
Over MCP
The MCP tool is brand_buzz. It takes the same inputs and costs the same. The tool list has the description your AI is given.
Last updated: