Account Reporter v2 - Waterfall.io API Documentation

Account Reporter V2

curl --request GET \
  --url https://api.waterfall.io/v2/account \
  --header 'x-api-key: <api-key>'

{
  "key_usage": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "prospector_requests": 123,
    "prospector_persons": 123,
    "prospector_persons_phones": 123,
    "enrichment_contact_requests": 123,
    "enrichment_contact_persons": 123,
    "enrichment_contact_persons_phones": 123,
    "enrichment_phone_requests": 123,
    "enrichment_phone_phones": 123,
    "enrichment_company_requests": 123,
    "enrichment_company_companies": 123,
    "search_contact_requests": 123,
    "search_contact_found": 123,
    "search_company_requests": 123,
    "search_company_found": 123,
    "company_reveal_requests": 123,
    "company_reveal_found": 123,
    "job_change_requests": 123,
    "job_change_found": 123,
    "verify_email_requests": 123,
    "verify_email_verified": 123
  },
  "account_usage": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "prospector_requests": 123,
    "prospector_persons": 123,
    "prospector_persons_phones": 123,
    "enrichment_contact_requests": 123,
    "enrichment_contact_persons": 123,
    "enrichment_contact_persons_phones": 123,
    "enrichment_phone_requests": 123,
    "enrichment_phone_phones": 123,
    "enrichment_company_requests": 123,
    "enrichment_company_companies": 123,
    "search_contact_requests": 123,
    "search_contact_found": 123,
    "search_company_requests": 123,
    "search_company_found": 123,
    "company_reveal_requests": 123,
    "company_reveal_found": 123,
    "job_change_requests": 123,
    "job_change_found": 123,
    "verify_email_requests": 123,
    "verify_email_verified": 123
  },
  "balance_remaining_usd": 123
}

GET

account

Account Reporter V2

curl --request GET \
  --url https://api.waterfall.io/v2/account \
  --header 'x-api-key: <api-key>'

{
  "key_usage": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "prospector_requests": 123,
    "prospector_persons": 123,
    "prospector_persons_phones": 123,
    "enrichment_contact_requests": 123,
    "enrichment_contact_persons": 123,
    "enrichment_contact_persons_phones": 123,
    "enrichment_phone_requests": 123,
    "enrichment_phone_phones": 123,
    "enrichment_company_requests": 123,
    "enrichment_company_companies": 123,
    "search_contact_requests": 123,
    "search_contact_found": 123,
    "search_company_requests": 123,
    "search_company_found": 123,
    "company_reveal_requests": 123,
    "company_reveal_found": 123,
    "job_change_requests": 123,
    "job_change_found": 123,
    "verify_email_requests": 123,
    "verify_email_verified": 123
  },
  "account_usage": {
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "prospector_requests": 123,
    "prospector_persons": 123,
    "prospector_persons_phones": 123,
    "enrichment_contact_requests": 123,
    "enrichment_contact_persons": 123,
    "enrichment_contact_persons_phones": 123,
    "enrichment_phone_requests": 123,
    "enrichment_phone_phones": 123,
    "enrichment_company_requests": 123,
    "enrichment_company_companies": 123,
    "search_contact_requests": 123,
    "search_contact_found": 123,
    "search_company_requests": 123,
    "search_company_found": 123,
    "company_reveal_requests": 123,
    "company_reveal_found": 123,
    "job_change_requests": 123,
    "job_change_found": 123,
    "verify_email_requests": 123,
    "verify_email_verified": 123
  },
  "balance_remaining_usd": 123
}

This call is free — it does not consume credits or count against your rate limit.

What this endpoint does

Returns usage counters and remaining balance for both the authenticated API key (key_usage) and the entire account (account_usage). The two objects are identical if you only have one key. If you have multiple keys, account_usage reflects the sum across all keys.

Query parameter

Pass month in YYYY-MM format to get usage for a specific month. If omitted, returns the current month.

GET /v2/account?month=2024-10

Usage fields

Both key_usage and account_usage return the same set of counters:

Field	Description
`prospector_requests`	Number of Prospector Launcher jobs submitted
`prospector_persons`	Number of contacts returned by Prospector
`prospector_persons_phones`	Phone numbers returned via Prospector phone enrichment
`enrichment_contact_requests`	Contact Enrichment Launcher jobs submitted
`enrichment_contact_persons`	Contacts successfully enriched
`enrichment_contact_persons_phones`	Phone numbers returned via Contact Enrichment
`enrichment_phone_requests`	Phone Enrichment Launcher jobs submitted
`enrichment_phone_phones`	Phone numbers successfully returned
`enrichment_company_requests`	Company Enrichment Launcher jobs submitted
`enrichment_company_companies`	Companies successfully enriched
`search_contact_requests`	Search Contact Launcher jobs submitted
`search_contact_found`	Contacts returned by Search Contact
`verify_email_requests`	Email Verifier calls made
`verify_email_verified`	Emails that returned a definitive status (`valid`, `invalid`, `risky`)
`balance_remaining_usd`	Remaining account balance in USD

Authorizations

x-api-key

string

header

required

To access the API, provide your API key in x-api-key.

Query Parameters

month

string

Optional month in YYYY-MM format used to scope usage counters.

Required string length: 7

Pattern: ^\d{4}-\d{2}$

Response

Success. You can check usage.

Account reporter response containing key-level and account-level usage metrics.

key_usage

object

Usage counters for a given time window.

Show child attributes

account_usage

object

Usage counters for a given time window.

Show child attributes

balance_remaining_usd

number<float>

Example:

23.34

Email Verifier

API Keys Management

​What this endpoint does

​Query parameter

​Usage fields

Authorizations

Query Parameters

Response

What this endpoint does

Query parameter

Usage fields