Checks and usage

A check is the unit every plan counts. Each moderation uses one or more, depending on what you send, and its response says how many. Knowing the arithmetic lets you size a plan and predict what a form with photos costs before you send it.

What one moderation costs

• One check for the object. A text is one object. So is a whole form, however many text fields it has.
• One more for each image.
• An advanced policy adds its own weight. made_with_ai, the advanced policy that runs today, adds one check for each image and nothing for text. Only policies whose tier is advanced add to the cost, and GET /v1/policies lists the check_weight of each. Every other policy is covered by the object's check.

Each object of a batch is charged on its own. A re-moderation is a new moderation and costs again. A dry run costs the same as live traffic.

Some results cost less, or nothing:

Every moderation reports its own cost in usage: checks is what it was charged, and cached says whether the result came from the cache. A request that answers 202 shows checks: 0 until the moderation has finished.

The monthly allowance

The allowance belongs to the organisation and is shared by all its projects.

• Without a subscription, the month is the calendar month in UTC. The allowance resets at midnight UTC on the 1st.
• With a subscription, it is your billing month. The allowance resets on the day of the month you subscribed.
• A yearly plan resets every month all the same.
• Checks you did not use do not carry over.

An upgrade raises the current month's allowance to the new plan's at once, and what you have used stays used. A downgrade takes nothing back and counts from the next month.

Extra checks

When a month needs more, buy a pack of extra checks on the Billing page. Every plan can, the Free plan included.

Extra checks are spent only after the monthly allowance is gone, oldest pack first, and one moderation can be paid partly from each. They carry over from month to month and survive a change of plan or a cancelled subscription. A pack expires 365 days after you bought it.

When checks run out

Before a moderation runs, Infrared works out its cost. If the allowance and the extra checks together do not cover it, the request answers 402 and nothing is screened:

{
  "error": {
    "code": "quota_exceeded",
    "message": "The monthly checks quota is exhausted and no extra checks are available",
    "details": [{ "field": "checks", "message": "2 needed, 1 available" }],
    "request_id": "req_4f0c2a9d8e7b46a1b3c5d6e7f8091a2b"
  }
}

• The test uses the full cost, before any cache discount. With one check left, a text passes and an image is refused.
• In a batch, each object is admitted on its own. A refused one comes back in its place as an entry with "object": "error", and the others run.
• A submission that fails validation is still answered, because it costs nothing.
• A test key is never refused.

A refused request is not run later. Decide in your code what a 402 means for your product: hold the content, publish it unscreened or turn the upload away.

If the request carried an Idempotency-Key, the refusal is remembered under that key for 24 hours. After you add checks, send the content again with a new key, or the stored 402 comes back.

Read usage over the API

GET /v1/usage needs the read scope. from and to are optional dates; without them the project figures cover the current calendar month up to today.

curl "https://api.useinfrared.com/v1/usage?from=2026-10-01&to=2026-10-08" \
  -H "Authorization: Bearer $INFRARED_KEY"

const response = await fetch("https://api.useinfrared.com/v1/usage?from=2026-10-01&to=2026-10-08", {
  headers: { Authorization: `Bearer ${process.env.INFRARED_KEY}` },
});

const usage = await response.json();

import os
import requests

response = requests.get(
    "https://api.useinfrared.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    params={
        "from": "2026-10-01",
        "to": "2026-10-08",
    },
)

usage = response.json()

{
  "object": "usage_summary",
  "checks_used": 38420,
  "checks_quota": 100000,
  "checks_remaining": 61580,
  "extra_checks": 5000,
  "period_start": "2026-09-14",
  "period_end": "2026-10-14",
  "resets_at": "2026-10-14T09:26:53.000Z",
  "project": {
    "object": "usage",
    "period": { "from": "2026-10-01", "to": "2026-10-08" },
    "environment": "live",
    "totals": {
      "moderations": 2140,
      "checks": 3105,
      "flagged": 312,
      "allowed": 1790,
      "reviewed": 228,
      "rejected": 122,
      "cached": 96,
      "partial": 4,
      "failed": 0
    },
    "by_day": [
      { "date": "2026-10-01", "moderations": 251, "checks": 362, "flagged": 35 },
      { "date": "2026-10-02", "moderations": 268, "checks": 391, "flagged": 41 }
    ],
    "by_template": [
      { "template": "listing", "moderations": 1180, "checks": 2145, "flagged": 201, "rejected": 84, "reviewed": 150 },
      { "template": "review", "moderations": 890, "checks": 890, "flagged": 104, "rejected": 35, "reviewed": 72 },
      { "template": "basic", "moderations": 70, "checks": 70, "flagged": 7, "rejected": 3, "reviewed": 6 }
    ],
    "by_policy": [{ "policy": "made_with_ai", "moderations": 1180, "checks": 1180 }]
  }
}

The top level is the organisation's current allowance month, across every project. project is the key's own project between from and to, both days included.

Four things the numbers do not say on their own:

• The top level is current. The project block is built from daily totals that are refreshed every five minutes.
• project counts live traffic only, also when you call with a test key.
• In by_policy, checks is the policy's weight counted once for each moderation, not what you were charged. Read cost from totals.checks.
• A moderation that ended failed is in no total, so failed reads 0. A submission that failed validation is counted, as flagged and as rejected.

The endpoint's full reference is Retrieve usage.

Usage in the dashboard

Usage shows the organisation's checks at the top: used, remaining, extra checks and the reset date. Under it are the current project's moderations by day, by template and by policy. Switch between Live and Test traffic, and between This month, Last 30 days and Last 7 days.

This month on that page is the calendar month. Checks this month is the allowance month, which starts on your billing day when you have a subscription, so the two can cover different dates. The rail repeats the checks figure on every page.

Next

• Plans and limitsWhat each plan includes, what is counted per organisation and what per project, and what happens to your setup when the plan changes.
• BillingSubscribe, change plan, buy extra checks and find your invoices on the Billing page of the dashboard. It is open to the organisation's Owners.
• Test modeA test key runs the whole pipeline and uses no checks. It is not a sandbox: its moderations still reach the review queue and your webhooks.
• ErrorsEvery error has one JSON shape. Branch on its code, show its details and quote its request id. The table lists each code the API returns and when.