Account

Usage Statistics

Aggregated usage for the authenticated customer over a rolling window ending now. Useful for tracking spend against your plan's rate limit, spotting which lookups you actually depend on, and confirming that your cache hit rate is what you expect.

Parameters

Example

curl 'https://api.securityaccelerated.com/v1/usage?days=7' \
  -H 'X-API-Key: your-api-key'

const res = await fetch(
  'https://api.securityaccelerated.com/v1/usage?days=7',
  { headers: { 'X-API-Key': process.env.API_KEY } }
);
const usage = await res.json();
console.log(usage.total_requests, usage.cache_hit_rate);

import os, requests

res = requests.get(
    "https://api.securityaccelerated.com/v1/usage",
    params={"days": 7},
    headers={"X-API-Key": os.environ["API_KEY"]},
)
usage = res.json()
print(usage["total_requests"], usage["cache_hit_rate"])

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET",
		"https://api.securityaccelerated.com/v1/usage?days=7", nil)
	req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var usage struct {
		TotalRequests int     `json:"total_requests"`
		CacheHitRate  float64 `json:"cache_hit_rate"`
	}
	json.NewDecoder(resp.Body).Decode(&usage)
	fmt.Println(usage.TotalRequests, usage.CacheHitRate)
}

Response

{
  "total_requests": 1284,
  "cache_hits": 3907,
  "cache_misses": 1130,
  "cache_hit_rate": 0.776,
  "avg_latency_ms": 412.8,
  "total_domains": 2140,
  "total_ips": 96,
  "status_codes": { "200": 1270, "429": 14 },
  "feature_usage": { "dns": 2140, "ssl": 2140, "whois": 757 },
  "requests_by_path": { "/v1/domain/lookup": 1188, "/v1/ip/lookup": 96 },
  "period_start": "2026-08-03T00:00:00Z",
  "period_end": "2026-08-10T00:00:00Z"
}

Response Fields

How Counting Works

feature_usage counts the lookups you requested, however they were served. A lookup answered from cache still counts, because otherwise caching would make a feature you depend on look unused.

cache_hits and cache_misses count individual lookups, not requests. That is why they routinely exceed total_requests: one request naming six lookups across three domains contributes eighteen to their sum and one to total_requests.

Key Rotation

Issues a fresh API key and starts a grace window on every key you held before it. The request takes no body. Rotate on a schedule, when someone with access leaves, or immediately if a key may have been exposed.

Example

curl -X POST https://api.securityaccelerated.com/v1/keys/rotate \
  -H 'X-API-Key: your-current-api-key'

Response

{
  "api_key": "3f9a1c...  (64 hex characters)",
  "old_keys_expire_at": "2026-08-11T14:22:05Z",
  "message": "store this key now — it cannot be retrieved again; previous keys stop working at old_keys_expire_at"
}

Response Fields

Rotating Safely

The grace window exists so that rotation is not an outage. Both the old and new keys authenticate until old_keys_expire_at, which gives you time to deploy:

1. Call POST /v1/keys/rotate and store api_key in your secret manager.
2. Deploy it everywhere that talks to the API — every service, job runner, and CI secret.
3. Confirm the rollout before old_keys_expire_at. A single lookup with the new key is enough.
4. At old_keys_expire_at the previous keys stop working. Anything still holding one starts receiving 401.

The grace window is 24 hours. Rotating again during one issues another key and starts a fresh window on the key you just replaced — but it never pushes back an expiry that is already set. Keys grace-expired by an earlier rotation keep their original deadline, so repeated rotation cannot be used to keep an exposed key alive.

Error Handling

All error responses use the same envelope as the rest of the API:

{
  "error": "description of the problem"
}

Both endpoints count against your plan's rate limit like any other request, and both echo X-Request-ID and your X-Client-Request-ID. See Request Correlation for the header contract.