> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revenuebase.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Which endpoint should I use?

> Choose how to check an audience or retrieve its contact records.

Use the **same filter** to define an audience. Choose the endpoint based on
what you want back: numbers, a masked sample, analysis, inline records, or a
downloadable file.

## One audience, five operations

Count, View, and Insights are free on every plan. Preview and Start Export
use credits on Pay-as-you-go (PAYG). All-you-can-eat (AYCE) includes unlimited
contact retrieval at 0 credits, within the per-call limits shown below.

```mermaid theme={null}
%%{init: {'flowchart': {'htmlLabels': false, 'nodeSpacing': 20, 'padding': 12}}}%%
flowchart LR
  audience["Contact audience filter"] --> count["`Count: audience size
Free (0 credits)`"]
  audience --> view["`View: masked sample
Free (0 credits)`"]
  audience --> insights["`Insights: audience analysis
Free (0 credits)`"]
  audience --> preview["`Preview
Rows returned now (JSON)
Up to 50,000 rows
PAYG: uses credits
AYCE: included`"]
  audience --> export["`Start Export
Job ID, then file download
Up to 1,000,000 rows
PAYG: uses credits
AYCE: included`"]
  classDef free fill:#173b2b,stroke:#4fbf84,color:#e4f8eb
  classDef paid fill:#3d2e13,stroke:#e5ae46,color:#ffebb5
  class count,view,insights free
  class preview,export paid
```

These are independent calls. You can run Insights before View, or go directly
to Preview when you already know what you need.

| Endpoint | Question it answers | What you get | Credits |
| - | - | - | - |
| [Count](/api-reference/count) | How large is this audience? | Matching contact total, distinct-company count, and email/mobile availability counts. No individual records. | 0 |
| [View](/api-reference/view) | Are these the people I meant? | Up to 100 contact rows. Names, roles, and company fields; email/mobile appear as availability booleans. | 0 |
| [Preview](/api-reference/preview) | Can I retrieve these records now? | Up to 50,000 contact rows inline, with the fields you request and the email/mobile details you choose to reveal. | Metered on PAYG; included on AYCE |
| [Insights](/api-reference/insights) | What is the audience's composition and data coverage? | Aggregate reachability, freshness, coverage, or field fill rates. No individual contact records. | 0 |
| [Start Export](/api-reference/start-export) | Can I download a larger list as a file? | An `exportId` for an asynchronous job. Poll its status, then download the completed file of up to 1,000,000 rows. | Metered on PAYG; included on AYCE |

Count's contact `total` is exact. Its other counts are estimates in default
`fast` mode; check `exact` or request `mode: "exact"` for precise figures.
View has a 100,000-row daily sample allowance per API key, resetting at UTC
midnight. See [limits](/api-reference/v2/contact-api-overview#what-you-get-back).

## View checks relevance; Preview retrieves records

**View** is a free relevance check. A row can show a person's name, role,
company, and whether contact details are available. It replaces email and
mobile values with `hasEmail` and `hasMobile` booleans.

**Preview** retrieves contact records in the response. Set `columns` to
choose the returned fields, `limit` to cap the rows, and `reveal` to choose
email, mobile, both, or neither. It is charged on PAYG even when you request
only profile and company fields. AYCE includes contact retrieval at 0 credits.

<Note>
  Omitting `reveal` selects both email and mobile. Set it explicitly to
  control cost; choosing fewer `columns` does not remove reveal charges.
  See [credits and plans](/api-reference/v2/credits).
</Note>

View and Preview return samples with no pagination. A smaller `limit` changes
how many rows you retrieve, not the audience defined by your filter.

## Preview returns rows; Start Export starts a file job

**Preview** returns the contact rows directly in its API response. Use it
when your application needs an immediate batch, capped by `limit` at up to
50,000 rows.

**Start Export** returns a job ID, rather than contact rows or a finished file.
Use it for a file of up to 1,000,000 rows, with `maxRows` as your row cap.
Poll the export status and download the file once the job succeeds.

Both use the same [PAYG credit rates](/api-reference/v2/credits#compare-retrieval-prices).
Preview reserves credits before returning rows and settles the actual charge
with the response. Start Export holds credits while the job runs and settles
the actual charge when it completes.
AYCE includes both at 0 credits. Use the free
[Estimate](/api-reference/estimate-export) before starting a metered export.

## Count measures size; Insights describes the audience

Count gives you headline numbers. Insights lets you choose one analysis
section per call:

| Insights section | Use it to ask |
| - | - |
| `reachability` | How many matching contact rows have email, mobile, or both? |
| `freshness` | How recently were emails verified and records updated? |
| `coverage` | How is the audience distributed across a field, such as seniority or company industry? |
| `fillRate` | How often are the fields I need populated? |

Insights evaluates the **filtered audience**, rather than the rows in a View
or Preview sample. Grouped outputs can summarize smaller categories as
`Other`; they are summaries, not record downloads.

## A practical sequence

Suppose you want VPs at US-headquartered software companies.

1. **Count** to check audience size.
2. **View** to inspect names, roles, and companies without spending credits.
3. **Insights** to check email availability and industry distribution if needed.
4. **Preview** for an immediate batch, or **Estimate** followed by **Start Export** for a file.

Reuse the same filter throughout. Company search fields work directly on
contact endpoints, so you can combine company criteria with job or person
criteria in one request. Available company fields on a contact row require
no second company lookup or separate company-row charge.

## The company equivalents

[Company Search](/api-reference/v2/company-search-overview) returns the
company part of the same data, deduplicated to one search result per `RBID_ORG`.

| Contact operation | Company operation | What changes |
| - | - | - |
| `/count` | `/company/count` | Counts companies, with aggregated contact totals. Company counts are exact; person/job filters select companies represented by matching contacts. |
| `/view` | No `/company/view` endpoint | Use Company Preview for company rows. It costs 0 credits and has no person email/mobile to mask. |
| `/preview` | `/company/preview` | One row per company, with company fields and contact totals. Up to 50,000 rows; 0 credits. |
| `/insights` | `/company/insights` | Company `coverage` and `fillRate`; contact `reachability` and `freshness` sections are unavailable here. |
| `/enrich` | `/company/enrich` | Known company domains, LinkedIn URLs, and RBIDs; 10,000 combined identifiers. PAYG charges 1 per returned match; AYCE includes unlimited company retrieval. |
| `/exports/estimate` | `/company/exports/estimate` | Free forecast for company rows and SmartSearch charges; creates no job or hold. |
| `/exports` | `/company/exports` | Starts an asynchronous file job with company rows. Metered on PAYG; included on AYCE. |

All paths above use the base URL `https://api.revenuebase.ai/v2/contact`.
Company Preview and Insights require company filters. Company Count and
Estimate and Export can also apply person/job conditions and select the distinct companies
of the matching contacts. Their company contact totals still describe all
contacts at each selected company. Check the
[column catalogs](/api-reference/v2/company-search-overview#browse-company-fields)
for fields supported on each surface.


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