# Review Queue

## Overview

The Review Queue is the central hub for moderators. It contains content flagged by automated moderation engines or reported by users. Moderators review items in the queue and take actions such as approve, delete, and ban. `submit_action` is how you apply a decision to an item; see [Actions](https://getstream.io/moderation/docs/php/content-moderation/actions/).

In the dashboard, the **Inbox** tab shows items waiting for review and the **Reviewed** tab shows items a moderator has already acted on.

## Query Review Queue

Use this endpoint to retrieve items from the review queue. It supports filtering by content type, review status, moderation category, and more. You can also sort results, paginate through them, and lock items to prevent multiple moderators from reviewing the same item simultaneously.

`POST /api/v2/moderation/review_queue`

`filter` is a map. Built-in keys:

`id`, `created_at`, `updated_at`, `reviewed_at`, `completed_at`, `archived_at`, `escalated_at`, `date_range`, `type`, `status`, `entity_type`, `entity_id`, `entity_creator_id`, `entity_creator_name`, `content_text`, `queue_type`, `language`, `teams`, `latest_moderator_action`, `user_report_reason`, `recommended_action`, `reviewed`, `appeal`, `appeal_status`, `appeal_id`, `flagged_user_id`, `has_image`, `has_video`, `has_text`, `has_audio`, `flags_count`, `severity`, `confidence_score`, `bounce_count`, `category`, `label`, `reporter_type`, `reporter_id`, `config_key`, `ai_text_severity`, `channel_cid`, `channel_id`, `escalated`, `escalated_by`, `escalation_priority`, `escalation_reason`

Any other key is matched against `moderation_payload.custom`. `filter_config.filterable_custom_keys` lists the custom keys the app exposes as chips.

`content_text` is special: `$q` is a keyword search (terms ANDed, no adjacency). `$eq` and `$in` match the text exactly and are unindexed, so scope them with `date_range`.

Sort is allowed on `created_at` only. The response field is `items`. Pass `next` back to load the following page.

To review only flagged content and skip items the engines already removed, filter on `recommended_action`:

```js label="Node.js"
const response = await client.moderation.queryReviewQueue({
  filter: { recommended_action: "flag", reviewed: false },
  sort: [{ field: "created_at", direction: -1 }],
});
```

In the dashboard, set the **Action** filter to `flag` and bookmark the URL.

```php label="PHP"
$response = $client->queryReviewQueue(new QueryReviewQueueRequest(
    filter: (object)['entity_type' => 'stream:chat:v1:message', 'reviewed' => false],
    sort: [new SortParam(field: 'created_at', direction: -1)],
    limit: 20,
));
```

### Filter Parameters

| Key                | Type     | Description                                                                                                             |
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| id                 | string   | Filter by specific review queue item ID.                                                                                |
| created_at         | datetime | Filter by creation date.                                                                                                |
| updated_at         | datetime | Filter by last update date.                                                                                             |
| status             | string   | Review queue item status: `complete`, `partial`, or `flagged`.                                                          |
| entity_type        | string   | Filter by entity type (e.g., `stream:chat:v1:message`, `stream:user`, `stream:feeds:v2:activity`).                      |
| entity_id          | string   | Filter by entity ID.                                                                                                    |
| entity_creator_id  | string   | Filter by the user who created the content.                                                                             |
| reviewed           | boolean  | Filter by review status. `false` for unreviewed items.                                                                  |
| has_text           | boolean  | Filter items containing flagged text.                                                                                   |
| has_image          | boolean  | Filter items containing flagged images.                                                                                 |
| has_video          | boolean  | Filter items containing flagged video.                                                                                  |
| category           | string   | Filter by moderation engine: `ai_text`, `ai_image`, `automod_toxicity`, `automod_platform_circumvention`, `block_list`. |
| label              | string   | Filter by classification label, such as `SPAM` or `HATRED`.                                                             |
| recommended_action | string   | `keep`, `flag`, `remove`, `shadow`, `bounce`, `bounce_flag`, `bounce_remove`, `mask`, or `mask_flag`.                   |
| reporter_type      | string   | Who flagged the item: `moderator`, `user`, `automod`, or `serverside`.                                                  |
| reporter_id        | string   | Filter by specific reporter user ID.                                                                                    |
| date_range         | string   | Filter by date range. Format: `"2026-01-01T00:00:00_2026-12-31T00:00:00"`.                                              |
| appeal             | boolean  | Filter items that have (`true`) or don't have (`false`) an appeal.                                                      |
| appeal_status      | string   | Filter by appeal status: `submitted`, `accepted`, `rejected`.                                                           |
| user_report_reason | string   | Filter items flagged by users with a given reason.                                                                      |

### Request Parameters

| Key           | Required | Type    | Description                                                                                     |
| ------------- | -------- | ------- | ----------------------------------------------------------------------------------------------- |
| filter        | false    | object  | Filter conditions (see above).                                                                  |
| sort          | false    | array   | Sort parameters. Supported fields: `id`, `created_at`, `updated_at`.                            |
| limit         | false    | number  | Maximum items to return (default 20).                                                           |
| next          | false    | string  | Cursor for pagination.                                                                          |
| lock_items    | false    | boolean | When true, locks returned items to prevent other moderators from reviewing them simultaneously. |
| lock_count    | false    | number  | Number of items to lock (1-25). Only used with `lock_items`.                                    |
| lock_duration | false    | number  | Lock duration in seconds.                                                                       |
| stats_only    | false    | boolean | When true, returns only queue statistics without items.                                         |

### Response

| Key   | Type   | Description                                |
| ----- | ------ | ------------------------------------------ |
| items | array  | List of review queue items.                |
| next  | string | Next cursor for pagination.                |
| stats | object | Queue statistics (counts by content type). |

## Count Review Queue

Use this endpoint to show how many items a review queue filter matches, for example a total on a dashboard tab or saved view. It takes the same `filter` as [Query Review Queue](#query-review-queue) and counts exactly the items that query lists, with the same permissions and team scoping.

`POST /api/v2/moderation/review_queue/count`

Counts are exact up to 50,000. Above that, `capped` is `true` and `total` is a lower bound. The first request for a filter tries to count it right away. If that can't finish quickly, the response has `pending: true`, `total: 0` and no `computed_at`: treat that as "not counted yet", not as an empty queue. After that, the count is kept up to date in the background while the filter is being requested. Whenever `pending` is `true`, the count is missing or out of date: show the count you have and request it again a few seconds later.

```php label="PHP"
$response = $client->countReviewQueue(new CountReviewQueueRequest(
    filter: (object)['entity_type' => 'stream:chat:v1:message', 'reviewed' => false],
));
```

### Request Parameters

| Key    | Required | Type   | Description                                                              |
| ------ | -------- | ------ | ------------------------------------------------------------------------ |
| filter | false    | object | Filter conditions, the same as [Query Review Queue](#filter-parameters). |

### Response

| Key         | Type    | Description                                                                                       |
| ----------- | ------- | ------------------------------------------------------------------------------------------------- |
| total       | number  | Number of items matching the filter. When `capped` is `true`, at least this many.                 |
| capped      | boolean | More items match than are counted exactly (50,000), so `total` is a lower bound.                  |
| pending     | boolean | The count is missing or out of date because the queue changed since it was counted.               |
| computed_at | number  | When the count was computed, as a Unix timestamp in nanoseconds. Absent when no count exists yet. |

## Get Review Queue Item

Retrieve a specific review queue item by its ID. This returns the full item details including the entity content, moderation flags, and any actions already taken.

`GET /api/v2/moderation/review_queue/{id}`

```php label="PHP"
$response = $client->getReviewQueueItem('item_id');
```

### Request Parameters

| Key | Required | Type   | Description               |
| --- | -------- | ------ | ------------------------- |
| id  | true     | string | The review queue item ID. |

### Response

| Key  | Type   | Description                              |
| ---- | ------ | ---------------------------------------- |
| item | object | The review queue item with full details. |

## Moderator feedback

`POST /api/v2/moderation/submit_moderation_feedback` records that a classification was wrong. It does not change the item. `message`, `published_at`, and `reference` are required.

```js label="Node.js"
await client.moderation.submitModerationFeedback({
  message: "the moderated text",
  published_at: "2026-10-20T13:13:38Z",
  reference: "provider-reference",
  current_labels: ["HATRED"],
  current_recommended_action: "remove",
  expected_labels: ["INSULT"],
  expected_recommended_action: "flag",
});
```

---

For the most recent version of this documentation, visit [https://getstream.io/moderation/docs/php/content-moderation/review-queue/](https://getstream.io/moderation/docs/php/content-moderation/review-queue/).