URL: /capabilities/data · Id: `page:/capabilities/data`

# Data: every reading names when, how and what it cost

> Every reading your agents take of the market, with where it came from, when, and what it cost.

Every reading your agents take of the market, with where it came from, when, and what it cost.

- **Deepens:** [`noun:dataset`](https://startupbuilder.dev/business/nouns/dataset), [`product-template:dataset-api`](https://startupbuilder.dev/products/templates/dataset-api), [`capability:market-data`](https://startupbuilder.dev/systems/marketing/market-data), [`capability:enrichment`](https://startupbuilder.dev/systems/sales/enrichment)
- **Calls:** [25](/code/data)
- **Events:** [One per call](/code/events)
- **First call:** [`Organization.count`](/code/data/organizations/count)

```text title="Run it · Ask"
How many US property managers with 20 to 200 staff are there? Spend nothing.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Organization.count({ where: { industries: ['property management'], headcount: { min: 20, max: 200 }, countries: ['US'] }, maxCost: 0 })
```

```json title="Run it · Response"
{
  "count": 4180,
  "ignored": [],
  "observedAt": "2026-10-27T14:02:11Z",
  "method": "estimated"
}
```

The reference for every call on this page is [the Data API](/code/data).

## Every reading names when, how and what it cost
Data is what your agents read about the market: companies, people, search terms, AI answers, links, rivals' ads and posts. Every reading comes back in one envelope, whichever [Source](https://startupbuilder.dev/business/nouns/source) answered.

`observedAt` says when the market was read, not when the row was written. `method` says how: `sampled` is a live read, `estimated` is modeled from an index, and `reported` comes from [your own account](/code/integrations).

`null` means unknown, never zero. A long-tail term with no measured volume reads `searches: null`. Every call emits one [Event](https://startupbuilder.dev/business/nouns/event), so a [Trigger](https://startupbuilder.dev/business/nouns/trigger) can fire on it unchanged.

```ts
type Observed = {
  observedAt: string                           // when the market was read
  method: 'sampled' | 'estimated' | 'reported'
  venue?: string                               // 'google-search', 'chatgpt', 'reddit'
  locale?: string                              // 'en-US'
}
type Cost = { usd: number; maxUsd: number; units: number; misses: number }
```

[Types](/code/data/types) lists every shared field and what its `null` means.

Verified means two checks, both on the record. The address is at the right company: its domain is the account's own domain, after redirects, so an address at a former employer or a parent company never counts. And the mailbox checks deliverable. An address that fails the first check is found again from the person's current profile, never sent to.

## Your agents read search, outreach, social and ads
Each row is a question a founder asks, and the calls that answer it. Every call is one abstract API under one name, whichever source sits behind it.

The readings cover the whole funnel. [Rankings](/code/data/keywords/search) and [AI answers](/code/data/keywords/ask) feed search, [people](/code/data/people) feed outreach, [posts and creators](/code/data/people/find) feed social, and [rivals' ads](/code/data/ads/find) feed paid.

| What | Calls | What comes back | Reference |
| --- | --- | --- | --- |
| Companies that fit | [`Organization.count`](/code/data/organizations/count), [`Organization.find`](/code/data/organizations/find), [`Organization.enrich`](/code/data/organizations/enrich) | A free count, then rows with fit and the quoted evidence, then headcount, funding, technology and hiring | [Organizations](/code/data/organizations) |
| People and work emails | [`Prospect.find`](/code/data/people/find), [`ContactPoint.findEmail`](/code/data/people/find-email), [`ContactPoint.verifyEmail`](/code/data/people/verify-email) | Names and titles at the companies you approved, then a verified work email: at the account’s own domain, and checked deliverable | [People](/code/data/people) |
| Search demand | [`Keyword.find`](/code/data/keywords/find), [`Keyword.measure`](/code/data/keywords/measure), [`Keyword.forecast`](/code/data/keywords/forecast) | Ideas, then volume, cost per click, difficulty from 0 to 100, intent and trend, then what ads on a term cost | [Keywords](/code/data/keywords) |
| Rankings | [`Keyword.search`](/code/data/keywords/search) | The top results on Google Search or Bing, your own position, and the questions people also ask | [Keywords](/code/data/keywords) |
| AI answers | [`Keyword.ask`](/code/data/keywords/ask) | The answer on ChatGPT, Gemini, Perplexity, Claude or Google AI Overviews, the brands it names and the pages it cites | [Keywords](/code/data/keywords) |
| Links and authority | [`Domain.benchmark`](/code/data/domains/benchmark), [`Domain.findLinks`](/code/data/domains/find-links), [`Domain.findCompetitors`](/code/data/domains/find-competitors) | Authority beside your rivals, the sites that link to them and not to you, and who competes for your terms | [Domains](/code/data/domains) |
| Index state and page health | [`Domain.verify`](/code/data/domains/verify), [`Page.audit`](/code/data/pages-and-sites/audit-page), [`Site.audit`](/code/data/pages-and-sites/audit-site) | Which key pages Google Search and Bing hold, and what a page or a whole site gets wrong | [Pages and sites](/code/data/pages-and-sites) |
| Rivals’ ads | [`Ad.find`](/code/data/ads/find) | Ads running on Facebook, Instagram, Google Search, LinkedIn and TikTok, with first and last seen | [Ads](/code/data/ads) |
| Posts and creators | [`Keyword.search`](/code/data/keywords/search), [`Prospect.find`](/code/data/people/find) | Problem posts on Reddit, X and Hacker News, creators by audience, and the people who engaged with a LinkedIn post | [People](/code/data/people) |
| Buying triggers | [`Monitor.create`](/code/data/monitors/create), [`Monitor.check`](/code/data/monitors/check) | A dated Event when a company raises, hires for a role or loses a buyer, and when a rank or an answer moves | [Monitors](/code/data/monitors) |

## Count free, then pay only for results
Counting is free. [`Organization.count`](/code/data/organizations/count) and [`Prospect.count`](/code/data/people/count) cost nothing, and every find takes the same filters, so you size a market before you buy one row.

You pay per unit returned, never per row requested. A lookup that finds nothing is free wherever the route allows, and a check that ends catch-all or unknown costs nothing.

`maxCost` caps every call. A call that would cross it is [refused](/code/refusals#max-cost) before anything is spent, or it stops early with `complete: false`. Reads through your own [Search Console](/code/integrations/google-search-console) or [ad account](/code/integrations/google-ads) cost $0 and say `method: 'reported'`.

## Market readings are shared; people readings are not
Pass `maxAge`, and a stored reading younger than it comes back at no charge. Volume, difficulty, results pages and authority are shared across every [startup](https://startupbuilder.dev/business/nouns/startup) that reads the same subject and locale.

Readings about people are never shared. Each startup pays for its own [prospect](https://startupbuilder.dev/business/nouns/prospect) rows, and every [Suppression](https://startupbuilder.dev/business/nouns/suppression) is read before a lookup on a person.

## When a source fails, the call does not
Each call has ranked [Mappings](https://startupbuilder.dev/business/nouns/mapping), one per [Source](https://startupbuilder.dev/business/nouns/source). On a 429, a 5xx or a timeout, the platform tries the next route and reports `route: { tried: 2 }`. No source name ever appears in a response.

A 4xx is never retried elsewhere, because it means the input is wrong. When every route is out of capacity, the call refuses with [`sources-busy`](/code/refusals#sources-busy) and spends nothing.

A filter a route cannot apply is listed in `ignored`, never dropped. Pass `strict: true` to be refused instead. [Filter coverage](/code/data/types#filter-coverage) gives the measured rate for each filter.

## A first pass reads companies, people and search
Free counts come first, then the rows, the checks and the readings, each at its own [price](/code/data#calls).

| Step | Call | Cost |
| --- | --- | --- |
| How many property managers fit | [`Organization.count`](/code/data/organizations/count) | Free |
| 100 that fit a sentence, with the evidence quoted | [`Organization.find`](/code/data/organizations/find) | About 20¢ |
| The person to write to at each | [`Prospect.find`](/code/data/people/find) | About 5¢ |
| 100 work emails found at the right company | [`ContactPoint.findEmail`](/code/data/people/find-email) | About 45¢ |
| Each one checked deliverable | [`ContactPoint.verifyEmail`](/code/data/people/verify-email) | About 18¢ |
| 500 search terms measured | [`Keyword.measure`](/code/data/keywords/measure) | About 90¢ |
| 30 results pages read | [`Keyword.search`](/code/data/keywords/search) | About 0.9¢ |
| 20 buying questions on 4 answer engines | [`Keyword.ask`](/code/data/keywords/ask) | About 32¢ |
| The 550 sites that link to 3 rivals, compared with yours | [`Domain.findLinks`](/code/data/domains/find-links) | About 11¢ |
| **In all** | None. | **About $2.22** |

## Watch a reading, and act when it changes
A [Monitor](https://startupbuilder.dev/business/nouns/monitor) re-runs a Data call on a schedule and records an Event only on the change you name. The changes are a rank move, a new answer citation, a funding round, a hiring post, a lost link and a new rival ad.

A [Workflow](https://startupbuilder.dev/business/nouns/workflow) can start on that Event. Scheduling is free, and each run costs what its call costs.

```ts
await $.try.Monitor.create({ verb: 'Keyword.ask', input: { keyword: 'rent ledger template' }, change: 'answer-citation', every: '1w' })
```