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

## The social data tool object

<ResponseField name="object" type="string">Always `social_data_tool`.</ResponseField>
<ResponseField name="id" type="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.</ResponseField>
<ResponseField name="name" type="string">What the tool does, briefly.</ResponseField>
<ResponseField name="description" type="string">What it returns. On [describe](#describe-a-tool), the long form.</ResponseField>
<ResponseField name="platforms" type="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`.</ResponseField>
<ResponseField name="price" type="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"`).</ResponseField>

## Search tools

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

<ParamField query="query" type="string" required>What you need, as a short noun phrase (1–200 characters): `tiktok video comments`, `instagram profile`.</ParamField>
<ParamField query="platform" type="string">Only tools for this network (one of `platforms` above).</ParamField>
<ParamField query="limit" type="integer">1–20, default 8.</ParamField>

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

<CodeGroup>
  ```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
  ```
</CodeGroup>

## Describe a tool

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

Answers the [tool](#the-social-data-tool-object) plus:

<ResponseField name="input" type="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.</ResponseField>
<ResponseField name="notes" type="string[]">Usage notes: quirks, limits, the parameter that controls volume.</ResponseField>

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

<ParamField body="tool_id" type="string" required>An `id` from search.</ParamField>
<ParamField body="query" type="object">Query parameters, as `input.query` describes.</ParamField>
<ParamField body="path" type="object">Path parameters, as `input.path` describes.</ParamField>
<ParamField body="body" type="object">Body fields, as `input.body` describes.</ParamField>

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

<ResponseField name="object" type="string">Always `social_data_run`.</ResponseField>
<ResponseField name="tool_id" type="string">The tool that ran.</ResponseField>
<ResponseField name="status" type="string">`succeeded` or `failed`. A failed run is still a `200`: it happened, and `error` says why.</ResponseField>
<ResponseField name="data" type="any">The network's data, unchanged. `null` when failed.</ResponseField>
<ResponseField name="error" type="string | null">Why it failed, in words that say what to change — often the parameter the network refused.</ResponseField>
<ResponseField name="cost_micro_usd" type="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.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601.</ResponseField>

<CodeGroup>
  ```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
  ```
</CodeGroup>

```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](/docs/platform/pricing#priced-tools).


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