> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Social data

> Search a catalogue of read-only tools for public social media data, read one's input schema, and run it — priced per run, no connected account.

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](https://vetta.sh/docs/capabilities/tools.md) in the `social` domain; the guide is [Social data](https://vetta.sh/docs/capabilities/social-data.md). These routes are the [data routes](https://vetta.sh/docs/api/data.md)' `social` domain.

## The social data tool object

**object** `string`

Always `social_data_tool`.

**id** `string`

Opaque. Pass it back to [describe](#describe-a-tool) or [run](#run-a-tool) unchanged; it has no prefix and is not a stored object.

**name** `string`

What the tool does, briefly.

**description** `string`

What it returns. On [describe](#describe-a-tool), the long form.

**platforms** `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`.

**price** `object`

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

## Search tools

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

**query** `string` *required*

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

**platform** `string`

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

**limit** `integer`

1–20, default 8.

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

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

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

```bash CLI theme={"system"}
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](#the-social-data-tool-object) plus:

**input** `object`

A JSON Schema per input location — `path`, `query`, `body` — each present only when the tool takes it. A [run](#run-a-tool) sends parameters in the same three places.

**notes** `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`](https://vetta.sh/docs/api/overview#idempotency) optional: a retry under the same key replays the first answer and is billed once.

**tool\_id** `string` *required*

An `id` from search.

**query** `object`

Query parameters, as `input.query` describes.

**path** `object`

Path parameters, as `input.path` describes.

**body** `object`

Body fields, as `input.body` describes.

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

**object** `string`

Always `social_data_run`.

**tool\_id** `string`

The tool that ran.

**status** `string`

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

**data** `any`

The network's data, unchanged. `null` when failed.

**error** `string | null`

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

**cost\_micro\_usd** `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.

**created\_at** `string`

ISO 8601.

```bash cURL theme={"system"}
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" } }'
```

```ts SDK theme={"system"}
const run = await client.socialData.run({ tool_id, query: { username: "nasa" } });
```

```bash CLI theme={"system"}
vetta social-data run <tool_id> --query username=nasa
```

```json Response theme={"system"}
{
  "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](https://vetta.sh/docs/platform/pricing.md#priced-tools).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.