Monitoring

List violations

See the rules your agents have broken.

POSThttps://api.ollive.ai/api/violations/query/v1

Safe to retryPagedv1

How it works

A violation is one agent breaking one rule. If an agent breaks the same rule in 10 conversations, that is one violation with session_count: 10.

Use group_by to choose how much detail you get:

directive (the default): one row for each rule an agent broke, with how many conversations broke it and when it was first and last seen.
pattern: for one violation, groups the conversations that broke the rule in the same way. Needs deployment_id and directive_id.
session: for one violation, one row per conversation. Needs deployment_id and directive_id.

To dig into a row, send its deployment_id, directive_id, binding_text_id and pack_id back with the next group_by.

Authorization

Authorizationheaderrequired
Your API key, after the word Bearer, like this: Bearer sk-…. Create a key.

Request body

application/json

group_bystringdefault directive
How much detail to return. See above.
directivepatternsession
deployment_idstring
Only this deployment. Required for pattern and session.
directive_idstring
The rule. Required for pattern and session.
binding_text_idstring
Only rules from this source. Copy it from a row.
pack_idstring (uuid)
Only rules from this pack.
pattern_idstring
With session: only conversations in this pattern.
severitiesstring[]
With directive: only these severities.
criticalhighmediumlow
sincestringdefault 30d
How far back to look, such as 30m, 12h, 7d, or all for everything.
limitinteger
How many rows per page. With directive, the default is 10 and the most is 200. With session, the default is 25 and the most is 100.
cursorstring
The next_cursor from the previous page.
sourcestringdefault PLATFORM
Which conversations to include: PLATFORM for ones Ollive collected, API for ones you sent.
PLATFORMAPI

Every field is optional unless group_by needs it. Send {} for all violations in the last 30 days.

Response

The violations found. An empty list if there are none.

dataobject[]required
One row per violation, pattern or conversation, depending on group_by.
- deployment_idstring (uuid)required
  The deployment that broke the rule.
- directive_idstringrequired
  The rule.
- binding_text_idstringrequired
  The law, regulation or contract the rule comes from.
- pack_idstringrequired
  The rule pack it belongs to.
- pack_namestringrequired
  The rule pack’s name.
- titlestringrequired
  A short name for the violation.
- descriptionstringrequired
  A longer explanation.
- source_kindstringrequired
  Where the rule comes from.
  regulationframeworkcustom
- severitystringrequired
  How serious it is.
  criticalhighmediumlow
- citationsstring[]required
  References to the source, such as a section number.
- directive_textstringrequired
  The rule, in words.
- violation_textstringrequired
  What the agent did wrong.
- session_countintegerrequired
  How many conversations broke the rule.
- first_seen_atstring (date-time)
  When it first happened. directive rows only.
- last_seen_atstring (date-time)
  When it last happened. directive rows only.
- pattern_idstringrequired
  The pattern’s ID. Set on pattern and session rows.
- factsobject[]required
  What the conversations in this pattern have in common. pattern rows only.
  fieldstringrequired
  The fact’s name.
  questionstringrequired
  The question Ollive answered.
  answerstringrequired
  The answer.
  truefalseunknown
- sessionobject
  The conversation. session rows only.
  session_refstringrequired
  Your ID for the conversation.
  occurred_atstring (date-time)
  When it happened.
  duration_msinteger
  How long it lasted, in milliseconds.
  failed_stepsobject[]required
  Where in the conversation the rule was broken.
  rationalestringrequired
  Why it broke the rule.
  turn_indicesinteger[]required
  The turns involved.
  flagged_turn_indicesinteger[]required
  Every turn that was flagged.
total_countintegerrequired
How many results match, across all pages.
has_morebooleanrequired
Whether there is another page.
next_cursorstringrequired
Send this as cursor to get the next page. Empty on the last page.

← Get a transcript List verdicts →

curl -X POST "https://api.ollive.ai/api/violations/query/v1" \  -H "Authorization: Bearer $OLLIVE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "deployment_id": "d7e2c4a1-3f58-4b9e-8a61-0c5d9e2f7b34",    "severities": [      "critical",      "high"    ],    "since": "30d"  }'

Response

{  "data": [    {      "deployment_id": "d7e2c4a1-3f58-4b9e-8a61-0c5d9e2f7b34",      "binding_text_id": "msa-northwind-2026",      "directive_id": "identify-as-automated",      "pack_id": "5c1b9a3e-7d24-4f60-b8e1-92a4c6d0f3e8",      "pack_name": "Northwind MSA obligations",      "title": "Did not identify as automated",      "description": "The agent spoke with a caller without saying it is an automated system.",      "source_kind": "custom",      "severity": "high",      "citations": [        "MSA § 7.2"      ],      "directive_text": "Identify as an automated system at the start of every customer interaction.",      "violation_text": "The agent introduced itself by a human name and never said it was automated.",      "session_count": 10,      "first_seen_at": "2026-09-21T16:44:02Z",      "last_seen_at": "2026-10-14T09:12:19Z",      "pattern_id": "",      "facts": []    }  ],  "total_count": 1,  "has_more": false,  "next_cursor": ""}

{  "error": {    "code": "invalid_request",    "message": "deployment_id is required with group_by session.",    "param": "deployment_id",    "request_id": "4b1f0c9e2d7a48b6a3e5f19c0d8b7a26"  }}

{  "error": {    "code": "authentication_failed",    "message": "Invalid API key.",    "param": "",    "request_id": "4b1f0c9e2d7a48b6a3e5f19c0d8b7a26"  }}