Social data

Three routes over one catalogue of read-only tools for public posts, profiles, comments, followers, hashtags and trends on about 21 networks. The same catalogue an agent reads with its data_* tools in the social domain; the guide is Social data. These routes are the data routes’ social domain.

string

Always social_data_tool.

string

Opaque. Pass it back to describe or run unchanged; it has no prefix and is not a stored object.

string

What the tool does, briefly.

string

What it returns. On describe, the long form.

string[]

The networks it reads: x, instagram, tiktok, facebook, reddit, youtube, snapchat, linkedin, threads, telegram, douyin, kuaishou, xiaohongshu, weibo, bilibili, zhihu, wechat, lemon8, pipixia, toutiao, xigua.

object

What a run costs you: basis (per_call, per_result or varies), micro_usd (integer; for varies, the highest case) and text ("$0.0039 per call").

Search tools

GET /v1/social_data/tools → 200 OK — scope agents:read. Free.

string

required

What you need, as a short noun phrase (1–200 characters): tiktok video comments, instagram profile.

string

Only tools for this network (one of platforms above).

integer

1–20, default 8.

Answers { data: social_data_tool[] }, best match first. There is no cursor: the ranking is the page.

curl -fsSL "https://api.vetta.sh/v1/social_data/tools?query=instagram%20profile&platform=instagram&limit=3" \
  -H "authorization: Bearer sk_live_..."

const { data } = await client.socialData.searchTools({ query: "instagram profile", platform: "instagram", limit: 3 });

vetta social-data search "instagram profile" --platform instagram --limit 3

Describe a tool

GET /v1/social_data/tools/{id} → 200 OK — scope agents:read. Free. Answers the tool plus:

object

A JSON Schema per input location — path, query, body — each present only when the tool takes it. A run sends parameters in the same three places.

string[]

Usage notes: quirks, limits, the parameter that controls volume.

An id that is not a social data tool is 404 not_found.

Run a tool

POST /v1/social_data/runs → 200 OK — scope sessions:write. Priced. Idempotency-Key optional: a retry under the same key replays the first answer and is billed once.

string

required

An id from search.

object

Query parameters, as input.query describes.

object

Path parameters, as input.path describes.

object

Body fields, as input.body describes.

The request returns when the run ends — usually seconds, at most about two minutes.

string

Always social_data_run.

string

The tool that ran.

string

succeeded or failed. A failed run is still a 200: it happened, and error says why.

any

The network’s data, unchanged. null when failed.

string | null

Why it failed, in words that say what to change — often the parameter the network refused.

integer

What this run debited, on the search tier. Normally 0 for a failed run, and then no ledger entry is written; a stopped per-result run debits what it gathered.

string

ISO 8601.

curl -fsSL https://api.vetta.sh/v1/social_data/runs \
  -H "authorization: Bearer sk_live_..." \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{ "tool_id": "<tool_id>", "query": { "username": "nasa" } }'

const run = await client.socialData.run({ tool_id, query: { username: "nasa" } });

vetta social-data run <tool_id> --query username=nasa

Response

{
  "object": "social_data_run",
  "tool_id": "<tool_id>",
  "status": "succeeded",
  "data": { "username": "nasa", "follower_count": 98000000 },
  "error": null,
  "cost_micro_usd": 3900,
  "created_at": "2026-10-02T12:00:00.000Z"
}

Errors

Status	`code`	When
400	`validation_failed`	A missing `tool_id`, a parameter location that is not an object, or input the service refused before running. Nothing is billed.
402	`insufficient_credits`	The prepaid balance is below the tool’s listed price for one call (or for 25 results on a per-result tool, the most one run returns). Checked before the run starts.
404	`not_found`	The `tool_id` is not a social data tool.
429	`rate_limited`	Too many runs at once; retry shortly.
501	`feature_not_configured`	Social data is not enabled on this deployment.
502	`provider_error`	The service did not answer, or the run passed two minutes and was stopped. Nothing is billed.

Pricing

Search and describe are free. A run is the tool’s price, booked once on the search component; a failed or stopped run is normally free (a stopped per-result run costs what it gathered). See Pricing.

Introduction

Core resources

Platform

Identity

Search tools

Describe a tool

Run a tool

Errors

Pricing

​The social data tool object

​Search tools

​Describe a tool

​Run a tool

​Errors

​Pricing

The social data tool object

Search tools

Describe a tool

Run a tool

Errors

Pricing