Analytics API

Get programmatic access to your usage statistics, token consumption, and API metrics. The Analytics API provides a comprehensive snapshot of your account activity, perfect for building custom dashboards, monitoring integrations, or automated reporting.

Plan Requirement: The Analytics API is only available on Pro and Mega plans. Free and Starter plan users will receive a 403 response with an upgrade prompt.

Endpoint

GET Request

GET https://api.apiverve.com/v1/analytics

Authentication

Include your API key in the request header:

Authentication Header

x-api-key: YOUR_API_KEY

Response Format

A successful response includes a comprehensive summary of your usage data:

Success Response (200 OK)

{
  "status": "ok",
  "data": {
    "summary": {
      "plan": "pro",
      "tokensUsed": 12450,
      "tokensRemaining": 87550,
      "tokensLimit": 100000,
      "bonusTokens": 0,
      "usagePercent": 12,
      "renewalDate": "2025-01-15",
      "lifetimeCalls": 458230,
      "rateLimit": "120 requests/minute"
    },
    "daily": {
      "2024-12-15": 450,
      "2024-12-16": 678,
      "2024-12-17": 234
    },
    "byApi": {
      "emailvalidator": 5200,
      "weatherforecast": 3100,
      "currencyconverter": 2150,
      "dnslookup": 2000
    },
    "lastActivity": "2024-12-17 14:30:00"
  },
  "error": null
}

Response Fields

Summary Object

Field	Type	Description
`plan`	string	Your current subscription plan (pro, mega, pro_annual, mega_annual)
`tokensUsed`	number	Total tokens consumed in the current billing period
`tokensRemaining`	number	Tokens remaining until your limit is reached
`tokensLimit`	number	Maximum tokens allowed per billing period (includes bonus tokens)
`bonusTokens`	number	Additional bonus tokens added to your account
`usagePercent`	number	Percentage of token quota used (0-100)
`renewalDate`	string	Date when your token quota resets (YYYY-MM-DD format)
`lifetimeCalls`	number	Total API calls made since account creation
`rateLimit`	string	Your plan's rate limit (e.g., "120 requests/minute" or "unlimited")

Daily Object

Contains token usage per day for the last 30 days. Keys are dates in YYYY-MM-DD format, values are token counts. Days with zero usage are omitted.

byApi Object

Token usage broken down by API. Keys are API identifiers (e.g., emailvalidator), values are total tokens consumed by that API in the current period.

lastActivity

Timestamp of your most recent API call in YYYY-MM-DD HH:mm:ss format (UTC). Returns null if no activity recorded.

Code Examples

cURL

cURL Request

curl "https://api.apiverve.com/v1/analytics" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (Fetch API)

JavaScript Fetch

const apiKey = 'YOUR_API_KEY';

fetch('https://api.apiverve.com/v1/analytics', {
  headers: {
    'x-api-key': apiKey
  }
})
  .then(response => response.json())
  .then(data => {
    if (data.status === 'ok') {
      console.log('Tokens used:', data.data.summary.tokensUsed);
      console.log('Tokens remaining:', data.data.summary.tokensRemaining);
      console.log('Usage:', data.data.summary.usagePercent + '%');
    }
  })
  .catch(error => console.error('Error:', error));

Python

import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.apiverve.com/v1/analytics'
headers = {'x-api-key': api_key}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    data = response.json()
    if data['status'] == 'ok':
        summary = data['data']['summary']
        print(f"Plan: {summary['plan']}")
        print(f"Tokens used: {summary['tokensUsed']}/{summary['tokensLimit']}")
        print(f"Usage: {summary['usagePercent']}%")
        print(f"Renewal date: {summary['renewalDate']}")
else:
    print(f'Error: {response.status_code}')

Node.js (axios)

Node.js

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';

axios.get('https://api.apiverve.com/v1/analytics', {
  headers: { 'x-api-key': apiKey }
})
.then(response => {
  const { summary, daily, byApi } = response.data.data;

  console.log('=== Usage Summary ===');
  console.log(`Plan: ${summary.plan}`);
  console.log(`Tokens: ${summary.tokensUsed} / ${summary.tokensLimit}`);
  console.log(`Rate Limit: ${summary.rateLimit}`);

  console.log('\n=== Top APIs ===');
  Object.entries(byApi)
    .sort((a, b) => b[1] - a[1])
    .forEach(([api, tokens]) => {
      console.log(`  ${api}: ${tokens} tokens`);
    });
})
.catch(error => console.error('Error:', error.message));

Use Cases

Use Case	Description
Custom Dashboards	Build internal dashboards showing API usage metrics alongside your other business KPIs
Usage Alerts	Set up automated alerts when usage exceeds certain thresholds (e.g., 80% of quota)
Cost Tracking	Monitor API consumption for budgeting and cost allocation across projects or departments
Automated Reporting	Generate weekly or monthly usage reports for stakeholders
Capacity Planning	Analyze daily usage patterns to plan for scaling or plan upgrades

Error Responses

401 Unauthorized

API key is missing or invalid:

401 Response

{
  "status": "error",
  "data": null,
  "error": "API key required"
}

403 Forbidden (Plan Restriction)

Analytics API requires Pro or Mega plan:

403 Response

{
  "status": "error",
  "data": null,
  "error": "Analytics API requires Pro or Mega plan",
  "premium": {
    "message": "Analytics API is only available on Pro and Mega plans. Upgrade to access detailed usage analytics.",
    "locked_features": ["analytics_api"],
    "upgrade_url": "https://apiverve.com/pricing"
  }
}

405 Method Not Allowed

Only GET requests are supported:

405 Response

{
  "status": "error",
  "data": null,
  "error": "Method not allowed"
}

Best Practices

Cache responses: Analytics data updates approximately every 1-2 minutes. Cache responses to avoid unnecessary calls.
Monitor usage percent: Set up alerts when usagePercent exceeds 80% to avoid hitting limits.
Track by API: Use the byApi breakdown to identify which APIs consume the most tokens and optimize accordingly.
Check renewal dates: Plan ahead for high-usage periods by checking renewalDate.
Handle errors gracefully: If the endpoint returns a 403, display an upgrade prompt to users rather than an error.

Pro Tip: The Analytics API does NOT consume tokens. You can call it as often as needed for monitoring without affecting your quota.

Need Help?

Was this page helpful?

Help us improve our documentation