Batch checks

A batch is for content that arrives together: the comments of a thread you are importing, a backlog you want screened, the replies a job produced overnight. One request carries a list of objects, each one moderated exactly as it would be on its own, and one response carries a result per object in the same order.

Put the objects in items. Each item is a complete request body of POST /v1/moderations: a single object or a whole form, with its own template, content_id and author_id.

curl https://api.useinfrared.com/v1/moderations/batch \
  -H "Authorization: Bearer $INFRARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "type": "text",
        "input": "Lovely table, arrived on time.",
        "content_id": "review_901"
      },
      {
        "template": "old-listing",
        "type": "text",
        "input": "Oak chairs, set of four.",
        "content_id": "listing_902"
      }
    ]
  }'

const response = await fetch("https://api.useinfrared.com/v1/moderations/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INFRARED_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      {
        type: "text",
        input: "Lovely table, arrived on time.",
        content_id: "review_901",
      },
      {
        template: "old-listing",
        type: "text",
        input: "Oak chairs, set of four.",
        content_id: "listing_902",
      },
    ],
  }),
});

const batch = await response.json();

import os
import requests

response = requests.post(
    "https://api.useinfrared.com/v1/moderations/batch",
    headers={"Authorization": f"Bearer {os.environ['INFRARED_KEY']}"},
    json={
        "items": [
            {
                "type": "text",
                "input": "Lovely table, arrived on time.",
                "content_id": "review_901",
            },
            {
                "template": "old-listing",
                "type": "text",
                "input": "Oak chairs, set of four.",
                "content_id": "listing_902",
            },
        ],
    },
)

batch = response.json()

{
  "object": "list",
  "data": [
    {
      "object": "moderation",
      "id": "mod_1wYU5OzcitEwsDwaRkuPyB",
      "template": { "slug": "basic", "version": 1 },
      "type": "text",
      "status": "completed",
      "flagged": false,
      "recommendation": "allow",
      "reasons": ["triage:allow"],
      "content_id": "review_901"
    },
    {
      "object": "error",
      "index": 1,
      "error": {
        "code": "template_not_found",
        "message": "Template old-listing not found",
        "details": []
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The second item named a template that does not exist. It failed alone: the first item was screened as usual.

How large a batch can be

A batch holds between 1 and 100 items, and each plan sets a ceiling of its own within that.

A batch above the plan's size answers 403 plan_limit before anything runs. The whole request body may be 2 MB, which long texts reach before the item count does.

When a batch answers in the same response

The whole batch is either answered inline or queued. It is answered inline, with 200 and finished moderations, when all three hold:

• every item is a single text object,
• there are 10 items or fewer,
• no item sets mode to async.

Otherwise the batch answers 202 and every item is queued, whatever its own mode says. Each entry is then a moderation with status: "screening", and each result arrives on its own by webhook or by polling. A form item queues the batch even when the form holds only text.

Items that fail

There are three ways an item can go wrong, and they look different:

• The item is refused. Its entry is an error object: object is error, index is its position in items, and error holds the same code, message and details a single request would have returned. A missing template, a template outside the plan, an unsupported content type and exhausted checks all arrive this way.
• The item fails validation. Its entry is a moderation with status: "invalid", exactly as for a single request. It is finished at once, also in a queued batch.
• The body does not match the schema. One malformed item rejects the whole batch with 422 before anything runs. details names the item, for example items.1.

Check object on every entry before reading it as a moderation.

Checks, limits and retries

Checks are counted per item, at that item's turn. A batch answered inline can therefore run out partway: the items before are screened and the items after come back as quota_exceeded errors.

The batch counts as one request against the rate limit.

An Idempotency-Key covers the whole batch. Repeating the request with the same key returns the first response, which for a queued batch is the list of screening moderations as first returned.

If the request ends in a 5xx, the items processed before the failure already exist and were charged. Send a content_id with every item so you can tell which ones went through.

Next

• Sync and asyncText is answered in the same response and images are queued. Choose with mode, then read a queued result from a webhook event or by polling.
• Statuses and errorsThe five statuses a moderation can have and every error the moderation endpoints return, with the HTTP status, the code and what to do next.
• IdempotencySend an Idempotency-Key when you create a moderation, and a retry returns the first answer in place of a second moderation and a second charge.
• Rate limitsEach API key may send a set number of requests a minute, by plan. Every response says where the key stands, and a 429 says how long to wait.