Rules

Rules run an action when their conditions match. Scope a rule to specific policies with config_keys, or leave that list empty to apply it app-wide.

Upsert Rule

Create or update a moderation rule. This endpoint uses POST /api/v2/moderation/moderation_rule and allows you to define the rule name, conditions, actions, and other configuration in a single request.

client.moderation.upsert_moderation_rule(
    name="ban_on_severe_harassment",
    rule_type="user",
    config_keys=["chat:messaging"],
    logic="AND",
    action={
        "type": "ban_user",
        "ban_options": {"duration": 3600, "reason": "Severe harassment"},
    },
    conditions=[
        {
            "type": "text_rule",
            "text_rule_params": {"harm_labels": ["HATRED"], "severity": "critical"},
        }
    ],
    enabled=True,
    description="Auto-ban users for critical harassment",
)

Request Parameters

Response

Get Rule

Retrieve a single moderation rule by its ID. This endpoint uses GET /api/v2/moderation/moderation_rule/{id} and returns the full rule object including its conditions, actions, and metadata.

client.moderation.get_moderation_rule("rule_id")

Request Parameters

Response

Delete Rule

Delete a moderation rule by its ID. This endpoint uses DELETE /api/v2/moderation/moderation_rule/{id} and permanently removes the rule from the system.

client.moderation.delete_moderation_rule("rule_id")

Request Parameters

Response

Query Rules

Query moderation rules with optional filters, sorting, and pagination. This endpoint uses POST /api/v2/moderation/moderation_rules and supports standard query patterns for listing and searching rules.

client.moderation.query_moderation_rules(
    filter={"enabled": True},
    sort=[{"field": "created_at", "direction": -1}],
    limit=10,
)

Request Parameters

Response

Rule Actions Reference

The following table lists all available action types that can be assigned to a moderation rule. Each action defines what happens when the rule conditions are met.

Global vs policy-specific rules

Global rules

Global rules apply to all the content in your application, as long as it reaches the moderation system.

{
  "name": "Global Spam Detection",
  "description": "Applies to every policy",
  "team": "moderation",
  "config_keys": [], // Empty array = global rule
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    // ... conditions
  ],
  "logic": "AND",
  "action": {
    // ... action definition
  }
}

Policy-specific rules

These rules only run for the policies you list in config_keys.

E.g., if you have a rule that only applies to chat, you can set the config_keys to ["chat:messaging", "chat:support"], then counters will only be counted for messages sent in the channel types mentioned.

{
  "name": "Chat-Only Rule",
  "description": "Only applies to chat policies",
  "team": "moderation",
  "config_keys": ["chat:messaging", "chat:support"], // These policies only
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "12h",
  "conditions": [
    // ... conditions
  ],
  "logic": "AND",
  "action": {
    // ... action definition
  }
}

Basic rule structure

Every rule has three main parts:

1. Conditions: What behavior to watch for
2. Threshold: How many violations before taking action
3. Action: What to do when the threshold is reached

Example: Complete Rule Structure

{
  "name": "Spam Detection",
  "description": "Detects and bans users for spam behavior",
  "team": "moderation",
  "config_keys": ["chat:messaging", "chat:support"],
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    {
      "type": "text_rule",
      "text_rule_params": {
        "threshold": 5,
        "time_window": "1h",
        "llm_harm_labels": {
          "SCAM": "Fraudulent content, phishing attempts, or deceptive practices",
          "PLATFORM_BYPASS": "Content that attempts to circumvent platform moderation systems"
        }
      }
    },
    {
      "type": "content_count_rule",
      "content_count_rule_params": {
        "threshold": 50,
        "time_window": "1h"
      }
    }
  ],
  "logic": "OR",
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 3600,
      "reason": "Spam behavior detected",
      "shadow_ban": false,
      "ip_ban": false
    }
  }
}

This rule:

• Watches for spam and advertising content
• Triggers when a user posts 5+ spam messages within 1 hour or 50+ messages within 1 hour
• Bans the user for 1 hour when triggered

Condition types

These are the conditions you can put on a rule. Send them on Upsert Rule. A rule can have at most 5 conditions, and a policy at most 3 rules.

Every condition type. Conditions in one rule combine with AND or OR. The sections after the table document the types that take extra fields.

Reaction velocity

user_reaction_count is a user rule. It fires when one user sends too many reactions in a window (app-wide, not per channel). A reaction has no text to score, so message rules never see this.

count picks the unit:

• reactions (default): every reaction event
• reacted_messages: each message they reacted to counts once. Stacking several reaction types on one post is still 1.

{
  "type": "user_reaction_count",
  "user_reaction_count_params": {
    "threshold": 10,
    "time_window": "1m",
    "count": "reacted_messages"
  }
}

Use a user action (ban, flag the user, or a webhook). This only runs when a reaction is moderated.

Identical images

user_identical_image_count is a user rule. It counts how many times the same user posts the same image. Identity comes from the image bytes Stream already downloads for moderation, not the CDN URL, so a re-upload still matches.

{
  "type": "user_identical_image_count",
  "user_identical_image_count_params": {
    "threshold": 3,
    "time_window": "5m",
    "match": "exact"
  }
}

Images that cannot be fetched are skipped (fail-open).

Flood identical and similar

rule_type: "flood" is for repeated copy. Conditions are flood_identical (exact text after normalization, or media when there is no text) and flood_similar (near-duplicate text). Both default to per user. Actions are the content actions (flag, remove, shadow_block) and webhook_only. There is no cooldown: with a content action, once the threshold is hit every further match is actioned. With webhook_only, the rule sends moderation_rule.triggered once each time the count reaches a multiple of threshold (100, 200, 300... for a threshold of 100), and cross-user rules list the senders since the previous webhook in matched_user_ids. See Rule-triggered webhooks.

{
  "type": "flood_identical",
  "flood_identical_params": {
    "threshold": 5,
    "time_window": "30s",
    "track_across_users": true,
    "min_text_length": 20,
    "allowlist": ["gg"]
  }
}

flood_similar uses the same threshold, time_window, and allowlist, plus similarity_distance (1 to 16). It has no across-users option.

This is separate from policy flood_config, which stays per user and has no track_across_users or min_text_length.

Custom properties (Stream Chat and Feeds only)

content_custom_property matches a key on the moderated entity. Stream Chat sends message.custom. Stream Feeds sends activity and comment custom. A rule on audience_rating can match a message, a post, or a comment. Other products do not send this field.

{
  "type": "content_custom_property",
  "content_custom_property_params": {
    "property_key": "audience_rating",
    "operator": "eq",
    "expected_value": "kids"
  }
}

Operators: exists, not_exists, eq, ne, gt, gte, lt, lte, contains, not_contains.

To act on how often a user sends matching custom values, use content_custom_property_count with threshold and time_window.

Country

content_country_code matches the countries the content is aimed at: country_codes on Check and Analyze, or the deprecated country_code.

{
  "type": "content_country_code",
  "content_country_code_params": {
    "operator": "in",
    "country_codes": ["DE", "AT"]
  }
}

eq and ne take exactly one code; in and not_in take one or more. country_codes is required, and every entry must be an ISO 3166-1 alpha-2 code.

Content with several countries matches when any of them qualifies, so ne with ["US"] does not fire for content aimed at ["US", "DE"]. Content with no text or media, such as a reaction, never matches.

Time windows

Counting conditions accept 15s, 30s, 1m, 5m, 30m, 1h, 24h, 7d, and 30d. Flood conditions use a shorter set: 15s, 30s, 1m, 2m, 3m, 5m, 10m, 15m, 30m, and 1h. Live video cooldowns are 5s, 10s, 1m, 5m, and 10m.

Cooldown Periods

The Rule Builder supports cooldown periods to prevent immediate re-triggering of rules after an action has been taken. This is particularly useful when users are banned and then unbanned by administrators.

When a rule with a cooldown period is triggered and an action is taken (like banning a user), the system records this action with an expiration time. During the cooldown period, the same rule will not trigger again for that user, even if they continue to violate the conditions.

Configuration

Add a cooldown_period field to the rule:

{
  "name": "Spam Detection with Cooldown",
  "description": "Spam detection rule with 24h cooldown",
  "team": "moderation",
  "config_keys": [],
  "rule_type": "user",
  "enabled": true,
  "cooldown_period": "24h",
  "conditions": [
    // ... conditions
  ],
  "action": {
    "type": "ban_user",
    "ban_options": {
      "duration": 3600,
      "reason": "Spam behavior detected",
      "shadow_ban": false,
      "ip_ban": false
    }
  }
}

Example Scenario

1. User violates rule: User posts 5 spam messages in 1 hour
2. Rule triggers: User gets banned for 1 hour
3. Admin unbans user: Administrator manually unbans the user
4. User posts again: User immediately posts more spam messages
5. Cooldown active: Rule does not trigger again due to 24-hour cooldown
6. After cooldown: User can trigger the rule again after 24 hours