Skip to content
Get Started

Create a batch

POST/v1/moderations/batchKey scope moderate

Moderates up to 100 objects in one request and returns one result per item, in the order sent. A batch of at most 10 single text objects runs in the request and answers 200; any other batch (more items, a form, an image, or an item with mode set to async) is queued item by item and answers 202. An item that is refused does not fail the batch: its place in data holds an error entry.

Needs a key with the moderate scope. Authentication

curl https://api.useinfrared.com/v1/moderations/batch \
  -H "Authorization: Bearer $INFRARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "template": "review",
        "type": "text",
        "input": "Arrived two days early and works exactly as described. The seller answered every question.",
        "content_id": "review_9032",
        "author_id": "user_5290"
      },
      {
        "template": "review",
        "type": "text",
        "input": "Skip this shop. I buy mine at https://deals.example.com with the code SAVE20 and get 20% off.",
        "content_id": "review_9033",
        "author_id": "user_4821"
      }
    ]
  }'
200 OKResponse
{
  "object": "list",
  "data": [
    {
      "object": "moderation",
      "id": "mod_11SrKjWwwIYkkhV7A341eo",
      "template": {
        "slug": "review",
        "version": 1
      },
      "type": "text",
      "status": "completed",
      "flagged": false,
      "recommendation": "allow",
      "severity": "none",
      "policies": {
        "personal_data": 0,
        "lookalike_characters": 0,
        "profanity": 0,
        "hate_speech": 0,
        "toxicity": 0,
        "violence": 0,
        "self_harm": 0,
        "sexual": 0,
        "spam": 0,
        "links_contact": 0,
        "illicit": 0,
        "gibberish": 0,
        "off_topic": 0,
        "made_with_ai": 0,
        "instructions": 0
      },
      "triggered": [],
      "rule": null,
      "reasons": ["triage:allow"],
      "details": {
        "instructions": {
          "labels": ["confidence:100"],
          "matches": [
            {
              "label": "evidence",
              "value": "Arrived two days early and works exactly as described. The seller answered every question.",
              "field": null
            }
          ],
          "explanation": "The review describes a real experience with the product and seller, adhering to the policy."
        }
      },
      "author": {
        "id": "aut_4jb9a0j0nR6JwaRhJm4IWN",
        "external_id": "user_5290",
        "status": "enabled",
        "trust_level": "new",
        "known": true
      },
      "language": "en",
      "usage": {
        "checks": 1,
        "cached": false
      },
      "latency_ms": 1891,
      "dry_run": false,
      "content_id": "review_9032",
      "context_id": null,
      "metadata": null,
      "created_at": "2026-10-08T09:28:38.710Z",
      "completed_at": "2026-10-08T09:28:41.170Z"
    },
    {
      "object": "moderation",
      "id": "mod_6N1eLwABe6dRMHtzC53hc2",
      "template": {
        "slug": "review",
        "version": 1
      },
      "type": "text",
      "status": "completed",
      "flagged": true,
      "recommendation": "reject",
      "severity": "critical",
      "policies": {
        "personal_data": 0,
        "lookalike_characters": 0,
        "profanity": 0,
        "hate_speech": 0,
        "toxicity": 0,
        "violence": 0,
        "self_harm": 0,
        "sexual": 0,
        "spam": 0.9,
        "links_contact": 0.9,
        "illicit": 0,
        "gibberish": 0,
        "off_topic": 0,
        "made_with_ai": 0,
        "instructions": 1
      },
      "triggered": ["spam", "links_contact", "instructions"],
      "rule": null,
      "reasons": [
        "trigger:spam:review",
        "trigger:links_contact:review",
        "trigger:instructions:flag",
        "triage:reject"
      ],
      "details": {
        "spam": {
          "labels": ["promotion"],
          "matches": [
            {
              "label": "promotion",
              "value": "Skip this shop. I buy mine at https://deals.example.com with the code SAVE20 and get 20% off."
            }
          ]
        },
        "links_contact": {
          "labels": ["url"],
          "matches": [
            {
              "label": "url",
              "value": "https://deals.example.com"
            },
            {
              "label": "url",
              "value": "https://deals.example.com",
              "start": 30,
              "end": 55
            },
            {
              "label": "url",
              "value": "https://deals.example.com",
              "source": "model"
            }
          ]
        },
        "instructions": {
          "labels": ["confidence:100"],
          "matches": [
            {
              "label": "evidence",
              "value": "I buy mine at https://deals.example.com with the code SAVE20 and get 20% off.",
              "field": null
            }
          ],
          "explanation": "The review promotes a competitor by providing a link and discount code for another website."
        }
      },
      "author": {
        "id": "aut_7ZRftUOZyMjsmFWvJifaOJ",
        "external_id": "user_4821",
        "status": "enabled",
        "trust_level": "new",
        "known": true
      },
      "language": "en",
      "usage": {
        "checks": 1,
        "cached": false
      },
      "latency_ms": 2253,
      "dry_run": false,
      "content_id": "review_9033",
      "context_id": null,
      "metadata": null,
      "created_at": "2026-10-08T09:28:42.640Z",
      "completed_at": "2026-10-08T09:28:45.418Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Headers

Idempotency-Key

Works as on POST /v1/moderations, for the batch as a whole: a repeat of the key with the same body returns the stored response for 24 hours.

Request body

itemsarray of moderation request objectsRequired

The objects to moderate, 1 to 100 of them, each a single object or a whole form with the same properties as the body of POST /v1/moderations. The organisation's plan can set a lower maximum. The batch decides how items run: async on any item queues the whole batch, and sync on an item is ignored once the batch is queued. The request body is limited to 2 MB.

Returns

Status 200 when the batch ran in the request, 202 when it was queued. Both carry a list object whose data has one entry per item: a moderation, or an entry with object set to error, the item's index and an error holding code, message and details. Refusals of one item, such as template_not_found or quota_exceeded, appear there and never change the status of the batch. has_more is always false.

Errors

400
invalid_request

Idempotency-Key is longer than 255 characters.

403
plan_limit

The batch has more items than the organisation's plan allows. details[0].message is limit N.

409
idempotency_key_reused

The Idempotency-Key was already used with a different request body.

409
idempotency_in_progress

A request with the same Idempotency-Key is still being processed.

422
validation_error

items is empty or has more than 100 entries, the body has another key, or any item matches neither moderation shape. No item is processed.

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.