API Documentation

Complete guide to integrating ComplianceLayer into your security workflow.

Usage Analytics

Track your API consumption, monitor usage patterns, and stay within your plan limits. ComplianceLayer provides comprehensive usage analytics to help you optimize API calls and manage costs.

Why Track Usage?

  • Cost Management: Monitor consumption to avoid unexpected overages
  • Optimization: Identify which endpoints consume the most quota
  • Planning: Historical trends help you choose the right plan
  • Debugging: Detect unusual API activity or integration issues

Usage Summary

Get an overview of your API usage for a specific time period:

GET/usage/summary

Get aggregated usage statistics for your account over a date range.

Query Parameters

ParameterTypeRequiredDescription
start_datestringNoStart date (YYYY-MM-DD format). Defaults to beginning of current billing period.
end_datestringNoEnd date (YYYY-MM-DD format). Defaults to today.
curl "https://api.compliancelayer.net/v1/usage/summary?start_date=2026-03-01&end_date=2026-03-09" \
  -H "Authorization: Bearer cl_YOUR_API_KEY"

Check Limits

Verify your current usage against plan limits before making requests:

GET/usage/limits

Check if you're within your plan's usage limits. Returns detailed quota information and remaining capacity.

curl "https://api.compliancelayer.net/v1/usage/limits" \
  -H "Authorization: Bearer cl_YOUR_API_KEY"

Use this endpoint before batch operations or scheduling to ensure you have sufficient quota.

Usage by Endpoint

See which API endpoints consume the most of your quota:

GET/usage/by-endpoint

Get a breakdown of API usage by endpoint over the specified time period. Helps identify optimization opportunities.

Query Parameters

ParameterTypeDefaultDescription
daysnumber30Number of days to analyze (1-90)
curl "https://api.compliancelayer.net/v1/usage/by-endpoint?days=7" \
  -H "Authorization: Bearer cl_YOUR_API_KEY"

Historical Trends

View usage trends over time to identify patterns and plan capacity:

GET/usage/history

Get monthly usage history for trending analysis. Useful for capacity planning and identifying seasonal patterns.

Query Parameters

ParameterTypeDefaultDescription
monthsnumber6Number of months to return (1-12)
curl "https://api.compliancelayer.net/v1/usage/history?months=3" \
  -H "Authorization: Bearer cl_YOUR_API_KEY"

Practical Examples

Monitoring Daily Usage

Check your usage at the start of each day to stay within limits:

async function checkDailyUsage() {
  const response = await fetch(
    'https://api.compliancelayer.net/v1/usage/limits',
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );

  const data = await response.json();

  console.log(`Plan: ${data.plan.name}`);
  console.log(`Scans used: ${data.usage.scans_this_month}/${data.plan.limits.scans_per_month}`);
  console.log(`Usage: ${data.usage.usage_percent.toFixed(1)}%`);

  // Warn if approaching limit
  if (data.usage.usage_percent > 80) {
    console.warn('⚠️  Approaching monthly scan limit!');
  }

  return data;
}

// Run daily check
await checkDailyUsage();

Identifying Top Endpoints

Find which endpoints you call most frequently:

async function analyzeEndpointUsage(days = 30) {
  const response = await fetch(
    `https://api.compliancelayer.net/v1/usage/by-endpoint?days=${days}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );

  const data = await response.json();

  console.log(`Usage analysis for last ${days} days:`);
  console.log(`Total requests: ${data.total_requests}`);
  console.log('\nTop endpoints:');

  data.endpoints.slice(0, 5).forEach((endpoint, i) => {
    console.log(`${i + 1}. ${endpoint.endpoint}`);
    console.log(`   Calls: ${endpoint.count} (${endpoint.percent.toFixed(1)}%)`);
    console.log(`   Avg response time: ${endpoint.avg_response_time_ms}ms`);
  });

  return data;
}

await analyzeEndpointUsage(7);

Capacity Planning

Use historical data to predict future usage and plan upgrades:

async function planCapacity() {
  const response = await fetch(
    'https://api.compliancelayer.net/v1/usage/history?months=6',
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );

  const data = await response.json();

  // Calculate average monthly scans
  const avgScans = data.history.reduce((sum, month) => sum + month.scans, 0) / data.history.length;

  // Get current plan limit
  const limitsResponse = await fetch(
    'https://api.compliancelayer.net/v1/usage/limits',
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );

  const limits = await limitsResponse.json();
  const monthlyLimit = limits.plan.limits.scans_per_month;

  console.log(`Average monthly scans: ${Math.round(avgScans)}`);
  console.log(`Current plan limit: ${monthlyLimit}`);
  console.log(`Capacity utilization: ${((avgScans / monthlyLimit) * 100).toFixed(1)}%`);

  // Recommend upgrade if consistently over 80%
  if ((avgScans / monthlyLimit) > 0.8) {
    console.log('\n💡 Recommendation: Consider upgrading your plan');
    console.log('   You\'re consistently using over 80% of your quota.');
  }

  return data;
}

await planCapacity();

Best Practices

1. Monitor Usage Proactively

  • Check /usage/limits before running batch operations
  • Set up daily cron jobs to track usage trends
  • Alert when usage exceeds 80% of quota

2. Optimize High-Volume Endpoints

  • Use /usage/by-endpoint to identify optimization targets
  • Cache results where appropriate
  • Use webhooks instead of polling for scan status
  • Batch operations where possible

3. Plan Ahead

  • Review /usage/history monthly for trends
  • Upgrade plans before hitting limits, not after
  • Account for seasonal patterns in your usage

4. Build Usage Dashboards

Create internal dashboards that visualize:

  • Current usage vs plan limits (from /usage/limits)
  • Daily/weekly usage trends (from /usage/summary)
  • Top API consumers by endpoint (from /usage/by-endpoint)
  • Cost projections based on historical data

5. Set Up Alerts

async function checkAndAlert() {
  const response = await fetch(
    'https://api.compliancelayer.net/v1/usage/limits',
    {
      headers: {
        'Authorization': `Bearer ${process.env.API_KEY}`
      }
    }
  );

  const data = await response.json();
  const usagePercent = data.usage.usage_percent;

  if (usagePercent >= 90) {
    // Critical: Send PagerDuty alert
    await notifyPagerDuty({
      severity: 'critical',
      summary: `API quota at ${usagePercent}%`,
      details: data
    });
  } else if (usagePercent >= 80) {
    // Warning: Send Slack notification
    await notifySlack({
      channel: '#engineering',
      text: `⚠️  API usage at ${usagePercent}% of monthly quota`
    });
  }
}

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

Troubleshooting

Usage Data Doesn't Match Expected

  • Check that you're looking at the correct billing period
  • Failed requests still count toward rate limits but not monthly quota
  • Free tier scans and authenticated scans are counted separately

Historical Data Shows Gaps

  • Usage history is only available for active subscriptions
  • Data is aggregated at end of each month
  • Current month shows partial data

Endpoint Breakdown Incomplete

  • Only shows endpoints with at least 1 call in period
  • Anonymous/unauthenticated requests are not tracked
  • Admin endpoints may be excluded from user-facing analytics

Related Topics