Moderations

A moderation is one moderated object and its result: a verdict (flagged), a recommendation (allow, review or reject) and a score from 0 to 1 for every policy the template runs. A whole form produces one parent moderation and one moderation per content field.

Endpoints

The moderation object

One moderated object and its result. A form is one parent moderation of the type form with one moderation per content field under fields.

The moderation objectJSON

{
  "object": "moderation",
  "id": "mod_20KilKON2Z1Lf75c7AXP6m",
  "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.98,
    "violence": 0,
    "self_harm": 0,
    "sexual": 0,
    "spam": 0,
    "links_contact": 0,
    "illicit": 0,
    "gibberish": 0,
    "off_topic": 0,
    "made_with_ai": 0,
    "instructions": 1
  },
  "triggered": ["toxicity", "instructions"],
  "rule": null,
  "reasons": [
    "trigger:toxicity:flag",
    "trigger:instructions:flag",
    "triage:reject"
  ],
  "details": {
    "toxicity": {
      "labels": ["insult"],
      "matches": [
        {
          "label": "insult",
          "value": "Worst seller ever. You are a complete idiot."
        }
      ]
    },
    "instructions": {
      "labels": ["confidence:100"],
      "matches": [
        {
          "label": "evidence",
          "value": "You are a complete idiot.",
          "field": "input"
        }
      ],
      "explanation": "The review contains personal attacks against the seller rather than focusing on the product or service, which violates the policy against personal attacks.",
      "field": "input"
    }
  },
  "author": null,
  "language": "en",
  "usage": {
    "checks": 1,
    "cached": false
  },
  "latency_ms": 2184,
  "dry_run": false,
  "content_id": null,
  "context_id": null,
  "metadata": null,
  "created_at": "2026-10-08T09:28:34.691Z",
  "completed_at": "2026-10-08T09:28:37.066Z"
}

Attributes

object"moderation"

Always moderation.

idstring

Id of the moderation: mod_ plus 22 base62 characters. Null in the result of a template test.

templateobject or null

The template the moderation ran on.

slugstring: Slug of the template. basic is the built-in basic check.
versioninteger: Number of the template version that ran. Versions start at 1 and every publish adds one.

typeenum

text, image or form. audio and video are in development and are never returned.

One oftextimageaudiovideoform

fieldstring

Key of the template field this object is. Present on a form's field moderations and on single objects sent with field; absent otherwise.

statusenum

screening: queued or running. completed: every policy answered. partial: at least one policy failed and the others stand. invalid: the submission failed the template's validation. failed: the run itself failed and no check was consumed.

One ofscreeningcompletedpartialfailedinvalid

flaggedboolean

The verdict: true when at least one trigger with the flag effect fired, or when validation failed. It is separate from recommendation: a content rule can allow a flagged moderation.

recommendationenum or null

What to do with the content: allow, review or reject. It comes from the first matching content rule, else from severity triage, and is then adjusted by client_action. Null while the status is screening and on a failed moderation.

One ofallowreviewreject

severityenum or null

none, low, medium, high or critical, from the highest weighted policy score: medium from the template's review threshold (default 0.40), high from its reject threshold (default 0.80) and critical from 0.95. none for an invalid submission. Null while screening and on a failed moderation.

One ofnonelowmediumhighcritical

policiesmap

The score of every policy the template runs, from 0 (clean) to 1 (certain violation), keyed by policy key and rounded to two decimals. For a form, the highest score of each policy across its fields. Guidelines and wordlists appear as guideline/<slug> and wordlist/<slug>. A policy that does not apply to the content type scores 0. Empty while screening.

triggeredarray of strings

Keys of the policies whose trigger fired.

ruleobject or null

The content rule that decided the recommendation, or null when severity triage decided.

idstring

Id of the rule within the template, for example r4.

namestring

Name of the rule.

actionenum

The rule's outcome: allow, review or reject.

One ofallowreviewreject

reasonsarray of strings

The path to the decision, in order, as strings: trigger:<policy>:<effect> (with @<field> after the policy for a field trigger), rule:<id>, triage:<recommendation>, review_trigger, client_action:<action>:<recommendation>, partial:<policies>, partial_review and validation_failed.

detailspolicy details object

Evidence per policy, as an object keyed by policy key. A policy has an entry only when it produced labels, matches or an explanation, came from the result cache, or failed. On the parent of a form it covers the AI instructions and the guidelines; the evidence of each field is under that field's own moderation. Absent while screening.

labelsarray of strings: Sub-labels the policy assigned, for example phone for personal_data, url for links_contact or insult for toxicity.
matchesarray of maps: The pieces of evidence. Every item has a label and usually a value, the matched or quoted text. Pattern policies add start and end, character offsets in the normalised text; wordlists add term, canonical and similarity; quotes from a model add reason.
canonical_termstring: For a wordlist, the canonical spelling of the first matched term, for example tradely when the text said tr4dely.
masked_outputstring: For personal_data, the text with every match masked, for example call +44***23.
explanationstring: A short explanation from the model: why a guideline or the AI instructions scored as they did, or a one-line description of an image.
fieldstring: Key of the template field the result belongs to.
cachedboolean: True when the result came from the result cache. Absent otherwise.
errorstring: Why the policy could not be scored. Present only when the policy failed, in which case the moderation's status is partial.

validation_errorsarray of objects

Why validation failed. Present only when it did.

fieldstring: Key of the field at fault. For a single object it is input or field, or null for an image sent without field.
codestring: required, type, min_length, max_length, numeric, pattern, enum, min, max, min_items, max_items, url, unknown_field or type_mismatch.
messagestring: A sentence that names the field and the rule, for example Title must be at least 10 characters.
url: On the moderation of a form's image field: the URL of the image the entry is about, in place of field. Such an entry reports an image that could not be fetched or that broke the field's size limits, with a code such as fetch_failed, too_large, unsupported_type, max_bytes or dimensions, and does not make the moderation invalid.

authorobject or null

The author as the decision saw them. Null when the request had no author_id.

idstring or null

Id of the author: aut_ plus 22 base62 characters. Null in a template test when the author does not exist.

external_idstring

Your id for the author.

statusenum

The author's status when the decision was made: enabled, suspended or blocked. A suspension past its end date reads as enabled. Not included in list items.

One ofenabledsuspendedblocked

trust_levelenum

The author's effective trust level when the decision was made. Not included in list items.

One ofnewbasicregularestablishedtrusted

known

Always true when present: the author record existed when the decision was made. Not included in list items.

languagestring or null

ISO 639-1 code of the content's main language, for example en. Null for images, and for text of fewer than 12 letters when the template has no language hint.

usageobject

What the moderation cost.

checksinteger: Checks consumed: one per object, one more per image, plus the check weight of each advanced policy the template enables. 0 for test keys, template tests and invalid submissions.
cachedboolean: True when every policy result came from the result cache. Such a moderation is charged a quarter of its checks, rounded up.
estimated: Template tests only: the checks a live request with the same content would consume.

latency_msinteger or null

Time the pipeline took, in milliseconds. Time spent waiting in the queue is not included. Null while screening.

dry_runboolean

True when the request asked for a dry run or the project runs in dry run. Do not enforce the recommendation of a dry run.

testboolean

True for a moderation made with a test key or by a template test. Absent otherwise.

content_idstring or null

Your id for the object, or null.

context_idstring or null

Your id for the conversation, order or other context, or null.

metadataobject or null

The metadata sent with the request, or null. Removed after the retention period.

fieldsmap

Forms only: one moderation per text or image field that had a value, keyed by field key. Number, boolean, enum, url and json fields are validated and readable by content rules, and have no entry.

The moderation object

created_attimestamp

When the moderation was created, ISO 8601 in UTC.

completed_attimestamp or null

When the result was ready, ISO 8601 in UTC. Null while screening.

parent_id

On a form's field moderation: id of the parent moderation.

error

On a failed moderation: an object with code and message.

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