Skip to main content
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

FieldDescription
total_usdTotal cost of the API call
persons_usd / phones_usd / companies_usdCost split by enrichment type
persons_count / phones_count / companies_countRecords returned per enrichment type
balance_remaining_usdRemaining 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

CategoryEndpoints
personsContact Enrichment, Prospector, Search Contact
phonesPhone Enrichment, or any Contact/Prospector request with include_phones: true
companiesCompany 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 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 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 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 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 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 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 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 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 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
    }
  }
}