Usage & Quotas API

The Usage API lets you monitor your scan consumption, check quota limits, review alert history, and subscribe to real-time usage events over WebSocket.

Authentication

All usage endpoints require your API key:

X-API-Key: nat_pk_your_api_key_here

Base URL

https://api.nat-testing.io/api/v1

Endpoints

Get current usage

Returns current-period scan usage and quota information for your tenant.

GET /api/v1/usage

curl https://api.nat-testing.io/api/v1/usage \
  -H "X-API-Key: $NAT_API_KEY"

Response 200 OK:

{
  "tenant_id": "tenant_abc123",
  "plan": "pro",
  "scans_used": 423,
  "scans_limit": 500,
  "security_scan_count": 18,
  "monthly_security_scan_quota": 100,
  "approaching_limit": true,
  "quota_reset_date": "2025-02-01T00:00:00Z",
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z"
}

Response fields:

Field	Type	Description
`tenant_id`	string	Your tenant identifier
`plan`	string	Current plan: `free`, `pro`, `team`, `enterprise`
`scans_used`	integer	Functional scans consumed in the current billing period
`scans_limit`	integer	Maximum functional scans allowed per period
`security_scan_count`	integer	Security scans consumed in the current billing period
`monthly_security_scan_quota`	integer	Maximum security scans allowed per period (`0` on Free)
`approaching_limit`	boolean	`true` when usage exceeds 80% of quota
`quota_reset_date`	string	ISO 8601 timestamp when quota resets
`period_start`	string	Start of the current billing period
`period_end`	string	End of the current billing period

⚠️

When approaching_limit is true, consider upgrading your plan or pausing non-critical scans until quota_reset_date. When quota is fully exhausted, new scan requests return 402 QUOTA_EXCEEDED.

Get usage alert history

Returns a list of usage alerts that have been triggered for your tenant, such as approaching-limit warnings and quota-exceeded events.

GET /api/v1/usage/alerts

Query parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Results per page (max 100)
`type`	string		Filter by alert type: `approaching_limit`, `quota_exceeded`, `quota_reset`

curl "https://api.nat-testing.io/api/v1/usage/alerts?per_page=10" \
  -H "X-API-Key: $NAT_API_KEY"

Response 200 OK:

{
  "alerts": [
    {
      "alert_id": "alert_001",
      "type": "approaching_limit",
      "message": "You have used 85% of your monthly scan quota (425/500).",
      "scans_used": 425,
      "scans_limit": 500,
      "triggered_at": "2025-01-28T14:22:00Z"
    },
    {
      "alert_id": "alert_002",
      "type": "quota_exceeded",
      "message": "Monthly scan quota exhausted. New scans are blocked until 2025-02-01.",
      "scans_used": 500,
      "scans_limit": 500,
      "triggered_at": "2025-01-29T09:41:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "per_page": 10
}

Alert types:

Type	Description
`approaching_limit`	Triggered when usage exceeds 80% of quota
`quota_exceeded`	Triggered when quota is fully exhausted
`quota_reset`	Triggered when quota resets at the start of a new billing period

WebSocket: real-time usage events

Connect to /ws/live to receive real-time usage_update events as scans are consumed.

WebSocket wss://api.nat-testing.io/ws/live

Connecting

Include your API key as a query parameter or in the connection headers:

const ws = new WebSocket(
  "wss://api.nat-testing.io/ws/live?api_key=nat_pk_your_api_key_here"
);

const ws = new WebSocket(
  "wss://api.nat-testing.io/ws/live?api_key=nat_pk_your_api_key_here"
);
 
ws.onopen = () => {
  console.log("Connected to NAT live events");
};
 
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
 
  if (msg.type === "usage_update") {
    console.log(`Scans used: ${msg.scan_count} / ${msg.monthly_scan_quota}`);
 
    if (msg.approaching_limit) {
      console.warn("Warning: approaching quota limit");
    }
  }
};
 
ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

Event format

All events follow this envelope structure:

{
  "type": "usage_update",
  "tenant_id": "tenant_abc123",
  "scan_count": 426,
  "monthly_scan_quota": 500,
  "security_scan_count": 18,
  "monthly_security_scan_quota": 100,
  "approaching_limit": true,
  "quota_reset_date": "2025-02-01T00:00:00Z",
  "timestamp": "2025-01-28T14:22:31Z"
}

Event fields:

Field	Type	Description
`type`	string	Always `usage_update`
`tenant_id`	string	Your tenant identifier
`scan_count`	integer	Updated functional scan count after the triggering scan
`monthly_scan_quota`	integer	Monthly functional scan quota
`security_scan_count`	integer	Updated security scan count
`monthly_security_scan_quota`	integer	Monthly security scan quota
`approaching_limit`	boolean	`true` when above 80% of quota
`quota_reset_date`	string	ISO 8601 timestamp for next reset
`timestamp`	string	When the event was emitted

The WebSocket connection sends a usage_update event after every scan completes. You can use this to power real-time dashboards without polling the REST endpoint.