---
title: "Run Preview"
method: POST
path: "/api/simulator/preview"
tags: ["simulator"]
---

# Run Preview

`POST /api/simulator/preview`

## Request

- Base URL: `https://www.gateco.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://www.gateco.ai/api/simulator/preview`
- Auth: OAuth 2 (password, token URL `/api/auth/login`)

Execute a live search and apply policy evaluation to show per-result allow/deny.

Readiness guards:
- Entitlement: access_simulator feature (Growth+)
- Connector: must be connected with a valid search_config
- Principals: at least one active principal must exist in the org
- Policies: at least one active policy must exist in the org

Denied results never expose content_preview.
Emits a simulator_preview_executed audit event on success.

## Request body

- PreviewRequest: Request body for the live preview endpoint.
  - `principal_id` string, required
  - `connector_id` string, required
  - `query` string, required
  - `top_k` integer
  - `search_mode` 'vector' | 'keyword' | 'hybrid'
  - `alpha` number, nullable

## Response `200`

Successful Response

- PreviewResponse: Response from the live preview endpoint.
  - `outcome` string, required
  - `query` string, required
  - `principal_name` string, required
  - `connector_name` string, required
  - `search_mode` string, required
  - `total_results` integer, required
  - `allowed_results` object[], required
  - `denied_results` object[], required
  - `policy_trace` object[], required
  - `timing_ms` number, required

## Other responses

- `422`: Validation Error

---

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