Usage Reporting API

Get detailed usage statistics, spam detection analytics, and spending breakdowns programmatically.

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

GET /api/v1/reports/usage

Get usage statistics for the authenticating API key.

Query Parameters

Parameter Type Default Description
start_date string 30 days ago Start date in ISO format (YYYY-MM-DD)
end_date string today End date in ISO format (YYYY-MM-DD)
group_by string day Time grouping: day, week, or month
GET /api/v1/reports/usage/all

Get aggregated usage statistics across ALL your API keys.

Uses the same query parameters as /reports/usage.

GET /api/v1/reports/export NEW

Export your lookup history as a CSV file. Perfect for importing into spreadsheets, data analysis tools, or your own systems.

Query Parameters

Parameter Type Default Description
start_date string 30 days ago Start date in ISO format (YYYY-MM-DD)
end_date string today End date in ISO format (YYYY-MM-DD)
limit integer 10000 Maximum records to export (max: 50,000)
format string csv Export format (currently only csv supported)

CSV Columns

The exported CSV includes the following columns:

  • Timestamp (UTC) - When the lookup was performed
  • Phone Number - The queried phone number
  • Products - Products included in lookup (lrn, cnam, spam, etc.)
  • Amount - Cost charged for this lookup
  • LRN - Location Routing Number
  • LRN Activated At - Date LRN was activated
  • Carrier - Voice carrier name
  • Carrier Type - WIRELESS, LANDLINE, VOIP, etc.
  • CNAM - Caller ID name
  • Messaging Enabled - Yes/No
  • Messaging Provider - SMS provider name
  • Is Spam - Yes/No if spam was detected
  • Spam Type - SPAM, ROBOCALL, or SCAM
  • City - Geographic city
  • State - Geographic state

Example Request

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

Rate Limits

To prevent abuse, CSV exports are limited to:

  • 10 requests per hour
  • 2 requests per minute
  • Maximum 50,000 records per export

Example Request

curl -X GET "https://api-service.verirouteintel.io/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

Field Type Description
summary.total_lookups integer Total number of API lookups in the period
summary.total_spent float Total amount charged in USD
summary.spam_detected integer Number of lookups that detected spam
summary.clean_numbers integer Number of lookups with clean (non-spam) results
summary.spam_rate_percent float Percentage of spam checks that detected spam
by_product object Lookup counts by product type (lrn, cnam, spam, etc.)
by_interface object Lookup counts by interface (api, web, batch)
spam_breakdown object Spam detection counts by type (spam, scam, robocall)
time_series array Usage data grouped by time period

Code Examples

Python

import requests

api_key = "YOUR_API_KEY"
url = "https://api-service.verirouteintel.io/api/v1/reports/usage"

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://api-service.verirouteintel.io/api/v1/reports/usage',
    {
      headers: { 'Authorization': `Bearer ${apiKey}` },
      params: {
        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

Endpoint Rate Limit
/reports/usage 60 requests per hour, 10 per minute
/reports/usage/all 30 requests per hour, 5 per minute
/reports/export 10 requests per hour, 2 per minute

Error Responses

Code Error Description
400 INVALID_PARAMETER Invalid group_by value (must be day, week, or month)
400 INVALID_DATE_FORMAT Date format is invalid (use YYYY-MM-DD)
401 UNAUTHORIZED Missing or invalid API key
429 RATE_LIMITED Too many requests, try again later

Dashboard Alternative

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

Dashboard Access: Visit My Lookup History to see interactive charts, filter by date range and API key, and export data to CSV.