Analytics API

Monitor your API usage with comprehensive analytics endpoints

GET /v1/analytics/dashboard

Dashboard Overview

cURL

curl --request GET \
  --url https://api.leadmagic.io/v1/analytics/dashboard \
  --header 'X-API-Key: <api-key>'

200

{
  "user": {
    "id": "user_abc123",
    "email": "[e-mail]"
  },
  "credits": {
    "current": 15432.5,
    "formatted": "$154.33"
  },
  "rate_limit": {
    "minute": {
      "limit": 300,
      "used": 45,
      "remaining": 255,
      "utilization": 15
    },
    "daily": {
      "limit": 500000,
      "used": 12500,
      "remaining": 487500,
      "utilization": 2.5
    }
  },
  "concurrency": {
    "current": 0,
    "peak": 23,
    "active_reservations": 0
  },
  "stats": {
    "today": {
      "requests": 1250,
      "credits": 875.5,
      "chargeable_requests": 1100,
      "chargeable_rate": 88,
      "unique_products": 5
    },
    "this_week": {
      "requests": 8500,
      "credits": 5200.25,
      "chargeable_requests": 7200,
      "chargeable_rate": 84.7,
      "unique_products": 8
    },
    "this_month": {
      "requests": 45000,
      "credits": 28500,
      "chargeable_requests": 38000,
      "chargeable_rate": 84.4,
      "unique_products": 12
    }
  }
}

Usage Analytics

Get detailed insights into your API usage, credit consumption, and performance metrics. All analytics endpoints are free and don’t consume credits.

100% Free: All analytics endpoints consume zero credits and have no rate limits. Use them to build dashboards, monitoring systems, and usage alerts.

Quick Reference

Endpoint	Method	Description	Best For
/v1/analytics/dashboard	GET	Real-time account status	Live dashboards, health checks
/v1/analytics/usage	GET	Daily usage summary	Weekly/monthly reports
/v1/analytics/products	GET	Per-product breakdown	Cost optimization
/v1/analytics/credits	GET	Credit consumption history	Spend tracking
/v1/analytics/summary	GET	All-time statistics	Account overview
/v1/analytics/daily	GET	Daily performance metrics	SLA monitoring
/v1/analytics/day/:date	GET	Single day breakdown	Debugging, audits

---

Dashboard

Get a real-time snapshot of your account status including credits, rate limits, and usage statistics.

GET /v1/analytics/dashboard

cURL

curl 'https://api.leadmagic.io/v1/analytics/dashboard' \
  -H 'X-API-Key: YOUR_API_KEY'

Response

{
  "user": {
    "id": "user_abc123",
    "email": "[e-mail]"
  },
  "credits": {
    "current": 15432.50,
    "formatted": "$154.33"
  },
  "rate_limit": {
    "minute": {
      "limit": 300,
      "used": 45,
      "remaining": 255,
      "utilization": 15.0
    },
    "daily": {
      "limit": 500000,
      "used": 12500,
      "remaining": 487500,
      "utilization": 2.5
    }
  },
  "concurrency": {
    "current": 0,
    "peak": 23,
    "active_reservations": 0
  },
  "stats": {
    "today": {
      "requests": 1250,
      "credits": 875.50,
      "chargeable_requests": 1100,
      "chargeable_rate": 88.0,
      "unique_products": 5
    },
    "this_week": {
      "requests": 8500,
      "credits": 5200.25,
      "chargeable_requests": 7200,
      "chargeable_rate": 84.7,
      "unique_products": 8
    },
    "this_month": {
      "requests": 45000,
      "credits": 28500.00,
      "chargeable_requests": 38000,
      "chargeable_rate": 84.4,
      "unique_products": 12
    }
  }
}

Response Fields

user · object · required

Your account information

Show properties

id · string

Unique user identifier

email · string

Account email address

credits · object · required

Current credit balance

Show properties

current · number

Raw credit balance (1 credit = $0.01)

formatted · string

Human-readable dollar value

rate_limit · object · required

Real-time rate limit status

Show properties

minute.limit · number

Requests per minute allowed

minute.used · number

Requests used this minute

minute.remaining · number

Requests remaining this minute

minute.utilization · number

Percentage of limit used (0-100)

daily.limit · number

Requests per day allowed

daily.used · number

Requests used today

daily.remaining · number

Requests remaining today

daily.utilization · number

Percentage of daily limit used

concurrency · object · required

Concurrent request tracking

Show properties

current · number

Currently in-flight requests

peak · number

Peak concurrent requests (session)

active_reservations · number

Credit reservations pending

stats · object · required

Usage statistics for today, this week, and this month

Show properties

requests · number

Total API requests

credits · number

Total credits consumed

chargeable_requests · number

Requests that consumed credits

chargeable_rate · number

Percentage of requests charged

unique_products · number

Number of different endpoints used

---

Usage Summary

Get aggregated usage metrics over a time period with daily breakdown.

GET /v1/analytics/usage?days=30

days · number · default: "30"

Number of days to include (1-90)

Response

{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "total_credits": 28500.00,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4,
    "unique_products": 12
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "chargeable_requests": 1100,
      "total_credits": 875.50,
      "unique_products_used": 5
    }
  ]
}

Chargeable Rate shows what percentage of your requests consumed credits. A lower rate means more free results (unknown validations, not-found responses, etc.).

---

Products Breakdown

Get per-product usage with requests, credits, and success rates. Essential for cost optimization.

GET /v1/analytics/products?days=30

days · number · default: "30"

Number of days to include (1-90)

Response

{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "products": {
    "email_validation": {
      "total_requests": 20000,
      "total_credits": 5000.00,
      "successful_requests": 19500,
      "failed_requests": 500,
      "success_rate": 97.5,
      "avg_credits_per_request": 0.25
    },
    "email_finder": {
      "total_requests": 10000,
      "total_credits": 8500.00,
      "successful_requests": 8500,
      "failed_requests": 1500,
      "success_rate": 85.0,
      "avg_credits_per_request": 0.85
    }
  },
  "daily": [...]
}

Success rate means we found data. For email finder, 85% success means 85% of lookups returned an email. You only pay for successful results.

---

Credit History

Get credit consumption history with daily breakdown. Perfect for spend tracking and budgeting.

GET /v1/analytics/credits?days=30

days · number · default: "30"

Number of days to include (1-90)

Response

{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "summary": {
    "total_credits": 28500.00,
    "total_requests": 45000,
    "chargeable_requests": 38000,
    "avg_credits_per_request": 0.63,
    "chargeable_rate": 84.4
  },
  "daily": [
    {
      "date": "2026-11-01",
      "total_credits": 875.50,
      "total_requests": 1250,
      "chargeable_requests": 1100
    }
  ]
}

---

All-Time Summary

Get lifetime statistics for your account, or specify a custom date range.

GET /v1/analytics/summary
GET /v1/analytics/summary?start_date=2026-10-01&end_date=2026-11-01

start_date · string

Start date (YYYY-MM-DD format). Optional.

end_date · string

End date (YYYY-MM-DD format). Optional.

Response

{
  "total_api_requests": 1250000,
  "total_credits_consumed": 425000.50,
  "unique_products_used": 15,
  "successful_requests": 1150000,
  "failed_requests": 100000,
  "success_rate": 92.0,
  "avg_response_time_ms": 245,
  "first_request": "2023-06-15T10:30:00.000Z",
  "last_request": "2026-11-01T14:22:00.000Z"
}

---

Daily Metrics

Get detailed daily metrics including latency percentiles and error rates. Essential for SLA monitoring.

GET /v1/analytics/daily?days=30

days · number · default: "30"

Number of days to include (1-90)

Response

{
  "period": {
    "start": "2026-10-02",
    "end": "2026-11-01",
    "days": 30
  },
  "data": [
    {
      "date": "2026-11-01",
      "total_requests": 1250,
      "successful_requests": 1175,
      "failed_requests": 75,
      "total_credits": 875.50,
      "p50_latency_ms": 180,
      "p95_latency_ms": 450,
      "p99_latency_ms": 890,
      "error_rate": 6.0
    }
  ]
}

Latency Percentiles

Metric	Description
p50_latency_ms	Median response time (50th percentile)
p95_latency_ms	95% of requests faster than this
p99_latency_ms	99% of requests faster than this

---

Day Breakdown

Get per-product breakdown for a specific day. Perfect for debugging and audits.

GET /v1/analytics/day/2026-11-01

Response

{
  "date": "2026-11-01",
  "summary": {
    "total_credits": 875.50,
    "total_requests": 1250,
    "products_count": 8
  },
  "products": [
    {
      "product_id": "email_validation",
      "requests": 500,
      "credits": 125.00,
      "credits_percentage": 14.29,
      "avg_credits_per_request": 0.25,
      "max_credits": 0.25
    },
    {
      "product_id": "email_finder",
      "requests": 350,
      "credits": 297.50,
      "credits_percentage": 34.00,
      "avg_credits_per_request": 0.85,
      "max_credits": 1.00
    }
  ]
}

---

Practical Examples

Monitoring Dashboard

Build a Real-Time Dashboard

Fetch all metrics in parallel for a comprehensive dashboard:

const headers = { 'X-API-Key': process.env.LEADMAGIC_API_KEY };

async function getDashboardMetrics() {
  const [dashboard, usage, products, daily] = await Promise.all([
    fetch('https://api.leadmagic.io/v1/analytics/dashboard', { headers }),
    fetch('https://api.leadmagic.io/v1/analytics/usage?days=7', { headers }),
    fetch('https://api.leadmagic.io/v1/analytics/products?days=7', { headers }),
    fetch('https://api.leadmagic.io/v1/analytics/daily?days=7', { headers })
  ]).then(responses => Promise.all(responses.map(r => r.json())));
  
  return {
    // Account health
    credits: dashboard.data.credits.current,
    creditsFormatted: dashboard.data.credits.formatted,
    
    // Rate limits
    minuteUtilization: dashboard.data.rate_limit.minute.utilization,
    dailyUtilization: dashboard.data.rate_limit.daily.utilization,
    
    // Weekly stats
    weeklyRequests: usage.data.summary.total_requests,
    weeklyCredits: usage.data.summary.total_credits,
    chargeableRate: usage.data.summary.chargeable_rate,
    
    // Top products by spend
    topProducts: Object.entries(products.data.products)
      .sort((a, b) => b[1].total_credits - a[1].total_credits)
      .slice(0, 5),
    
    // Performance
    avgLatency: daily.data.data.reduce((sum, d) => sum + d.p50_latency_ms, 0) / daily.data.data.length,
    avgErrorRate: daily.data.data.reduce((sum, d) => sum + d.error_rate, 0) / daily.data.data.length
  };
}

Alerting

Set Up Usage Alerts

Monitor credits and rate limits to prevent service interruptions:

async function checkAndAlert() {
  const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
    headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
  });
  const { data } = await response.json();
  
  const alerts = [];
  
  // Credit alerts
  if (data.credits.current < 100) {
    alerts.push({
      level: 'critical',
      message: `Credits critically low: ${data.credits.formatted}`
    });
  } else if (data.credits.current < 1000) {
    alerts.push({
      level: 'warning', 
      message: `Credits running low: ${data.credits.formatted}`
    });
  }
  
  // Rate limit alerts
  if (data.rate_limit.daily.utilization > 90) {
    alerts.push({
      level: 'warning',
      message: `Daily rate limit at ${data.rate_limit.daily.utilization}%`
    });
  }
  
  if (data.rate_limit.minute.utilization > 80) {
    alerts.push({
      level: 'warning',
      message: `Minute rate limit at ${data.rate_limit.minute.utilization}%`
    });
  }
  
  // Send alerts via Slack, email, PagerDuty, etc.
  for (const alert of alerts) {
    await sendAlert(alert);
  }
  
  return alerts;
}

// Run every 5 minutes
setInterval(checkAndAlert, 5 * 60 * 1000);

Cost Optimization

Analyze and Optimize Spending

Identify which products consume the most credits:

import requests

def analyze_spending():
    headers = {'X-API-Key': 'YOUR_API_KEY'}
    
    # Get last 30 days of product usage
    response = requests.get(
        'https://api.leadmagic.io/v1/analytics/products?days=30',
        headers=headers
    )
    data = response.json()['data']
    
    # Calculate cost breakdown
    products = data['products']
    total_credits = sum(p['total_credits'] for p in products.values())
    
    print(f"Total spend: ${total_credits * 0.01:.2f}")
    print("\nBreakdown by product:")
    
    for product_id, stats in sorted(
        products.items(), 
        key=lambda x: x[1]['total_credits'], 
        reverse=True
    ):
        percentage = (stats['total_credits'] / total_credits) * 100
        cost = stats['total_credits'] * 0.01
        
        print(f"  {product_id}:")
        print(f"    Requests: {stats['total_requests']:,}")
        print(f"    Credits: {stats['total_credits']:,.2f} ({percentage:.1f}%)")
        print(f"    Cost: ${cost:.2f}")
        print(f"    Success rate: {stats['success_rate']}%")
        print(f"    Avg per request: {stats['avg_credits_per_request']:.3f}")
        print()

SLA Monitoring

Track Performance SLAs

Monitor latency and error rates against your SLA targets:

const SLA_TARGETS = {
  p95_latency_ms: 1000,  // 1 second
  p99_latency_ms: 2000,  // 2 seconds
  error_rate: 5.0        // 5%
};

async function checkSLA() {
  const response = await fetch(
    'https://api.leadmagic.io/v1/analytics/daily?days=7',
    { headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY } }
  );
  const { data } = await response.json();
  
  const violations = [];
  
  for (const day of data.data) {
    if (day.p95_latency_ms > SLA_TARGETS.p95_latency_ms) {
      violations.push({
        date: day.date,
        metric: 'p95_latency',
        value: day.p95_latency_ms,
        target: SLA_TARGETS.p95_latency_ms
      });
    }
    
    if (day.error_rate > SLA_TARGETS.error_rate) {
      violations.push({
        date: day.date,
        metric: 'error_rate',
        value: day.error_rate,
        target: SLA_TARGETS.error_rate
      });
    }
  }
  
  return {
    period: data.period,
    violations,
    slaCompliant: violations.length === 0
  };
}

---

Best Practices

Cache dashboard responses

Analytics endpoints are free, but caching improves your dashboard performance:

let cache = { data: null, timestamp: 0 };
const CACHE_TTL = 60 * 1000; // 1 minute

async function getCachedDashboard() {
  if (cache.data && Date.now() - cache.timestamp < CACHE_TTL) {
    return cache.data;
  }
  
  const response = await fetch('https://api.leadmagic.io/v1/analytics/dashboard', {
    headers: { 'X-API-Key': process.env.LEADMAGIC_API_KEY }
  });
  
  cache = { data: await response.json(), timestamp: Date.now() };
  return cache.data;
}

Use response headers instead

Every API response includes X-Credits-Remaining — use this instead of polling the dashboard:

const response = await fetch('https://api.leadmagic.io/v1/people/email-validation', {
  method: 'POST',
  headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: '[e-mail]' })
});

const creditsRemaining = response.headers.get('X-Credits-Remaining');
const requestId = response.headers.get('X-Request-Id');

console.log(`Credits after request: ${creditsRemaining}`);

Batch analytics calls

Fetch multiple analytics endpoints in parallel:

const [dashboard, products, daily] = await Promise.all([
  fetch('/v1/analytics/dashboard', { headers }),
  fetch('/v1/analytics/products?days=30', { headers }),
  fetch('/v1/analytics/daily?days=30', { headers })
]).then(responses => Promise.all(responses.map(r => r.json())));

Set up regular reporting

Schedule weekly reports using cron or serverless functions:

// Weekly summary report
async function generateWeeklyReport() {
  const [usage, products] = await Promise.all([
    fetch('/v1/analytics/usage?days=7', { headers }).then(r => r.json()),
    fetch('/v1/analytics/products?days=7', { headers }).then(r => r.json())
  ]);
  
  return {
    period: usage.data.period,
    totalRequests: usage.data.summary.total_requests,
    totalCredits: usage.data.summary.total_credits,
    topProducts: Object.entries(products.data.products)
      .sort((a, b) => b[1].total_credits - a[1].total_credits)
      .slice(0, 5)
      .map(([id, stats]) => ({ id, ...stats }))
  };
}

---

Related

Check Credits

Simple endpoint to check your current balance.

Rate Limits

Learn about rate limiting and how to stay within limits.

Authorizations

X-API-Key · string · header · required

Your LeadMagic API key. Header name is case-insensitive (X-API-Key, X-API-KEY, x-api-key all work).

Response

200

application/json

Dashboard data retrieved successfully

user · object

Show child attributes

credits · object

Show child attributes

rate_limit · object

Show child attributes

concurrency · object

Show child attributes

stats · object

Show child attributes