Skip to main content
GET
/
v2
/
account
Account Reporter V2
curl --request GET \
  --url https://api.waterfall.io/v2/account \
  --header 'x-api-key: <api-key>'
{
  "key_usage": {
    "start_date": "2024-10-01",
    "end_date": "2024-11-01",
    "prospector_requests": 10,
    "prospector_persons": 17,
    "prospector_persons_phones": 2,
    "enrichment_contact_requests": 4827,
    "enrichment_contact_persons": 2873,
    "enrichment_contact_persons_phones": 85,
    "enrichment_phone_requests": 2590,
    "enrichment_phone_phones": 2279,
    "enrichment_company_requests": 15,
    "enrichment_company_companies": 15,
    "search_contact_requests": 0,
    "search_contact_found": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0
  },
  "account_usage": {
    "start_date": "2024-10-01",
    "end_date": "2024-11-01",
    "prospector_requests": 10,
    "prospector_persons": 17,
    "prospector_persons_phones": 2,
    "enrichment_contact_requests": 4827,
    "enrichment_contact_persons": 2873,
    "enrichment_contact_persons_phones": 85,
    "enrichment_phone_requests": 2590,
    "enrichment_phone_phones": 2279,
    "enrichment_company_requests": 15,
    "enrichment_company_companies": 15,
    "search_contact_requests": 0,
    "search_contact_found": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0
  },
  "balance_remaining_usd": 23.34
}
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:
FieldDescription
prospector_requestsNumber of Prospector Launcher jobs submitted
prospector_personsNumber of contacts returned by Prospector
prospector_persons_phonesPhone numbers returned via Prospector phone enrichment
enrichment_contact_requestsContact Enrichment Launcher jobs submitted
enrichment_contact_personsContacts successfully enriched
enrichment_contact_persons_phonesPhone numbers returned via Contact Enrichment
enrichment_phone_requestsPhone Enrichment Launcher jobs submitted
enrichment_phone_phonesPhone numbers successfully returned
enrichment_company_requestsCompany Enrichment Launcher jobs submitted
enrichment_company_companiesCompanies successfully enriched
search_contact_requestsSearch Contact Launcher jobs submitted
search_contact_foundContacts returned by Search Contact
verify_email_requestsEmail Verifier calls made
verify_email_verifiedEmails that returned a definitive status (valid, invalid, risky)
balance_remaining_usdRemaining 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.

​
account_usage
object

Usage counters for a given time window.

​
balance_remaining_usd
number<float>
Example:

23.34