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:
/usage/summaryGet aggregated usage statistics for your account over a date range.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
start_date | string | No | Start date (YYYY-MM-DD format). Defaults to beginning of current billing period. |
end_date | string | No | End 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:
/usage/limitsCheck 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:
/usage/by-endpointGet a breakdown of API usage by endpoint over the specified time period. Helps identify optimization opportunities.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
days | number | 30 | Number 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:
/usage/historyGet monthly usage history for trending analysis. Useful for capacity planning and identifying seasonal patterns.
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
months | number | 6 | Number 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/limitsbefore 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-endpointto identify optimization targets - Cache results where appropriate
- Use webhooks instead of polling for scan status
- Batch operations where possible
3. Plan Ahead
- Review
/usage/historymonthly 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
- Rate Limits - Understanding rate limit tiers and headers
- API Reference - Complete endpoint documentation
- Pricing Plans - Compare plan limits and features