Version: 1.0.0

Usage & Quota Analytics

The usage analytics endpoints give you full visibility into your API consumption patterns. Use these endpoints to track quota consumption, monitor usage trends, identify heavy consumers, and audit API calls for compliance.

All usage endpoints are scoped to your tenant. You can only see your own data.

Required scope: usage:read

Usage Summary

Get an aggregated view of your API usage over a date range.

Endpoint

GET /api/v1/usage/summary

Query Parameters

Parameter	Type	Default	Description
`period`	string	`30d`	Period: `24h`, `7d`, `30d`, `90d`

Request

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/summary?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "tenantId": "7b5b0610-2947-412f-a869-4683da321fcf",
    "period": {
      "start": "2026-02-04T00:00:00Z",
      "end": "2026-03-06T23:59:59Z"
    },
    "totalCalls": 4827,
    "successCalls": 4512,
    "errorCalls": 315,
    "avgDurationMs": 245,
    "maxDurationMs": 12450,
    "totalScans": 892,
    "distinctScanTypes": 5,
    "scanTypesUsed": ["nmap", "zap", "nuclei", "trivy", "sentinel"],
    "quotaConsumedCalls": 892
  }
}

Response Fields

Field	Description
`totalCalls`	Total number of API calls made
`successCalls`	Calls that returned 2xx status codes
`errorCalls`	Calls that returned 4xx or 5xx status codes
`avgDurationMs`	Average response time in milliseconds
`totalScans`	Total number of scans submitted
`distinctScanTypes`	Number of different scan engines used
`quotaConsumedCalls`	Number of calls that consumed quota

Quota Counting

Not all API calls consume quota. Only successful scan-related operations (2xx responses) count toward your plan quota.

Usage History

View time-series API usage data, broken down by hour or day.

Endpoint

GET /api/v1/usage/history

Query Parameters

Parameter	Type	Default	Description
`period`	string	`7d`	Period: `24h`, `7d`, `30d`, `90d`
`granularity`	string	auto	`hourly` or `daily` (auto-selected based on period)

Request

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/history?period=7d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "granularity": "daily",
    "entries": [
      {
        "timestamp": "2026-02-27T00:00:00Z",
        "totalCalls": 687,
        "successCalls": 645,
        "errorCalls": 42,
        "avgDurationMs": 198
      },
      {
        "timestamp": "2026-02-28T00:00:00Z",
        "totalCalls": 712,
        "successCalls": 690,
        "errorCalls": 22,
        "avgDurationMs": 234
      }
    ]
  }
}

Auto Granularity

Period	Default Granularity
`24h`	`hourly`
`7d`	`daily`
`30d`	`daily`
`90d`	`daily`

Usage by Scan Type

Breakdown of your API usage by scan engine to understand which tools are most used.

Endpoint

GET /api/v1/usage/by-scan-type

Request

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/by-scan-type?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "scanTypes": [
      {
        "scanType": "nmap",
        "totalScans": 342,
        "successScans": 330,
        "failedScans": 12,
        "avgDurationMs": 85000,
        "percentOfTotal": 38.3
      },
      {
        "scanType": "nuclei",
        "totalScans": 278,
        "successScans": 271,
        "failedScans": 7,
        "avgDurationMs": 120000,
        "percentOfTotal": 31.2
      },
      {
        "scanType": "zap",
        "totalScans": 145,
        "successScans": 140,
        "failedScans": 5,
        "avgDurationMs": 340000,
        "percentOfTotal": 16.3
      }
    ]
  }
}

Usage by API Key

View which API keys are generating the most usage. Useful for multi-team environments or when you have separate keys for different integrations.

Endpoint

GET /api/v1/usage/by-api-key

Request

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/by-api-key?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "apiKeys": [
      {
        "keyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "keyName": "CI/CD Pipeline - Production",
        "keyPrefix": "cix_sk_001e3c",
        "totalCalls": 3241,
        "successCalls": 3100,
        "errorCalls": 141,
        "lastUsedAt": "2026-03-06T09:45:12Z"
      },
      {
        "keyId": "b2c3d479-58cc-4372-a567-f47ac10b0e02",
        "keyName": "Monitoring - Read Only",
        "keyPrefix": "cix_sk_7f3a2b",
        "totalCalls": 1586,
        "successCalls": 1412,
        "errorCalls": 174,
        "lastUsedAt": "2026-03-06T10:00:00Z"
      }
    ]
  }
}

API Call Logs

Retrieve a detailed audit log of individual API calls for compliance and debugging.

Endpoint

GET /api/v1/usage/call-logs

Query Parameters

Parameter	Type	Default	Description
`period`	string	`24h`	Period: `24h`, `7d`, `30d`
`page`	integer	`1`	Page number
`limit`	integer	`50`	Results per page (max: 100)

Request

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/call-logs?period=24h&page=1&limit=20" \
  -H "X-API-Key: $CERTIX_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log-uuid-1",
        "method": "POST",
        "path": "/api/v1/scans",
        "statusCode": 201,
        "durationMs": 345,
        "scanType": "nmap",
        "target": "example.com",
        "quotaConsumed": true,
        "createdAt": "2026-03-06T10:00:00Z"
      },
      {
        "id": "log-uuid-2",
        "method": "GET",
        "path": "/api/v1/scans/uuid-here",
        "statusCode": 200,
        "durationMs": 45,
        "quotaConsumed": false,
        "createdAt": "2026-03-06T10:00:15Z"
      }
    ],
    "total": 156,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Compliance

API call logs include an integrity hash chain for tamper detection, compliant with ANSSI M25, NIS2, and DORA Art. 11 requirements.

Quota System

Your subscription plan defines the number of quota-consuming API calls you can make per billing period (calendar month).

What Consumes Quota

Action	Consumes Quota
`POST /scans` (success, 201)	Yes
`POST /scan-templates/:id/launch` (success, 201)	Yes
`GET /scans` (list scans)	No
`GET /scans/:id` (check status)	No
`GET /scans/:id/results` (retrieve results)	No
`POST /scans/:id/cancel`	No
Any failed request (4xx, 5xx)	No
Webhook/template/usage endpoints	No

Rule: Only successful scan creation calls (HTTP 201) consume quota.

Quota Exceeded

When your monthly quota is exhausted:

{
  "success": false,
  "error": "Monthly scan quota exceeded. Current usage: 500/500. Upgrade your plan or wait for the next billing period.",
  "code": "QUOTA_EXCEEDED"
}

HTTP Status: 429 Too Many Requests

Quota Reset

Quotas reset at the start of each calendar month (midnight UTC on the 1st).

Date Range Filtering

All usage endpoints support the period parameter for consistent date range filtering:

Period	Range
`24h`	Last 24 hours from now
`7d`	Last 7 days from now
`30d`	Last 30 days from now
`90d`	Last 90 days from now

Next Steps:

Usage Summary​

Endpoint​

Query Parameters​

Request​

Response (200 OK)​

Response Fields​

Usage History​

Endpoint​

Query Parameters​

Request​

Response (200 OK)​

Auto Granularity​

Usage by Scan Type​

Endpoint​

Request​

Response (200 OK)​

Usage by API Key​

Endpoint​

Request​

Response (200 OK)​

API Call Logs​

Endpoint​

Query Parameters​

Request​

Response (200 OK)​

Quota System​

What Consumes Quota​

Quota Exceeded​

Quota Reset​

Date Range Filtering​

Usage Summary

Endpoint

Query Parameters

Request

Response (200 OK)

Response Fields

Usage History

Endpoint

Query Parameters

Request

Response (200 OK)

Auto Granularity

Usage by Scan Type

Endpoint

Request

Response (200 OK)

Usage by API Key

Endpoint

Request

Response (200 OK)

API Call Logs

Endpoint

Query Parameters

Request

Response (200 OK)

Quota System

What Consumes Quota

Quota Exceeded

Quota Reset

Date Range Filtering