Run an evaluator as a guardrail

Run an evaluator inline and gate on one boolean. Same call as the evaluate path with as_guardrail set: every outcome carries passed, so an evaluator that skips or fails does not block the request it was guarding. Check passed and let the request through when it is true.

POST /api/v1/guardrails/{evaluator}/evaluate

Run an evaluator as a guardrail

Python

import requests

url = "https://app.langwatch.ai/api/v1/guardrails/{evaluator}/evaluate"

payload = { "data": {} }
headers = {
    "X-Auth-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

200

{
  "status": "processed",
  "score": 123,
  "passed": true,
  "label": "<string>",
  "details": "<string>",
  "cost": {
    "currency": "<string>",
    "amount": 123
  },
  "raw_response": "<unknown>"
}

Authorizations

X-Auth-Token · string · header · required

Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.

Path Parameters

evaluator · string · required

Which evaluator to run. Either a built-in id (ragas/faithfulness), the slug of a monitor configured in this project, or evaluators/{slug|id} for a saved evaluator. GET /api/evaluations/list returns the built-in ids.

Body

application/json

data · object · required

What the evaluator scores. Which fields are required depends on the evaluator; its own entry under Built-in Evaluators lists them.

Show child attributes

trace_id · string | null

Attaches the result to a trace you already sent

evaluation_id · string | null

Supply your own id to make the call idempotent

evaluator_id · string | null

name · string | null

Overrides the name the result is recorded under

settings · object | null

Per-call overrides of the evaluator's settings. Anything omitted falls back to the saved evaluator or monitor, then to the evaluator's own defaults.

Show child attributes

as_guardrail · boolean | null · default: false

Evaluate as a guardrail: a skipped or failed evaluation answers passed rather than an error, so a caller can gate on one field. The /api/guardrails path sets this for you.

Response

200

application/json

The evaluator ran, declined, or failed. Branch on status; in guardrail mode passed is set on all three.

Option 1

Option 2

Option 3

status · string · required

Allowed value: "processed"

score · number

passed · boolean

label · string

details · string

cost · object

What running the evaluator cost

Show child attributes

raw_response · any

The evaluator's own output, unprocessed