---
title: "Evaluate a card against an agent's historical traces"
method: POST
path: "/policies/evaluate/historical"
tags: ["Policy"]
---

# Evaluate a card against an agent's historical traces

`POST /policies/evaluate/historical`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/policies/evaluate/historical`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`

Replay an agent's recent AIP traces through the policy derived from a card to identify what would have been blocked, escalated, or flagged. By default the agent's current canonical alignment card is used; supply `card_json` to dry-run a hypothetical card instead. Useful for understanding the impact of a card/policy change before rolling it out. No standalone policy document is accepted (UC-8).

## Request body

- object
  - `agent_id` string, required: Agent whose historical traces will be replayed. The caller must be an owner, admin or member of the agent's org; otherwise the response is the same 404 as for an unknown agent.
  - `card_json` object: Optional hypothetical alignment card to evaluate against. If omitted, the agent's current canonical card is used (404 if the agent has none and no card_json is supplied).
  - `limit` integer: Maximum number of recent traces to evaluate (capped at 200).

## Response `200`

Historical evaluation result

- object
  - `agent_id` string, required
  - `card_id` string: Card the traces were evaluated against.
  - `total_traces` integer: Number of traces returned by the evaluation.
  - `results` object[]: Per-trace verdicts (or {skipped:true} for traces with no tool calls).
    - `trace_id` string
    - `verdict` string
    - `violations` object[]
    - `warnings` object[]
    - `skipped` boolean
  - `summary` object
    - `pass` integer
    - `warn` integer
    - `fail` integer
    - `skipped` integer
  - `message` string: Present only when the agent has no historical traces.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Cross-origin write refused (`cross_origin_rejected`). A state-changing request that carries the browser session cookie must come from a first-party origin (`Origin`, or failing that `Referer`) and must not send a form-style body (text/plain, urlencoded, multipart) the operation does not declare. Bearer and API-key callers are never subject to this check.
- `404`: Resource not found
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/e13923bd55ef?raw)