Overview

The Usage API provides insights into your DNS query volumes, helping you monitor traffic and plan capacity.

Required scope: usage:read

Endpoints

Endpoint reference

Method	Endpoint	Description
`GET`	`/v1/usage/summary`	Get usage summary
`GET`	`/v1/usage/current`	Get current period usage
`GET`	`/v1/usage/top-zones`	Get top zones by query volume
`GET`	`/v1/zones/{zone_id}/usage`	Get zone-specific usage

Get Usage Summary

Retrieve an overview of your DNS usage:

curl https://api.dnscale.eu/v1/usage/summary \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": {
    "customer_id": "cust_abc123",
    "period": "2025-01",
    "total_queries": 5250000,
    "total_zones": 12,
    "total_records": 156,
    "queries_by_region": {
      "EU_GLOBAL": 4200000,
      "GLOBAL": 1050000
    }
  }
}

Get Current Period Usage

Retrieve usage for the current billing period:

curl https://api.dnscale.eu/v1/usage/current \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": {
    "period_start": "2025-01-01T00:00:00Z",
    "period_end": "2025-01-31T23:59:59Z",
    "days_remaining": 15,
    "queries": {
      "total": 2500000,
      "included": 5000000,
      "overage": 0,
      "projected": 5000000
    },
    "zones": {
      "total": 12,
      "included": 50,
      "overage": 0
    }
  }
}

Get Top Zones

Retrieve your zones ranked by query volume:

curl "https://api.dnscale.eu/v1/usage/top-zones?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Default	Description
`limit`	10	Number of zones to return (max: 50)
`period`	current	Time period: `current`, `last_month`, `last_7_days`

Response:

{
  "status": "success",
  "data": {
    "items": [
      {
        "zone_id": "zone_abc123",
        "zone_name": "example.com",
        "queries": 1500000,
        "percentage": 30.0
      },
      {
        "zone_id": "zone_def456",
        "zone_name": "api.example.com",
        "queries": 1200000,
        "percentage": 24.0
      },
      {
        "zone_id": "zone_ghi789",
        "zone_name": "cdn.example.com",
        "queries": 800000,
        "percentage": 16.0
      }
    ],
    "period": "current",
    "total_queries": 5000000
  }
}

Get Zone Usage

Retrieve detailed usage for a specific zone:

curl https://api.dnscale.eu/v1/zones/{zone_id}/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "status": "success",
  "data": {
    "zone_id": "zone_abc123",
    "zone_name": "example.com",
    "period": "current_month",
    "queries": 1500000,
    "queries_by_type": {
      "A": 900000,
      "AAAA": 300000,
      "MX": 150000,
      "TXT": 100000,
      "CNAME": 50000
    },
    "queries_by_day": [
      {"date": "2025-01-01", "queries": 48000},
      {"date": "2025-01-02", "queries": 52000},
      {"date": "2025-01-03", "queries": 49000}
    ]
  }
}

Usage Metrics

Metric	Description
`total_queries`	Total DNS queries across all zones
`queries_by_type`	Breakdown by record type (A, AAAA, MX, etc.)
`queries_by_region`	Breakdown by DNScale region
`projected`	Estimated end-of-period total based on current rate

Plan Limits

Each plan includes a monthly query allowance:

Plan	Included Queries	Included Zones
Nano Free	100,000	1
Nano	5,000,000	10
Pro	50,000,000	100
Scale	500,000,000	Unlimited
Enterprise	Custom	Unlimited

Overage charges apply when you exceed your included queries. See Billing for details.

Example: Monitor Usage Alerts

# Check if approaching plan limit
USAGE=$(curl -s https://api.dnscale.eu/v1/usage/current \
  -H "Authorization: Bearer YOUR_API_KEY")
 
TOTAL=$(echo $USAGE | jq '.data.queries.total')
INCLUDED=$(echo $USAGE | jq '.data.queries.included')
PERCENTAGE=$(echo "scale=2; $TOTAL / $INCLUDED * 100" | bc)
 
echo "Usage: $PERCENTAGE% of monthly allowance"
 
if (( $(echo "$PERCENTAGE > 80" | bc -l) )); then
  echo "Warning: Approaching plan limit!"
fi