---
title: "replayPolicy"
description: "Replay recorded agent traffic against a policy"
canonical: "https://pgbeam.com/docs/ts-sdk/policies/replayPolicy"
last-updated: "2026-10-20T17:41:58.000Z"
---

# replayPolicy

> Replay recorded agent traffic against a policy

URL: https://pgbeam.com/docs/ts-sdk/policies/replayPolicy

{/* Auto-generated from OpenAPI. Do not edit. Run `pnpm generate:sdk-docs` to regenerate. */}

Replays the project's recorded agent audit traffic against a candidate policy (either a draft supplied inline or an existing policy referenced by id) and reports what would change: which queries that ran would now be blocked, which blocked queries would now be permitted, and which results would be masked or row-filtered. Traffic is deduplicated by normalized query shape, newest first, and every statement is evaluated through the data plane's own policy engine, so the verdicts match real enforcement. Stateful checks (budgets, approvals, write-mode routing) are reported as informational notes on each result, not verdicts. This endpoint reads only the audit log; it never connects to the upstream database and persists nothing.

## Usage

```typescript
const result = await api.policies.replayPolicy({
    pathParams: { project_id: "prj_xxx" },
    body: {
      ,
    },
  });
```

## Parameters

| Parameter             | Type                 | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pathParams.project_id | `string`             | Yes      | Unique project identifier (prefixed, e.g. prj_xxx).                                                                                                                                                                                                                                                                                                                                                              |
| body.policy_id        | `string`             | No       | ID of an existing saved policy profile to replay against.                                                                                                                                                                                                                                                                                                                                                        |
| body.policy           | `PolicyProfileInput` | No       | Mutable fields of a policy profile (used for create and update).                                                                                                                                                                                                                                                                                                                                                 |
| body.credential_id    | `string`             | No       | Restrict the replay to traffic recorded for one agent credential.                                                                                                                                                                                                                                                                                                                                                |
| body.bound_policy_id  | `string`             | No       | Restrict the replay to traffic recorded for the agent credentials currently bound to this policy profile. Use it to preview a change to a live policy against the traffic that policy actually governs: without it the replay covers every credential in the project, including credentials bound to other profiles, whose behaviour saving this candidate cannot change. Mutually exclusive with credential_id. |
| body.start_ts         | `string`             | No       | Start of the traffic window (inclusive). Defaults to 7 days before end_ts.                                                                                                                                                                                                                                                                                                                                       |
| body.end_ts           | `string`             | No       | End of the traffic window (exclusive). Defaults to now.                                                                                                                                                                                                                                                                                                                                                          |
| body.limit            | `number`             | No       | Maximum number of distinct queries to replay, newest first. Traffic is deduplicated by normalized query hash before evaluation.                                                                                                                                                                                                                                                                                  |

## Response

`Promise<PolicyReplayResult>`: the replay summary and per-query decisions.

## Example

```typescript
import { PgBeamClient } from "pgbeam";

const client = new PgBeamClient({
  token: "pbu_...",
  baseUrl: "https://api.pgbeam.com",
});

const result = await client.api.policies.replayPolicy({
  pathParams: { project_id: "prj_xxx" },
  body: {
      ,
    },
});
```

## Errors

| Status | Description                                                                                                                                                                                                                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | The request was rejected. `code` is `INVALID_INPUT`, and `errors` names the offending fields when the failure was a validation one.                                                                                                                                                                   |
| 401    | Missing or invalid authentication. `code` is `UNAUTHORIZED`.                                                                                                                                                                                                                                          |
| 403    | The caller is authenticated but not allowed to perform this operation. `code` is `FORBIDDEN` when the caller's role is insufficient, and `PLAN_LIMIT_REACHED` when the organization's plan is what stands in the way. The two are answered differently, so branch on the code rather than the status. |
| 404    | The resource does not exist, or the caller is not entitled to know that it does. `code` is `NOT_FOUND`.                                                                                                                                                                                               |
| 413    | The request body exceeds the 2 MB limit. `code` is `PAYLOAD_TOO_LARGE`.                                                                                                                                                                                                                               |
| 415    | The request body is not JSON, or carries a body without declaring a Content-Type. `code` is `UNSUPPORTED_MEDIA_TYPE`.                                                                                                                                                                                 |
| 429    | Rate limited. `code` is `RATE_LIMITED`.                                                                                                                                                                                                                                                               |
| 500    | The request failed for a reason on our side. `code` is `INTERNAL_ERROR`. Quote `request_id` when reporting it.                                                                                                                                                                                        |