> ## 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](/docs/capabilities/tools) use; the guide is [Data](/docs/capabilities/data). The [social data routes](/docs/api/social-data) are its `social` domain under their own names.

## The data tool object

<ResponseField name="object" type="string">Always `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="domains" type="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](/docs/capabilities/data#domains).</ResponseField>
<ResponseField name="platforms" type="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`.</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.002 per call"`).</ResponseField>

## Search tools

`GET /v1/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): `company funding rounds`, `homes for sale`.</ParamField>
<ParamField query="domain" type="string">Only tools in this domain (one of `domains` above).</ParamField>
<ParamField query="platform" type="string">Only social tools for this network (one of `platforms` above); implies `domain=social`.</ParamField>
<ParamField query="limit" type="integer">1–20, default 8.</ParamField>

Answers `{ data: 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/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
  ```
</CodeGroup>

## Describe a tool

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

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

## Run a tool

`POST /v1/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 `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 source'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 source 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/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
  ```
</CodeGroup>

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


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