> ## 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
> Read data across 18 domains — social media, people, companies, funding, markets, SEO, news, law, weather, jobs, property, reviews, trade, shopping and travel — from an agent, the dashboard, the API, the SDK or the CLI. Priced per run.
Data is one catalogue of **read-only** data tools: about 1,900 endpoints from 51 sources, grouped into 18 domains, and growing on its own. An agent asks a question in plain words and gets JSON back; a developer calls the same catalogue without an agent.
Every surface does the same three things:
1. **Search** the catalogue with a short phrase — `"company funding rounds"`, `"homes for sale"` — optionally in one domain. Free.
2. **Describe** a tool to read its input schema (`path`, `query` and `body` parameters), its price and its notes. Free.
3. **Run** it with those parameters and get the data back as JSON. Priced per run.
[Social data](/docs/capabilities/social-data) is this catalogue's `social` domain, under its own names.
## Domains
| Domain | What it covers | An example question |
| - | - | - |
| `social` | Public posts, profiles, comments, followers, hashtags and trends on about 21 networks | *What are the top comments on @nasa's latest Instagram post?* |
| `search` | Web, maps, shopping, image, video and app-store results | *Which coffee shops near Union Square have the best ratings?* |
| `people` | Person and company enrichment | *Who is the head of sales at Acme, and since when?* |
| `companies` | Company profiles, enrichment and company news | *How many employees does Acme have, and what did it announce this month?* |
| `compliance` | KYB, sanctions and company registries | *Is this supplier on a sanctions list?* |
| `funding` | Funding rounds and investors | *Who led Acme's last round, and how much was it?* |
| `seo` | Backlinks, keywords and AI-answer visibility | *Which sites link to our pricing page?* |
| `finance` | Quotes, earnings, analyst ratings and insider trades | *What did insiders buy or sell at Acme this quarter?* |
| `crypto` | TVL, token prices, yields and prediction markets | *What is the TVL of the largest lending protocols?* |
| `news` | News articles | *What was written about Acme this week?* |
| `legal` | The US Code and the Code of Federal Regulations | *What does 15 U.S.C. § 45 say?* |
| `weather` | Current conditions and forecasts | *Will it rain in Lisbon on Saturday?* |
| `jobs` | Job postings and pay | *Which companies are hiring Rust engineers in Berlin, and at what pay?* |
| `real_estate` | Property listings and values | *Which real-estate listings in Austin are under \$500k?* |
| `reviews` | Software and company reviews | *What do software reviews say users complain about in Acme's product?* |
| `trade` | Customs shipment records | *Who imports Acme's products into the US?* |
| `shopping` | Retail product listings | *What does this blender sell for across retailers?* |
| `travel` | Hotels and flights | *What are the cheapest flights from SFO to JFK next Friday?* |
Every tool only reads. Nothing in the catalogue posts, sends, buys or changes anything. Use Data for lawful purposes only, and respect privacy laws and each source's terms — especially for data about people.
## From an agent
Every agent has three built-in [tools](/docs/capabilities/tools): `data_search`, `data_describe` and `data_run`. `data_search` takes a `query`, and optionally a `domain`, a social `platform` and a `limit`; `data_describe` returns a tool's input schema; `data_run` runs it with `path`, `query` and `body` parameters. Search and describe are free and read-only, so they stay available in [plan mode](/docs/concepts/policies). A run is a priced call and asks first by default: you approve each one, or grant the rest of the chat at once. Set `data_run` to `allow` in the agent's [tool policy](/docs/capabilities/tools#permission-policies) to let it run unattended. The [social data](/docs/capabilities/social-data) names are on the API, SDK and CLI only; an agent reaches social tools with `data_search` and `domain: "social"`.
## From the dashboard
**Settings → Data** is the catalogue in the browser: pick a domain, search, open a tool to see what it takes and what it costs, fill in its parameters, run it, and read the data and the cost.
## From code
```bash CLI theme={"system"}
vetta data search "company funding rounds" --domain funding
vetta data describe
vetta data run --query company=acme.com
```
```ts SDK theme={"system"}
const { data: tools } = await client.data.searchTools({ query: "company funding rounds", domain: "funding" });
const tool = await client.data.getTool(tools[0].id); // tool.input says what to send
const run = await client.data.run({ tool_id: tool.id, query: { company: "acme.com" } });
console.log(run.status, run.data, run.cost_micro_usd);
```
```bash cURL theme={"system"}
curl -fsSL "https://api.vetta.sh/v1/data/tools?query=company%20funding%20rounds&domain=funding" \
-H "authorization: Bearer sk_live_..."
curl -fsSL https://api.vetta.sh/v1/data/runs \
-H "authorization: Bearer sk_live_..." -H "content-type: application/json" \
-d '{ "tool_id": "", "query": { "company": "acme.com" } }'
```
Parameter names differ by tool; `describe` says which ones a tool takes. The full contract is in the [API reference](/docs/api/data), the [SDK](/docs/sdk/data) and the [CLI](/docs/cli/data) pages.
## What it costs
Searching and describing are free. A run costs the price the tool lists — `price.text` on every tool, already the price you pay. Most tools are priced per call: the median is about `$0.002`, seven in ten cost `$0.013` or less, and the most expensive is about `$1.24`. Some are priced per result (a search that returns 20 records costs 20 results), and a few vary with the input (they say `up to …`). A run priced per result returns **at most 25 results**: any result-count field you send above 25 (`limit`, `maxResults`, `resultsPerPage`, `pageSize` and the like, at any depth) is lowered to 25, and a list input with more than 25 items (for example 30 usernames, where each one is a result) is refused with `validation_failed`. Runs are booked from prepaid credits on the `search` component of your [spend](/docs/platform/pricing#priced-tools), once per run.
A run is **admitted before anything is bought**:
Each run is capped at 25 results. Some sources bill per-result tools in blocks of 10, so a 25-result run can cost 30 results' worth; admission covers that.
* **API, SDK, CLI and dashboard**: the prepaid balance must cover the run's most it can cost — the listed price of one call, or of 30 results (plus any per-call fee) for a per-result tool; otherwise the run is refused with `402 insufficient_credits` and nothing runs.
* **Agents**: a run takes a hold against the session's budget first — the listed price for a per-call tool, up to 30 results' worth for a per-result one. The hold is settled at the real cost when the run ends.
A run that fails — the source refused the input, the record does not exist, the source was down — is normally **not charged** and writes no ledger entry. A run that takes longer than two minutes is stopped; it is normally not charged either, except that a tool priced per result costs what it gathered before the stop.
## Limits
* **On demand, not a stream.** Each run reads once; to watch a price, a listing or a company over time, run it on a schedule with a [deployment](/docs/capabilities/deployments).
* **No logins, read-only.** Nothing behind a login, and nothing written anywhere.
* **Up to two minutes and 25 results per run.** Ask for fewer results (most tools take a limit or count parameter; start with 5–10).
* **Results are the source's own data**, passed through unchanged, so field names differ between tools.
## Check that it works
From the CLI, in this order. The first three cost nothing.
1. **The catalogue is reachable.** `vetta data search "funding rounds" --domain funding` lists tools with prices, each with `funding` in `domains`. A `501 feature_not_configured` means data is not enabled on the deployment you are calling.
2. **A tool describes itself.** `vetta data describe ` prints its `input` schema — the parameters under `path`, `query` and `body`.
3. **A refused run is free.** `vetta data run ` with no parameters answers `status: "failed"` with `cost_micro_usd: 0` (or a `400` before anything runs).
4. **A real run returns data and its cost.** `vetta data run --query =`, with the parameters `describe` named, answers `status: "succeeded"`, the data in `data`, and `cost_micro_usd` equal to the tool's `price.micro_usd` for a per-call tool.
5. **It was billed once.** `vetta credits ledger --limit 5` shows one `search` debit for step 4 and no entry at all for steps 1–3.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.