Previews, simulations and replays

A preview runs the same evaluation as live traffic without recording a claim. Simulations and replays reuse the evidence your past evaluations retained and apply a policy to it, so a changed result comes from your policy change. Use them to see how AbuseZero will decide before anything changes for a real user.

Preview an evaluationCopy Anchor Link

POST /v1/evaluation-previews · Scope simulations:run · Requires Idempotency-Key

Also available as abusezero evaluations preview in the AbuseZero CLI, abusezero_preview_evaluation on the AbuseZero MCP server and previewEvaluation() in the AbuseZero Node.js SDK.

Runs a complete evaluation and returns the result without recording anything. The preview creates no evaluation, claim or outcome, and never affects a later evaluation.

Request bodyCopy Anchor Link

The same body as Create an evaluation.

ExampleCopy Anchor Link

import { randomUUID } from "node:crypto";

const preview = await abusezero.previewEvaluation(
  {
    benefit: "pro_trial",
    claim_id: "preview_user_4821",
    subject: { external_id: "user_4821", email: "jordan@example.com" },
    context: { ip: "203.0.113.42" },
  },
  randomUUID(),
);

Replace the example IP address with the user's public address. 203.0.113.42 comes from a range reserved for documentation, and AbuseZero rejects documentation, private and other non-routable addresses with IP_NOT_ROUTABLE.

ResponseCopy Anchor Link

Returns 201.

{
  "object": "evaluation_preview",
  "preview": true,
  "result": "deny",
  "risk": { "score": null, "band": "not_assessed" },
  "reason": {
    "code": "prior_claim_user",
    "message": "This user already received this benefit."
  },
  "inputs": {
    "email": "received",
    "ip": "received",
    "user_id": "received",
    "phone": "missing",
    "payment": "missing",
    "device": "missing",
    "browser": "missing"
  }
}

A preview can also return { "object": "evaluation_preview", "status": "skipped", "reason": … } when the workspace can't run it. See Skipped evaluations.

ErrorsCopy Anchor Link

Run a simulationCopy Anchor Link

POST /v1/simulations · Scope simulations:run

Also available as abusezero simulations run in the AbuseZero CLI, abusezero_simulate_sequence on the AbuseZero MCP server and simulate() in the AbuseZero Node.js SDK.

Runs a benefit's most recent evaluations again, one after another, under the policy you choose, as if that policy had been active at the time. The sequence starts from an empty history, and each step sees the claims the simulation allowed before it, so a simulation shows how a policy handles repeat claims across a sequence.

Simulations use evaluations whose request details are still retained. They apply the chosen policy and the benefit's current settings, not your allow and block list entries. They use no credits and change nothing.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

const simulation = await abusezero.simulate({
  benefit_id: "ben_5b2e9c41-7d3a-4f68-a1c0-9e8d7b6a5f24",
  policy_key: "strict",
});

ResponseCopy Anchor Link

Returns 201.

{
  "object": "simulation",
  "data": [
    {
      "step": 1,
      "evaluation": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
      "result": "allow",
      "reason": {
        "code": "default_allow",
        "message": "No rule matched, so the policy's default allowed this claim."
      }
    },
    {
      "step": 2,
      "evaluation": "eval_8a1d4f20-6c3b-4e57-b9d2-0f7e6a5c3b18",
      "result": "deny",
      "reason": {
        "code": "prior_claim_email",
        "message": "An earlier claim used this email address."
      }
    }
  ]
}

The benefit's current protection mode applies. In observe mode, every result is allow.

ErrorsCopy Anchor Link

Run a replayCopy Anchor Link

POST /v1/replays · Scope simulations:run

Also available as abusezero simulations replay in the AbuseZero CLI, abusezero_replay_evaluations on the AbuseZero MCP server and replay() in the AbuseZero Node.js SDK.

Re-decides a benefit's most recent evaluations under the policy you choose, using what each evaluation recorded, and shows every result that would change. Save a change as a draft policy and replay it before you assign it to a benefit.

Replays make no new lookups. They apply the chosen policy and the benefit's current settings to each evaluation's retained record, not your allow and block list entries. They use no credits and change nothing.

Request bodyCopy Anchor Link

ExampleCopy Anchor Link

const replay = await abusezero.replay({
  benefit_id: "ben_5b2e9c41-7d3a-4f68-a1c0-9e8d7b6a5f24",
  policy_key: "trial_protection",
});

const rows = replay.data as { evaluation: string; changed: boolean }[];
const changed = rows.filter((row) => row.changed);

ResponseCopy Anchor Link

Returns 201.

{
  "object": "replay",
  "limit": 500,
  "data": [
    {
      "evaluation": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
      "original": "allow",
      "replayed": "allow",
      "changed": false
    },
    {
      "evaluation": "eval_d2b7f9a4-5e1c-4a38-9f6d-7c3e1b8a0d52",
      "original": "allow",
      "replayed": "deny",
      "changed": true
    }
  ]
}

The benefit's current protection mode applies. In observe mode, every replayed result is allow.

ErrorsCopy Anchor Link

Next stepsCopy Anchor Link