Overview
Fiddler implements the LiteLLM Generic Guardrail API spec, allowing you to plug Fiddler’s guardrails directly into a LiteLLM proxy gateway. Once configured, every LLM request routed through the proxy is checked by Fiddler — in the recommendedpre_call mode, before it ever reaches the model.
This page takes you from a clean LiteLLM installation to a verified block, redact, and allow decision in about ten minutes.
Pick your path before you start:
The configuration on this page checks for:
- Secrets — API keys, tokens, credentials, and connection strings
- PII — personally identifiable information (emails, phone numbers, SSNs, credit cards, etc.)
How It Works
Prerequisites
Before you start, you need:- A Fiddler environment with Guardrails enabled.
Your instance base URL (for example
https://your-company.fiddler.ai) is theapi_baseprefix. If the endpoint returns HTTP 403, Guardrails is not enabled for your deployment — contact Fiddler. - A Fiddler API key, created under Settings → Credentials.
- LiteLLM ≥ 1.91.0 (this page was verified against LiteLLM 1.96.2).
- An LLM provider API key — the quick start uses OpenAI.
- uv installed, or another way to run the LiteLLM proxy.
- Network access from the proxy host to your Fiddler instance and your LLM provider, over HTTPS.
Quick Start
1
Set Environment Variables
FIDDLER_AUTH_HEADER exists because the config below references it with os.environ/FIDDLER_AUTH_HEADER —
the key stays in your environment and never appears in the config file.2
Create a Minimal config.yaml
/beta/litellm_basic_guardrail_api to api_base automatically.
The full endpoint called is https://<your-fiddler-instance>/v3/guardrails/litellm/beta/litellm_basic_guardrail_api.3
Start LiteLLM
"fastapi<0.140.7" pin works around a LiteLLM 1.96.x dependency gap:
its declared FastAPI range admits versions that removed an internal import the proxy still uses,
so an unpinned install fails at startup with ImportError: cannot import name 'get_flat_dependant'.
Remove the pin once upstream ships a fix.
To run the proxy in Docker instead, see the
LiteLLM Docker guide —
the guardrails configuration above is identical.4
Verify Block, Redact, and Allow
1. A synthetic secret is blocked. Secrets use Expected response — HTTP 400 with the guardrail’s reason:2. Synthetic PII is redacted in place. PII uses Expected: HTTP 200 and a normal model response.
The redaction happens between the proxy and the model, so to see it directly,
call the Fiddler endpoint with the same text:Expected response — the exact sanitized text the model would receive:3. Benign traffic passes through. Ordinary requests reach the model unchanged:Expected: HTTP 200 with a normal completion (for example, “The capital of France is Paris.”).You now have a working guardrail: secrets are blocked with HTTP 400,
PII is redacted before the model sees it, and clean traffic is unaffected.
mode: block, so the request never reaches the model:mode: redact, so the request succeeds
and the model receives sanitized text:What This Configuration Enables
The quick-start configuration runs exactly two checks on every request, before the LLM call:
Check selection is explicit: only the checks you list with
enabled: true run.
If you omit additional_provider_specific_params entirely, server-side defaults apply instead.
Always configure checks explicitly so the behavior matches this page.
The three failure controls in the config are also explicit, even where they match the default,
so that a secure posture survives upstream default changes:
See Failure Behavior for what each control covers and how they compose.
What Gets Scanned
- Free-text messages — user, assistant, and system message text forwarded by LiteLLM in
texts[]. Withmode: redact, detected values are replaced in place (for example[REDACTED EMAIL]). - Tool-call arguments — structured JSON in
tool_calls[].function.arguments. Detections always block, because redacting inside structured JSON is unsafe — see Tool Call Handling.
texts and tool_calls[].function.arguments are scanned.
Other request fields (tool definitions, images, headers, metadata) are accepted for protocol
compatibility but never scanned — see the API Reference.
Supported Modes and Endpoints
Fiddler supports all three LiteLLM guardrail modes. Setmode in your proxy config to one or more of:
during_call hides guardrail latency behind the LLM round-trip:
the response is held until the check completes,
but because the LLM call has already started, the input cannot be modified.
Use it only when block-or-allow is sufficient.
You can combine modes. For example, mode: [pre_call, post_call] scans both input and output:
Supported Endpoints
The guardrail runs on LiteLLM proxy endpoints that carry text content, including/v1/chat/completions (OpenAI format) and /v1/messages (Anthropic format).
LiteLLM extracts text from the request and forwards it to the Fiddler endpoint
regardless of the upstream provider format,
and applies redacted text before the provider call on both endpoint families.
Per-Request Control
Withdefault_on: true (the quick-start configuration), the guardrail runs on every request automatically.
When default_on is omitted, LiteLLM treats it as false, so set it explicitly.
Selective Activation
Setdefault_on: false in the proxy config,
then activate the guardrail on individual requests by passing guardrails in the request body:
"guardrails": ["fiddler"] bypass the guardrail entirely —
the Fiddler endpoint is never called.
Check Reference
Each check is configured entirely in the LiteLLM proxy’sadditional_provider_specific_params:
enabled(true/false) — whether the check runs at all.mode(redact/block) — what happens on a detection. The default isredactfor both checks.thresholdandentities(PII only) — detection sensitivity and entity selection.
Secrets
Detects credentials, API keys, and tokens.PII
Detects personally identifiable information.entities switches the check to exactly the entities you list — it replaces the default set
rather than extending it.
For the available entity types, see the PII Detection tutorial.
Detection is confidence-based:
values below threshold are left untouched,
so entities like personal names may pass through at the default threshold
while high-precision entities like emails and phone numbers redact reliably.
Failure Behavior
Three settings control what happens when a guardrail check cannot complete. Two belong to LiteLLM and one to Fiddler, and each observes a different class of failure.How the LiteLLM Controls Compose
LiteLLM lets a failed guardrail call through when either condition holds: the failure is in the unreachable class andunreachable_fallback: fail_open,
or fail_on_error: false.
There is no conflict case — fail-open wins if either setting grants it.
In practice:
- With the quick-start values (
fail_closed+true), every guardrail call failure rejects the request. unreachable_fallback: fail_openwithfail_on_error: truetolerates outages (unreachable endpoint, gateway 502/503/504) while still rejecting on malformed responses and other non-2xx errors.fail_on_error: falselets every guardrail failure through, regardless ofunreachable_fallback— it is the broadest bypass and deserves deliberate consideration.
fail_on_error: false cannot override a valid decision:
a successfully parsed action: BLOCKED response always blocks.
What the Client Sees
A blocked request is a 400 for non-streaming calls and for streaming calls blocked before the first chunk;
a block that occurs mid-stream cannot change the already-sent status line.
Fiddler’s failure_mode
failure_mode controls what happens when an internal check fails to complete —
an inference timeout, an inference server error, or content that exceeds the scan limit.
LiteLLM cannot see these failures because the Fiddler endpoint still returns HTTP 200
with a normal action, so the LiteLLM-side controls never fire.
The default is
open for backward compatibility.
For security-sensitive deployments, set failure_mode: closed, as the quick start does.
With all three controls at their secure values
(fail_closed, fail_on_error: true, failure_mode: closed),
no request bypasses scanning, whether the failure is at the transport, protocol, or detector level.
One caveat: an unexpected exception in the Fiddler pipeline under failure_mode: open
surfaces as an HTTP 5xx rather than a 200,
and is then handled by LiteLLM’s fail_on_error.
A deliberate fail-open posture (failure_mode: open plus fail_on_error: false) trades
protection for availability:
traffic keeps flowing during a guardrail outage, unscanned.
Choose it only for traffic where an unscanned request is acceptable,
and monitor the LiteLLM logs for the fail-open CRITICAL entries.
Timeouts
The guardrail check has one customer-facing timeout: the wall-clock deadline for the whole check pipeline, set per request viatimeout (seconds) in additional_provider_specific_params:
failure_mode governs the outcome:
under open the request proceeds unscanned, under closed it is blocked.
Text Length Limits
The maximum total text length scanned per request is controlled by theGUARDRAILS_MAX_TEXT_LENGTH environment variable on the Fiddler server
(default: 50,000 characters).
Messages are concatenated until the cap is reached;
segments beyond the cap are skipped, never truncated mid-segment:
Tool Call Handling
Whentool_calls contain PII or secrets, Fiddler always blocks rather than redacts.
Why: tool-call arguments are structured JSON that the downstream application will parse and execute.
Replacing a value like an email address with [REDACTED EMAIL] would cause send_email
to attempt delivery to a nonsensical address —
producing unpredictable behavior that is worse than blocking outright.
Example — blocked tool call:
Tool Results
Fiddler does not claim redaction coverage for tool results. Whether tool result content reaches the scanner depends on the LiteLLM gateway: LiteLLM must include the tool result in thetexts[] it forwards to Fiddler.
This is not guaranteed for all gateway configurations or versions,
and is known not to work on customer-managed or self-hosted gateways that do not extract
role:tool / tool_result messages into texts[].
Additionally, tool results are typed as any in the GenAI semantic conventions —
they can be plain strings, JSON objects, or arrays.
Even when the text does reach the scanner,
in-place character-span redaction on a serialized JSON payload is not safe
if the downstream application re-parses the result as structured data.
For reliable protection against secrets in tool output,
use mode: block on secrets and treat tool result content as untrusted.
Troubleshooting
For issues with a specific request, the safe identifiers to include in a support ticket are
litellm_call_id and litellm_trace_id — never include prompts, completions, or credentials.
API Reference
Endpoint
Authorization: Bearer <your-fiddler-api-key>
Request
texts and tool_calls[].function.arguments are scanned by guardrail checks.
The remaining fields are accepted for LiteLLM protocol compatibility,
and unknown fields are ignored.
Response
Fields withnull values are omitted from the wire.
The response shape varies by action:
Guardrail decisions are observable.
With the Fiddler OTel callback enabled on the same proxy,
each guardrail execution is traced as its own span next to the model call,
so every block or redact decision — and its reason — shows up in Explorer as an audit trail.
Next Steps
- Guardrails overview — understand the detection models behind these checks
- LiteLLM Integration — add tracing, token, and cost observability to the same proxy
- LiteLLM Generic Guardrail API spec — the upstream contract this integration implements
- AgentGateway Guardrails — the same Fiddler checks via AgentGateway’s webhook protocol
- Kong AI Gateway Guardrails — Fiddler guardrails via Kong (block-only, no masking)