Usage & Analytics API

Track and analyze your API usage with detailed analytics, monitoring, and reporting capabilities.

Base URL

https://api.zaits.net/v1/usage

Authentication

All requests require your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Note: Usage analytics require read permissions on your API key.

Usage Summary

Get a comprehensive overview of your API usage for the current month.

Endpoint

GET /v1/usage/summary

Request Example

curl -X GET https://api.zaits.net/v1/usage/summary \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "summary": {
    "current_month_calls": 1247,
    "previous_month_calls": 892,
    "limit": 2500,
    "percent_used": "49.88",
    "trend": "39.79",
    "remaining_calls": 1253
  },
  "by_endpoint": {
    "face": 687,
    "ocr": 423,
    "signing": 137
  },
  "subscription_tier": "basic",
  "period": {
    "start": "2024-01-01T00:00:00.000Z",
    "end": "2024-01-15T14:30:22.123Z"
  }
}

Response Fields

Field

Type

Description

current_month_calls

number

Total API calls this month

previous_month_calls

number

Total API calls last month

limit

number/string

Monthly API call limit ("unlimited" for enterprise)

percent_used

string

Percentage of monthly limit used

trend

string

Percentage change from previous month

remaining_calls

number/string

Remaining calls this month

by_endpoint

object

API calls broken down by service

subscription_tier

string

Current subscription plan

period

object

Date range for the summary

Detailed Usage Statistics

Get detailed usage statistics with filtering and pagination.

Endpoint

GET /v1/usage/stats

Query Parameters

Parameter

Type

Required

Description

start_date

string

❌

Start date (ISO 8601 format)

end_date

string

❌

End date (ISO 8601 format)

endpoint

string

❌

Filter by endpoint path

limit

number

❌

Items per page (default: 100, max: 1000)

page

number

❌

Page number (default: 1)

Request Examples

curl -X GET "https://api.zaits.net/v1/usage/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  start_date: '2025-01-01',
  end_date: '2025-01-31',
  endpoint: 'face',
  limit: 50,
  page: 1
});

const response = await fetch(`https://api.zaits.net/v1/usage/stats?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();

import requests

params = {
    'start_date': '2025-01-01',
    'end_date': '2025-01-31',
    'endpoint': 'face',
    'limit': 50,
    'page': 1
}

response = requests.get(
    'https://api.zaits.net/v1/usage/stats',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params=params
)

data = response.json()

Response

{
  "success": true,
  "data": [
    {
      "id": "usage_123456",
      "user_id": "user_789",
      "endpoint": "/v1/face/verify",
      "method": "POST",
      "status_code": 200,
      "response_time": 1.245,
      "created_at": "2024-01-15T14:30:22.123Z",
      "request_size": 1024,
      "response_size": 512,
      "ip_address": "203.0.113.1",
      "user_agent": "MyApp/1.0"
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 100,
    "total_pages": 13
  },
  "statistics": {
    "total_calls": 100,
    "avg_response_time": "1.234",
    "min_response_time": "0.123",
    "max_response_time": "3.456",
    "status_codes": {
      "200": 95,
      "400": 3,
      "429": 2
    }
  },
  "filters": {
    "start_date": "2024-01-01",
    "end_date": null,
    "endpoint": "face"
  }
}

Data Fields

Field

Type

Description

id

string

Unique usage record ID

endpoint

string

API endpoint called

method

string

HTTP method used

status_code

number

HTTP response status

response_time

number

Processing time in seconds

created_at

string

Timestamp of the request

request_size

number

Request size in bytes

response_size

number

Response size in bytes

ip_address

string

Client IP address

user_agent

string

Client user agent

Real-time Usage Monitoring

Get real-time usage statistics for monitoring and alerting.

Endpoint

GET /v1/usage/realtime

Query Parameters

Parameter

Type

Required

Description

window

string

❌

Time window: 1h, 6h, 24h (default: 1h)

interval

string

❌

Data interval: 1m, 5m, 15m, 1h

Request Example

curl -X GET "https://api.zaits.net/v1/usage/realtime?window=6h&interval=15m" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "current_rate": 12.5,
    "peak_rate": 45.2,
    "total_calls": 2847,
    "error_rate": 2.1,
    "avg_response_time": 1.234,
    "by_endpoint": {
      "face": 1823,
      "ocr": 724,
      "signing": 300
    },
    "timeseries": [
      {
        "timestamp": "2024-01-15T14:00:00Z",
        "calls": 45,
        "errors": 1,
        "avg_response_time": 1.123
      },
      {
        "timestamp": "2024-01-15T14:15:00Z",
        "calls": 38,
        "errors": 0,
        "avg_response_time": 1.089
      }
    ]
  },
  "window": "6h",
  "interval": "15m"
}

Usage Alerts

Configure usage alerts to monitor your API consumption.

Create Alert

POST /v1/usage/alerts

Request Body

{
  "name": "High Usage Alert",
  "type": "threshold",
  "condition": {
    "metric": "calls_per_hour",
    "operator": "greater_than",
    "value": 100
  },
  "notification": {
    "webhook_url": "https://your-app.com/webhooks/alerts",
    "email": "[email protected]"
  },
  "enabled": true
}

List Alerts

GET /v1/usage/alerts

Update Alert

PUT /v1/usage/alerts/{alert_id}

Credit Usage

Track credit consumption for paid APIs.

Endpoint

GET /v1/usage/credits

Response

{
  "success": true,
  "data": {
    "total_purchased": 10000,
    "total_used": 7542,
    "remaining": 2458,
    "usage_by_service": {
      "face_verification": 3421,
      "ocr_extraction": 2876,
      "document_signing": 1245
    },
    "estimated_monthly_burn": 4820,
    "days_remaining": 15.3
  }
}

Export Usage Data

Export usage data for analysis or compliance.

Endpoint

POST /v1/usage/export

Request Body

{
  "format": "csv",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "include_details": true,
  "email_to": "[email protected]"
}

Response

{
  "success": true,
  "export_id": "export_abc123",
  "status": "processing",
  "estimated_completion": "2024-01-15T15:00:00Z",
  "download_url": null
}

Check Export Status

GET /v1/usage/export/{export_id}

Subscription Limits

Different subscription tiers have different usage limits:

Tier

Monthly API Calls

Real-time Monitoring

Export History

Alerts

Free

200

❌

7 days

❌

Basic

2,500

✅

30 days

1 alert

Pro

20,000

✅

90 days

5 alerts

Enterprise

Unlimited

✅

1 year

Unlimited

Error Responses

Common Error Codes

Error Code

HTTP Status

Description

insufficient_permissions

403

API key lacks read permissions

invalid_date_range

400

Invalid start/end date format

limit_exceeded

400

Requested limit exceeds maximum

export_quota_exceeded

429

Too many exports requested

Error Response Format

{
  "success": false,
  "error": {
    "code": "invalid_date_range",
    "message": "Start date cannot be after end date",
    "details": {
      "start_date": "2024-01-31",
      "end_date": "2024-01-01"
    }
  }
}

Best Practices

Monitoring Your Usage

Set up alerts before reaching 80% of your monthly limit
Monitor trends to predict future usage patterns
Track error rates to identify issues early

Performance Optimization

Use date filters to reduce data transfer
Implement pagination for large datasets
Cache usage summaries to reduce API calls

Security Considerations

Use read-only API keys for analytics
Restrict IP access for production monitoring
Rotate analytics keys regularly

Next: White-Label Deployment API

PreviousWebhook API NextBest Practices

Last updated 2 months ago