Usage Tracking

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.

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

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

Contact Enrichment Launcher

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

Phone Enrichment Launcher

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

Prospector Launcher

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

Search Contact Launcher

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

Search Company Launcher

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

Email Verifier

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

Job Change Launcher

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

Company Reveal Launcher

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

Company Enrichment Launcher

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

General guidance

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

Fields

Cost mapping

Agentic and automated pipelines

Examples by endpoint

​Fields

​Cost mapping

​Agentic and automated pipelines

​Examples by endpoint

Fields

Cost mapping

Agentic and automated pipelines

Examples by endpoint