Account Reporter v2

Account Reporter V2

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v2/account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v2/account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v2/account"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v2/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "key_usage": {
    "start_date": "2024-02-01",
    "end_date": "2024-03-01",
    "prospector_requests": 1,
    "prospector_persons": 0,
    "prospector_persons_phones": 0,
    "enrichment_contact_requests": 0,
    "enrichment_contact_persons": 0,
    "enrichment_contact_persons_phones": 0,
    "enrichment_phone_requests": 0,
    "enrichment_phone_phones": 0,
    "enrichment_company_requests": 0,
    "enrichment_company_companies": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0,
    "search_contact_requests": 1,
    "search_contact_found": 0
  },
  "account_usage": {
    "start_date": "2024-02-01",
    "end_date": "2024-03-01",
    "prospector_requests": 2,
    "prospector_persons": 0,
    "prospector_persons_phones": 0,
    "enrichment_contact_requests": 0,
    "enrichment_contact_persons": 0,
    "enrichment_contact_persons_phones": 0,
    "enrichment_phone_requests": 0,
    "enrichment_phone_phones": 0,
    "enrichment_company_requests": 0,
    "enrichment_company_companies": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0,
    "search_contact_requests": 2,
    "search_contact_found": 0
  },
  "balance_remaining_usd": 99.9,
  "price": {
    "prospector_persons": 0.138,
    "prospector_persons_phones": 0.32,
    "enrichment_contact_persons": 0.138,
    "enrichment_contact_persons_phones": 0.32,
    "enrichment_phone_phones": 0.32,
    "enrichment_company_companies": 0.138,
    "search_contact_found": 0.04,
    "search_company_found": 0.04,
    "company_reveal_found": 0.05,
    "company_titles_found": 0,
    "job_change_found": 0.1,
    "verify_email_verified": 0.02
  }
}

GET

account

Account Reporter V2

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.waterfall.io/v2/account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.waterfall.io/v2/account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.waterfall.io/v2/account"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.waterfall.io/v2/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "key_usage": {
    "start_date": "2024-02-01",
    "end_date": "2024-03-01",
    "prospector_requests": 1,
    "prospector_persons": 0,
    "prospector_persons_phones": 0,
    "enrichment_contact_requests": 0,
    "enrichment_contact_persons": 0,
    "enrichment_contact_persons_phones": 0,
    "enrichment_phone_requests": 0,
    "enrichment_phone_phones": 0,
    "enrichment_company_requests": 0,
    "enrichment_company_companies": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0,
    "search_contact_requests": 1,
    "search_contact_found": 0
  },
  "account_usage": {
    "start_date": "2024-02-01",
    "end_date": "2024-03-01",
    "prospector_requests": 2,
    "prospector_persons": 0,
    "prospector_persons_phones": 0,
    "enrichment_contact_requests": 0,
    "enrichment_contact_persons": 0,
    "enrichment_contact_persons_phones": 0,
    "enrichment_phone_requests": 0,
    "enrichment_phone_phones": 0,
    "enrichment_company_requests": 0,
    "enrichment_company_companies": 0,
    "verify_email_requests": 0,
    "verify_email_verified": 0,
    "search_contact_requests": 2,
    "search_contact_found": 0
  },
  "balance_remaining_usd": 99.9,
  "price": {
    "prospector_persons": 0.138,
    "prospector_persons_phones": 0.32,
    "enrichment_contact_persons": 0.138,
    "enrichment_contact_persons_phones": 0.32,
    "enrichment_phone_phones": 0.32,
    "enrichment_company_companies": 0.138,
    "search_contact_found": 0.04,
    "search_company_found": 0.04,
    "company_reveal_found": 0.05,
    "company_titles_found": 0,
    "job_change_found": 0.1,
    "verify_email_verified": 0.02
  }
}

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 parameters

Usage can be scoped one of two ways. The two modes are mutually exclusive. By month — pass month in YYYY-MM format. If omitted, returns the current month.

GET /v2/account?month=2024-10

By custom date range — pass start_date and end_date together in YYYY-MM-DD format (UTC). start_date is inclusive, end_date is exclusive, and the range cannot exceed 12 months.

GET /v2/account?start_date=2025-01-01&end_date=2025-01-15

In both modes, the window’s start cannot be more than 12 months in the past, and the window cannot be entirely in the future. Combining month with start_date/end_date, or passing only one of start_date/end_date, returns a 400.

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

balance_remaining_usd is always the current balance, and price (master keys only) is always the current unit price. Neither is a historical value for the requested month or date range.

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. Mutually exclusive with start_date and end_date. The month's start must not be more than 12 months in the past, and must not be entirely in the future.

Required string length: 7

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

start_date

string<date>

Optional interval start date in YYYY-MM-DD format, UTC, inclusive. Must be provided together with end_date, and is mutually exclusive with month. Must not be more than 12 months before the current UTC date, and must not be entirely in the future (at least one day of the interval must be today or earlier).

Required string length: 10

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

end_date

string<date>

Optional interval end date in YYYY-MM-DD format, UTC, exclusive. Must be provided together with start_date, must be strictly after start_date, and the interval cannot exceed 12 months. Mutually exclusive with month.

Required string length: 10

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

Response

Success. Returns usage for the authenticated key and account. Master API keys also receive unit prices in price.

Account reporter response containing key-level and account-level usage metrics. The optional price object is included only for master API keys.

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>

The current account balance. This is a present-moment value, not a balance as of or within the requested month or start_date/end_date interval.

Example:

23.34

price

object

Unit prices in USD keyed by their corresponding Account Reporter usage field, derived from the latest payment row. Present only when the request is authenticated with a master API key. May be an empty object when no payment row exists. These are current prices, not the actual historical prices in effect during the requested month or start_date/end_date interval.

Show child attributes

General guidance

Agent Skills

Prospector

Search Contact

Search Company

Contact Enrichment

Phone Enrichment

Company Enrichment

Job Change

Company Reveal

Company Titles

Email Verification

Webhooks

Account

Support

What this endpoint does

Query parameters

Usage fields

Authorizations

Query Parameters

Response

​What this endpoint does

​Query parameters

​Usage fields

Authorizations

Query Parameters

Response

What this endpoint does

Query parameters

Usage fields