How to Monitor Your Easy Email Finder API Usage and Credit Balance

Visibility Into Your API Usage

When your business depends on the Easy Email Finder API, you need visibility into how credits are being consumed. Running out of credits mid-pipeline is costly in terms of wasted time. Unexpected spend spikes can break budgets. The API provides two free endpoints specifically for monitoring: /balance and /usage.

The Balance Endpoint

The /balance endpoint returns your current credit count. It is free and does not consume credits.

curl https://easyemailfinder.com/api/v1/balance \
  -H "Authorization: Bearer eef_live_your_api_key_here"

# Response:
# { "credits": 342 }

The Usage Endpoint

The /usage endpoint returns your historical usage data, showing how credits have been consumed over time.

curl https://easyemailfinder.com/api/v1/usage \
  -H "Authorization: Bearer eef_live_your_api_key_here"

Building a Balance Alert System

Here is a Python script that checks your balance and sends alerts when credits are running low:

import os
import requests
from datetime import datetime

EEF_KEY = os.getenv("EEF_API_KEY")
BASE = "https://easyemailfinder.com/api/v1"
HEADERS = {"Authorization": f"Bearer {EEF_KEY}"}

# Alert thresholds
CRITICAL_THRESHOLD = 10    # credits
WARNING_THRESHOLD = 50     # credits
SLACK_WEBHOOK = os.getenv("SLACK_WEBHOOK_URL")

def check_balance_and_alert():
    resp = requests.get(f"{BASE}/balance", headers=HEADERS)
    credits = resp.json().get("credits", 0)
    dollars = credits * 0.25

    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
    status = "OK"

    if credits <= CRITICAL_THRESHOLD:
        status = "CRITICAL"
        send_alert(f"CRITICAL: Only {credits} credits (USD {dollars:.2f}) remaining! "
                   f"Pipeline will stall soon. Purchase more credits at "
                   f"https://easyemailfinder.com")
    elif credits <= WARNING_THRESHOLD:
        status = "WARNING"
        send_alert(f"Warning: {credits} credits (USD {dollars:.2f}) remaining. "
                   f"Consider purchasing more credits.")

    print(f"[{timestamp}] Balance: {credits} credits (USD {dollars:.2f}) - {status}")
    return credits

def send_alert(message: str):
    """Send alert to Slack."""
    if SLACK_WEBHOOK:
        requests.post(SLACK_WEBHOOK, json={"text": message})
    # Also log to file
    with open("balance_alerts.log", "a") as f:
        f.write(f"{datetime.now().isoformat()} - {message}\n")

if __name__ == "__main__":
    check_balance_and_alert()

Run this as a cron job every hour to catch low-balance situations before they affect your pipeline:

# Check balance every hour
0 * * * * cd /path/to/project && python balance_monitor.py

Building a Usage Dashboard

Track your usage over time by logging balance checks and computing daily consumption:

import json
import os
from datetime import datetime

USAGE_LOG = "usage_history.json"

def log_usage(credits: int):
    """Log the current balance with timestamp."""
    history = []
    if os.path.exists(USAGE_LOG):
        with open(USAGE_LOG, "r") as f:
            history = json.load(f)

    history.append({
        "timestamp": datetime.now().isoformat(),
        "credits": credits,
        "dollars": credits * 0.25
    })

    # Keep last 30 days of data
    history = history[-720:]  # 24 checks/day * 30 days

    with open(USAGE_LOG, "w") as f:
        json.dump(history, f, indent=2)

def calculate_daily_spend():
    """Calculate average daily credit consumption."""
    if not os.path.exists(USAGE_LOG):
        return 0

    with open(USAGE_LOG, "r") as f:
        history = json.load(f)

    if len(history) < 2:
        return 0

    # Compare first and last readings
    first = history[0]
    last = history[-1]

    t1 = datetime.fromisoformat(first["timestamp"])
    t2 = datetime.fromisoformat(last["timestamp"])
    days = max((t2 - t1).total_seconds() / 86400, 1)

    # Credits consumed (accounting for purchases)
    consumed = first["credits"] - last["credits"]
    if consumed < 0:
        consumed = 0  # Credits were purchased

    daily_avg = consumed / days
    print(f"Average daily consumption: {daily_avg:.1f} credits (USD {daily_avg * 0.25:.2f})")
    print(f"Projected monthly spend: USD {daily_avg * 30 * 0.25:.2f}")
    return daily_avg

Node.js Monitoring Example

const API_KEY = process.env.EEF_API_KEY;
const BASE = "https://easyemailfinder.com/api/v1";

async function monitorBalance() {
  const resp = await fetch(`${BASE}/balance`, {
    headers: { "Authorization": `Bearer ${API_KEY}` }
  });
  const { credits } = await resp.json();

  console.log(`Balance: ${credits} credits ($${(credits * 0.25).toFixed(2)})`);

  if (credits < 10) {
    console.error("CRITICAL: Credits almost exhausted!");
    // Send alert via your preferred channel
    await sendSlackAlert(`Critical: ${credits} EEF credits remaining`);
  }

  return credits;
}

// Check balance before each pipeline run
async function runPipelineWithBalanceCheck(websites) {
  const credits = await monitorBalance();
  const needed = websites.length;

  if (credits < needed) {
    console.log(`Need ${needed} credits but only have ${credits}. Adjusting batch size.`);
    websites = websites.slice(0, credits);
  }

  // Proceed with enrichment
  // ...
}

// Run every 30 minutes
setInterval(monitorBalance, 30 * 60 * 1000);

Pre-Pipeline Balance Checks

Always check your balance before starting a batch processing job. This prevents the frustration of a pipeline failing mid-run due to insufficient credits.

def preflight_check(estimated_websites: int) -> bool:
    resp = requests.get(f"{BASE}/balance", headers=HEADERS)
    credits = resp.json().get("credits", 0)

    print(f"Available: {credits} credits")
    print(f"Estimated need: {estimated_websites} credits")
    print(f"Estimated cost: USD {estimated_websites * 0.25:.2f}")

    if credits < estimated_websites:
        shortfall = estimated_websites - credits
        print(f"Shortfall: {shortfall} credits (USD {shortfall * 0.25:.2f})")
        print(f"Purchase credits at: https://easyemailfinder.com")
        return False

    print("Sufficient credits. Proceeding.")
    return True

# Before running your batch job
if preflight_check(500):
    run_batch_enrichment("input.csv", "output.csv")

Integrating with External Monitoring

For production systems, pipe balance data into your existing monitoring stack:

• Datadog / Grafana: Emit balance as a custom metric via StatsD or the Datadog API
• PagerDuty: Trigger an incident when credits drop below critical threshold
• Email alerts: Use a simple SMTP script to notify your team

Next Steps

Monitoring is a key part of any production API integration. Combine it with the cost optimization tips and rate limit best practices for a bulletproof pipeline. Full API documentation is at easyemailfinder.com/developer/docs.