> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waterfall.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Usage Tracking
> Every Waterfall API response includes an output.usage object for real-time cost tracking and balance visibility.
Every response includes an `output.usage` object alongside the enrichment payload. No separate API call needed. Cost and balance data is always present.
Usage data is returned inside `output`, at the same level as the enrichment, prospector, search, or verification results.
```json theme={null}
{
"output": {
"person": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.1,
"persons_usd": 0.0,
"phones_count": 1,
"companies_usd": 0.0,
"persons_count": 0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
## Fields
| Field | Description |
| ---------------------------------------------------- | --------------------------------------------------------------- |
| `total_usd` | Total cost of the API call |
| `persons_usd` / `phones_usd` / `companies_usd` | Cost split by enrichment type |
| `persons_count` / `phones_count` / `companies_count` | Records returned per enrichment type |
| `balance_remaining_usd` | Remaining account balance, or amount due on pay-as-you-go plans |
More than one `*_usd` field can be non-zero in the same request. For example, if you run a Contact Enrichment with `include_phones: true` and we return both a contact record and a phone number, you'll see charges under both `persons_usd` and `phones_usd`.
## Cost mapping
| Category | Endpoints |
| ----------- | ------------------------------------------------------------------------------- |
| `persons` | Contact Enrichment, Prospector, Search Contact |
| `phones` | Phone Enrichment, or any Contact/Prospector request with `include_phones: true` |
| `companies` | Company Enrichment, Company Reveal, Search Company |
Usage is calculated using your currently configured rates. If your pricing changed recently, updated rates may not appear until any existing prepaid balance has been fully consumed.
## Agentic and automated pipelines
`balance_remaining_usd` is returned on every call, making it straightforward to build cost-aware automation without polling the Account API.
Common patterns:
* **Budget enforcement**: halt a loop or batch job when balance drops below a threshold
* **Top-up triggers**: fire an alert or webhook when balance crosses a floor
* **Per-run cost tracking**: sum `total_usd` across calls to measure spend per job or workflow
* **Self-regulating agents**: let an LLM-orchestrated pipeline decide whether to continue enriching based on remaining balance
```python theme={null}
response = waterfall.enrich_contact(...)
remaining = response["output"]["usage"]["balance_remaining_usd"]
if remaining < 10.00:
trigger_top_up_alert()
```
The cost data is already in the response. No extra round-trip needed.
## Examples by endpoint
[Contact Enrichment Launcher](/v1/contact-enrichment-launcher)
```json theme={null}
{
"output": {
"person": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.1,
"persons_count": 1,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Phone Enrichment Launcher](/v1/phone-enrichment-launcher)
```json theme={null}
{
"output": {
"person": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.1,
"phones_count": 1,
"persons_usd": 0.0,
"persons_count": 0,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Prospector Launcher](/v1/prospector-launcher)
```json theme={null}
{
"output": {
"persons": [],
"usage": {
"total_usd": 0.5,
"phones_usd": 0.1,
"phones_count": 1,
"persons_usd": 0.4,
"persons_count": 4,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Search Contact Launcher](/v1/search-contact-launcher)
```json theme={null}
{
"output": {
"persons": [],
"usage": {
"total_usd": 0.75,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.75,
"persons_count": 15,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Search Company Launcher](/v1/search-company-launcher)
```json theme={null}
{
"output": {
"companies": [],
"usage": {
"total_usd": 0.75,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.0,
"persons_count": 0,
"companies_usd": 0.75,
"companies_count": 15,
"balance_remaining_usd": 717.486
}
}
}
```
[Email Verifier](/v1/email-verifier)
```json theme={null}
{
"output": {
"email": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.1,
"persons_count": 1,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Job Change Launcher](/v1/job-change-launcher)
```json theme={null}
{
"output": {
"job_change_status": "moved",
"person": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.1,
"persons_count": 1,
"companies_usd": 0.0,
"companies_count": 0,
"balance_remaining_usd": 717.486
}
}
}
```
[Company Reveal Launcher](/v1/company-reveal-launcher)
```json theme={null}
{
"output": {
"company": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.0,
"persons_count": 0,
"companies_usd": 0.1,
"companies_count": 1,
"balance_remaining_usd": 717.486
}
}
}
```
[Company Enrichment Launcher](/v1/company-enrichment-launcher)
```json theme={null}
{
"output": {
"company": { ... },
"usage": {
"total_usd": 0.1,
"phones_usd": 0.0,
"phones_count": 0,
"persons_usd": 0.0,
"persons_count": 0,
"companies_usd": 0.1,
"companies_count": 1,
"balance_remaining_usd": 717.486
}
}
}
```