Retrieve usage

GET/v1/usageKey scope read

Returns the organisation's checks for the current period (used, included, remaining and extra) and the project's traffic for a date range: totals and a breakdown per day, per template and per advanced policy. Traffic made with test keys is not counted.

Needs a key with the read scope. Authentication

curl https://api.useinfrared.com/v1/usage \
  -H "Authorization: Bearer $INFRARED_KEY"

const response = await fetch("https://api.useinfrared.com/v1/usage", {
  headers: { Authorization: `Bearer ${process.env.INFRARED_KEY}` },
});

const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.useinfrared.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
)

data = response.json()

200 OKResponse

{
  "object": "usage_summary",
  "checks_used": 20,
  "checks_quota": 250000,
  "checks_remaining": 249980,
  "extra_checks": 0,
  "period_start": "2026-10-08",
  "period_end": "2026-11-01",
  "resets_at": "2026-11-01T00:00:00.000Z",
  "project": {
    "object": "usage",
    "period": {
      "from": "2026-10-01",
      "to": "2026-10-08"
    },
    "environment": "live",
    "totals": {
      "moderations": 20,
      "checks": 20,
      "flagged": 15,
      "allowed": 5,
      "reviewed": 0,
      "rejected": 15,
      "cached": 0,
      "partial": 0,
      "failed": 0
    },
    "by_day": [
      {
        "date": "2026-10-08",
        "moderations": 20,
        "checks": 20,
        "flagged": 15
      }
    ],
    "by_template": [
      {
        "template": "review",
        "moderations": 20,
        "checks": 20,
        "flagged": 15,
        "rejected": 15,
        "reviewed": 0
      }
    ],
    "by_policy": [
      {
        "policy": "made_with_ai",
        "moderations": 20,
        "checks": 20
      }
    ]
  }
}

Query parameters

fromdate: First day of the project breakdown, as YYYY-MM-DD. Default: the first day of the current calendar month. It does not change the checks figures, which always cover the current period.
todate: Last day of the project breakdown, as YYYY-MM-DD. Default: today.

Returns

The usage summary.

200 OKAn usage object

Errors

422: validation_error
from or to is not a date in the form YYYY-MM-DD.

Every endpoint can also answer the errors any request can meet: a missing key, a rate limit, a malformed body. Errors

Something missing or unclear on this page? Write to support@useinfrared.com.