Data

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 use; the guide is Data. The social data routes are its social domain under their own names.

The data tool object

string

Always 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[]

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.

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.

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.

string

required

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

string

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

string

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

integer

1–20, default 8.

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

curl -fsSL "https://api.vetta.sh/v1/data/tools?query=company%20funding%20rounds&domain=funding&limit=3" \
  -H "authorization: Bearer sk_live_..."

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

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 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 data tool is 404 not_found.

Run a tool

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

string | null

Why it failed, in words that say what to change — often the parameter the source 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/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" } }'

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

vetta data run <tool_id> --query company=acme.com

Response

{
  "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.

Introduction

Core resources

Platform

Identity

The data tool object

Search tools

Describe a tool

Run a tool

Errors

Pricing

​The data tool object

​Search tools

​Describe a tool

​Run a tool

​Errors

​Pricing

The data tool object

Search tools

Describe a tool

Run a tool

Errors

Pricing