Usage Reporting API

Overview

The Usage Reporting API allows you to retrieve comprehensive analytics about your API usage, including:

• Total lookups and spending over any time period
• Spam detection statistics (spam detected, clean numbers, spam rate)
• Breakdown by spam type (spam, scam, robocall)
• Usage breakdown by product (LRN, CNAM, Spam, Messaging, Trust)
• Usage breakdown by interface (API, Web, Batch)
• Time series data for trending analysis

Endpoints

# Download CSV for December 2024
curl -X GET "https://verirouteintel.com/api/v1/reports/export?start_date=2024-12-01&end;_date=2024-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o lookup_history.csv

Example Requests

Using period parameter (simple)

# Get last 7 days of usage
curl -X GET "https://verirouteintel.com/api/v1/reports/usage?period=week" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using custom date range

# Get usage for a specific date range
curl -X GET "https://verirouteintel.com/api/v1/reports/usage?start_date=2024-12-01&end;_date=2024-12-31&group;_by=week" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "api_key": {
      "id": 19,
      "alias": "Production Key"
    },
    "period": {
      "start": "2024-12-01",
      "end": "2024-12-31"
    },
    "summary": {
      "total_lookups": 1547,
      "total_spent": 45.82,
      "spam_detected": 127,
      "clean_numbers": 892,
      "spam_rate_percent": 12.46
    },
    "by_product": {
      "lrn": 450,
      "enhanced_lrn": 200,
      "cnam": 600,
      "spam": 1019,
      "messaging": 150,
      "trust": 50
    },
    "by_interface": {
      "api": 1200,
      "web": 247,
      "batch": 100
    },
    "spam_breakdown": {
      "spam": 80,
      "scam": 32,
      "robocall": 15
    },
    "time_series": [
      {
        "date": "2024-W49",
        "count": 512,
        "spent": 15.36
      },
      {
        "date": "2024-W50",
        "count": 498,
        "spent": 14.94
      },
      {
        "date": "2024-W51",
        "count": 537,
        "spent": 15.52
      }
    ]
  }
}

Response Fields

Code Examples

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://verirouteintel.com/api/v1/reports/usage"

# Option 1: Use period parameter for simple date ranges
params = {"period": "week"}  # day, week, or month

# Option 2: Use custom date range (overrides period)
# params = {
#     "start_date": "2024-12-01",
#     "end_date": "2024-12-31",
#     "group_by": "week"
# }

response = requests.get(
    url,
    headers={"Authorization": f"Bearer {api_key}"},
    params=params
)

data = response.json()
summary = data["data"]["summary"]

print(f"Total Lookups: {summary['total_lookups']:,}")
print(f"Total Spent: ${summary['total_spent']:.2f}")
print(f"Spam Detected: {summary['spam_detected']}")
print(f"Spam Rate: {summary['spam_rate_percent']}%")

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

async function getUsageReport() {
  const response = await axios.get(
    'https://verirouteintel.com/api/v1/reports/usage',
    {
      headers: { 'Authorization': `Bearer ${apiKey}` },
      params: {
        period: 'week'  // or 'day', 'month'
        // Or use custom dates:
        // start_date: '2024-12-01',
        // end_date: '2024-12-31',
        // group_by: 'week'
      }
    }
  );

  const { summary, spam_breakdown } = response.data.data;

  console.log(`Total Lookups: ${summary.total_lookups.toLocaleString()}`);
  console.log(`Spam Rate: ${summary.spam_rate_percent}%`);
  console.log('Spam Breakdown:', spam_breakdown);
}

getUsageReport();

Rate Limits

Error Responses

Dashboard Alternative

If you prefer a visual interface, the same analytics are available in your dashboard: