Evaluations

Evaluations let you run a fixed batch of content through a moderation policy and see how it is handled. Re-run the same set after you change rules, filters, or LLM settings to see what improved or drifted.

Use them from the dashboard (Moderation → Configuration → Evaluations) or from the server-side SDKs. The dashboard is the easiest way to create sets, watch a run, and compare results. The API is the same surface the dashboard calls, so you can automate evaluations from CI or your own tooling.

Concepts

Replay vs a single policy

When you create a set you pick how rows are executed:

• A specific policy. Every item runs against that policy's current configuration.
• Replay. Omit config_key. Seeded items keep the policy they originally ran under. Deleted policies are skipped for those rows.

Pasted (hand-written) content has no original policy, so it always needs a policy selected.

How scoring works

1. The first completed run is the baseline. It has no pass/fail metrics of its own.
2. Later runs compare each row's labels and recommended action to the baseline (or, for replay sets seeded from production, to the original production outcome stored on the row).
3. Rows with no expectations (empty labels and empty recommended action) are unscored. The run still records actual labels and action so you can inspect them, but they are excluded from pass/fail totals.

A row fails when labels differ (label_mismatch), the recommended action differs (action_mismatch), the provider errors (provider_error), or the row's policy no longer exists (policy_not_found).

Billing and retention

Each item in a run executes real moderation calls (LLM, NLP, image checks, and so on) at standard rates, the same as production traffic.

Each set keeps the last 10 completed runs. Starting another after that deletes the oldest run and its per-row results. In-flight runs are not deleted.

Using the dashboard

1. Open Moderation → Configuration → Evaluations.
2. Click Create evaluation.
   • Give the set a name.
   • Choose a policy, or Replay to re-run each item under its original policy.
   • Sample your newest moderated production content (up to 1000 items), or paste content (one item per line).
3. Open the set and click Run evaluation. Confirm the dialog: this spends real moderation usage.
4. When the run completes, compare it to the baseline or to another run. Filter to drifted rows, inspect a row's labels and recommended action, and export results as CSV.

You can also open Evaluations already filtered to a policy from that policy's page.

Creating, running, and deleting evaluations requires full access to the app's moderation configuration privilege. Read-only users can view sets and results.

API

These methods are server-side only. They are not available from client-side SDKs.

Create an evaluation set

POST /api/v2/moderation/policy_tests/sets

Provide either rows or seed, not both. Names are unique per app.

The example below samples the newest production content for a policy. To paste items instead, pass rows (each with a text field). To replay each item under its original policy, omit config_key.

CreatePolicyTestSetResponse response = client.moderation()
    .createPolicyTestSet(CreatePolicyTestSetRequest.builder()
        .name("Hate-speech sample")
        .configKey("chat:messaging")
        .seed(PolicyTestSeedSpec.builder()
            .labels(List.of())
            .limit(100)
            .build())
        .build())
    .execute()
    .getData();

Request parameters

seed fields:

Row fields (when using rows, and also returned on seeded sets):

Response

If seeding matches no production data, the request fails. Broaden labels or moderate more content first.

List evaluation sets

GET /api/v2/moderation/policy_tests/sets

Each set in sets may include last_run so you can show last-run status and pass rate without a second request.

ListPolicyTestSetsResponse response = client.moderation()
    .listPolicyTestSets(ListPolicyTestSetsRequest.builder().limit(50).build())
    .execute()
    .getData();

Request parameters

Response

Get an evaluation set

GET /api/v2/moderation/policy_tests/sets/{id}

Returns set (including rows), recent_runs (newest first, capped at 10), and baseline_run_id once the first run has completed.

GetPolicyTestSetResponse response = client.moderation()
    .getPolicyTestSet("pts_...")
    .execute()
    .getData();

Request parameters

Response

Delete an evaluation set

DELETE /api/v2/moderation/policy_tests/sets/{id}

Cascades to runs and results. Fails if a run is still pending or running.

client.moderation().deletePolicyTestSet("pts_...").execute();

Request parameters

Start a run

POST /api/v2/moderation/policy_tests/sets/{id}/runs

The body is empty. Only one run may be in progress per set. When a new run is created, the oldest terminal runs beyond the 10-run cap are deleted.

StartPolicyTestRunResponse response = client.moderation()
    .startPolicyTestRun("pts_...")
    .execute()
    .getData();

Request parameters

Response

Get a run (and results)

GET /api/v2/moderation/policy_tests/runs/{id}

Poll this while status is pending or running. rows_completed / rows_total track progress. Per-row results are omitted until the run is terminal, so polling stays cheap.

GetPolicyTestRunResponse response = client.moderation()
    .getPolicyTestRun("ptr_...")
    .execute()
    .getData();

Request parameters

Response

Run object

metrics.totals:

metrics.by_label maps each label to { same, changed }. changed counts rows where that label was added or dropped versus the baseline. Rows where the label was absent in both runs are not counted.

Result object (terminal runs)

Compare two runs client-side: fetch both, join on row_index.

Recommended workflow

1. Create a set from recent production traffic for the policy you are about to change.
2. Run it once to capture a baseline (or rely on seeded production outcomes for replay).
3. Change the policy, rules, or filters.
4. Run the same set again and inspect drifted rows before you roll the change out further.