> ## 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.

# Data

> Search a catalogue of read-only data tools in 18 domains, read one's input schema, and run it — priced per run.

Three routes over one catalogue of read-only data tools in 18 domains — social media, people, companies, funding, markets, SEO, news, law, weather, jobs, property, reviews, trade, shopping and travel. The same catalogue an agent's `data_*` [tools](https://vetta.sh/docs/capabilities/tools.md) use; the guide is [Data](https://vetta.sh/docs/capabilities/data.md). The [social data routes](https://vetta.sh/docs/api/social-data.md) are its `social` domain under their own names.

## The data tool object

**object** `string`

Always `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.

**domains** `string[]`

What it is about: `social`, `search`, `people`, `companies`, `compliance`, `funding`, `seo`, `finance`, `crypto`, `news`, `legal`, `weather`, `jobs`, `real_estate`, `reviews`, `trade`, `shopping`, `travel`. See [Domains](https://vetta.sh/docs/capabilities/data.md#domains).

**platforms** `string[]`

For a `social` tool, the networks it reads (empty for every other domain): `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.002 per call"`).

## Search tools

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

**query** `string` *required*

What you need, as a short noun phrase (1–200 characters): `company funding rounds`, `homes for sale`.

**domain** `string`

Only tools in this domain (one of `domains` above).

**platform** `string`

Only social tools for this network (one of `platforms` above); implies `domain=social`.

**limit** `integer`

1–20, default 8.

Answers `{ data: 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/data/tools?query=company%20funding%20rounds&domain=funding&limit=3" \
  -H "authorization: Bearer sk_live_..."
```

```ts SDK theme={"system"}
const { data } = await client.data.searchTools({ query: "company funding rounds", domain: "funding", limit: 3 });
```

```bash CLI theme={"system"}
vetta data search "company funding rounds" --domain funding --limit 3
```

## Describe a tool

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

Answers the [tool](#the-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 data tool is `404 not_found`.

## Run a tool

`POST /v1/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 `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 source's data, unchanged. `null` when failed.

**error** `string | null`

Why it failed, in words that say what to change — often the parameter the source 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/data/runs \
  -H "authorization: Bearer sk_live_..." \
  -H "idempotency-key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{ "tool_id": "<tool_id>", "query": { "company": "acme.com" } }'
```

```ts SDK theme={"system"}
const run = await client.data.run({ tool_id, query: { company: "acme.com" } });
```

```bash CLI theme={"system"}
vetta data run <tool_id> --query company=acme.com
```

```json Response theme={"system"}
{
  "object": "data_run",
  "tool_id": "<tool_id>",
  "status": "succeeded",
  "data": { "company": "acme.com", "rounds": [{ "type": "Series A", "amount_usd": 12000000 }] },
  "error": null,
  "cost_micro_usd": 2000,
  "created_at": "2026-10-04T12: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 data tool. |
| 429 | `rate_limited` | Too many runs at once; retry shortly. |
| 501 | `feature_not_configured` | Data is not enabled on this deployment. |
| 502 | `provider_error` | The service did not answer, the run passed two minutes and was stopped, or a run succeeded but the service had not reported its cost yet (its output is withheld; retry). Nothing is billed. |

## Pricing

Search and describe are free. Each run is capped at 25 results: any result-count field above 25, at any depth of the input (`limit`, `maxItems`, `maxResults`, `resultsPerPage`, `pageSize`, `num…`, `max…`, `…Count`), is lowered to 25, and the balance must cover the listed price for one call (or for 30 results on a per-result tool, since some sources bill results in blocks of 10). It is then booked at the tool's `price`, once on the `search` component; a failed or stopped run is normally free, but one the source billed (a timeout or stop that had already gathered results) 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.