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 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. 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>

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.

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 parameter

Usage fields

Authorizations

Query Parameters

Response

​What this endpoint does

​Query parameter

​Usage fields

Authorizations

Query Parameters

Response

What this endpoint does

Query parameter

Usage fields