Guardrail triggers

Package: agentrouter.guardrails.v1 Service: GuardrailTriggersService

Endpoints

List guardrail trigger events

Changed in v0.7.0 (new features): Every guardrail rule now carries a reference, a short read-only id such as GR-0142 that the database mints once and never rewrites. The guardrail rule APIs and each trigger evaluation return it beside the display_name, and the data plane receives it in its runtime configuration, so a platform operator reading a trigger has one id to quote. Existing rules were numbered in creation order, and a blocked caller's refusal body does not carry the reference yet.

Changed in v0.7.0 (new features): A guardrail trigger now reports one verdict for the whole event, which is blocked, redacted or would-have, resolved from its rule evaluations so an enforced block outranks an enforced redact and either outranks a monitor-mode hit that changed nothing. ListGuardrailTriggers filters on verdicts and returns a count for each one. The counts answer every filter on the request except verdicts itself, so a console showing the three as peers keeps all three counts on screen after a reader picks one.

What it does: Lists trigger events matching the specified filters.

Request fields:

Field	Required	Description
`customer_id`	no	Owning customer scope; defaults to caller's session customer when empty.
`project_id`	no	Owning project scope; defaults to caller's session project when empty.
`page`	no	Cursor-pagination inputs.
`guardrail_ids`	no	Filter to events for these guardrail ids.
`consumer_ids`	no	Filter to events for these consumer ids.
`resource_ids`	no	Filter to events for these resource ids.
`date_from`	no	Inclusive start of the time range to query.
`date_to`	no	Inclusive end of the time range to query.
`min_execution_duration_ms`	no	Filter to events with execution_duration_ms >= this value.
`max_execution_duration_ms`	no	Filter to events with execution_duration_ms <= this value.
`guardrail_types`	no	Filter to events for guardrails of these types.
`exclude_guardrail_types`	no	Exclude events for guardrails of these types.
`verdicts`	no	Filter to events whose verdict is one of these (tetrateio/fraser#9667). Empty returns every verdict, and TRIGGER_VERDICT_UNSPECIFIED entries are ignored rather than matching the events that resolved to no verdict. A value the server does not know is refused with INVALID_ARGUMENT.

Response fields:

Field	Required	Description
`triggers`	no	Trigger events matching the request filters, one page's worth.
`page`	no	Cursor-pagination outputs.
`total`	no	Total count of matching triggers across all pages.
`verdict_counts`	no	How many events resolved to each verdict, one entry per verdict including the ones that matched nothing (tetrateio/fraser#9667). Counted against every filter on the request EXCEPT `verdicts`, and `total` above obeys `verdicts` like the page does. A console renders the three verdicts as peers a reader picks between, so picking one must not drive the other two counts to zero and strand the reader on the filter they just chose. The three counts sum to at most the unfiltered total, since an event that resolved to no verdict is in none of them.

{"signatures":{"go":"c.GuardrailTriggers().ListGuardrailTriggers(ctx, \u0026guardrailsv1.ListGuardrailTriggersRequest{...})","python":"client.guardrailtriggers.listguardrailtriggers(...)","typescript":"client.guardrailtriggers.listguardrailtriggers({...})","cli":"tare api guardrails triggers list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","cli":"tare api guardrails triggers list","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/triggers","slug":"list-guardrail-trigger-events"}

Get a guardrail trigger event

What it does: Returns a single trigger event by id.

Request fields:

Field	Required	Description
`customer_id`	no	Owning customer scope; defaults to caller's session customer when empty.
`project_id`	no	Owning project scope; defaults to caller's session project when empty.
`id`	yes	Required: id of the trigger event to fetch.

Response fields:

Field	Required	Description
`trigger`	no	The requested guardrail trigger event.

{"signatures":{"go":"c.GuardrailTriggers().GetGuardrailTrigger(ctx, \u0026guardrailsv1.GetGuardrailTriggerRequest{...})","python":"client.guardrailtriggers.getguardrailtrigger(...)","typescript":"client.guardrailtriggers.getguardrailtrigger({...})","cli":"tare api guardrails triggers get \u003cid\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers/01H...\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","cli":"tare api guardrails triggers get \u003cid\u003e","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers/01H...\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/triggers/{id}","slug":"get-a-guardrail-trigger-event"}

Get guardrail trigger statistics

What it does: Returns aggregate statistics for trigger events in scope.

Request fields:

Field	Required	Description
`customer_id`	no	Owning customer scope; defaults to caller's session customer when empty.
`project_id`	no	Owning project scope; defaults to caller's session project when empty.

Response fields:

Field	Required	Description
`total_triggers`	no	Total number of trigger events in scope.
`avg_execution_time_ms`	no	Average execution time across all triggers, in milliseconds.
`top_consumers`	no	Ranked list of consumers by trigger count.
`top_resources`	no	Ranked list of resources by trigger count.
`top_guardrails`	no	Ranked list of guardrails by trigger count.
`time_distribution`	no	Time-series distribution of trigger counts.

{"signatures":{"go":"c.GuardrailTriggers().GetGuardrailTriggerStats(ctx, \u0026guardrailsv1.GetGuardrailTriggerStatsRequest{...})","python":"client.guardrailtriggers.getguardrailtriggerstats(...)","typescript":"client.guardrailtriggers.getguardrailtriggerstats({...})","cli":"tare api guardrails triggers stats","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers/stats\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","cli":"tare api guardrails triggers stats","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/triggers/stats\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/triggers/stats","slug":"get-guardrail-trigger-statistics"}

Get guardrails dashboard summary

What it does: Returns a combined summary of guardrail posture and recent trigger activity for the dashboard view.

Request fields:

Field	Required	Description
`customer_id`	no	Owning customer scope; defaults to caller's session customer when empty.
`project_id`	no	Owning project scope; defaults to caller's session project when empty.

Response fields:

Field	Required	Description
`guardrails`	no	Summary of guardrails configured in scope.
`events`	no	Summary of trigger events recorded in scope.

{"signatures":{"go":"c.GuardrailTriggers().GetDashboard(ctx, \u0026guardrailsv1.GetDashboardRequest{...})","python":"client.guardrailtriggers.getdashboard(...)","typescript":"client.guardrailtriggers.getdashboard({...})","cli":"tare api guardrails dashboard","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/dashboard\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"examples":{"go":"// No Go SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for GuardrailTriggersService yet -- use the CLI or curl example below.","cli":"tare api guardrails dashboard","curl":"curl \"${AGENTROUTER_BASE_URL}/v1/customers/cust_01H.../projects/proj_01H.../guardrails/dashboard\" \\\n  -H \"Authorization: Bearer ak-${AGENTROUTER_API_KEY}\""},"persona":"Authenticated (API key or session token)","httpVerb":"GET","httpPath":"/v1/customers/{customer_id}/projects/{project_id}/guardrails/dashboard","slug":"get-guardrails-dashboard-summary"}