Get guardrail hits

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get guardrail hits

> Get guardrail hits through the workspace-scoped public API.

Counts initial failed checks per policy in the selected window and the preceding equal-length window. Rewritten replies count as hits. Policies without failures in either window may be absent; `policies` can be empty.

See the [Guardrails overview](/en/api-reference/guardrails) for shared schemas and runtime limitations.

<ParamField header="Authorization" type="string" required>Bearer workspace API key. The key needs `read` scope.</ParamField>
<ParamField query="botId" type="string" required>Agent UUID in the authenticated workspace.</ParamField>
<ParamField query="days" type="integer">1 to 90; defaults to 30.</ParamField>

## Response

<ResponseField name="days" type="integer">Requested window length.</ResponseField>
<ResponseField name="from" type="datetime">Current window start.</ResponseField>
<ResponseField name="to" type="datetime">Current window end.</ResponseField>
<ResponseField name="bucketSeconds" type="number">Bucket duration: 24 buckets for one day, four per day for 2 to 7 days, and at most 30 buckets for longer windows.</ResponseField>
<ResponseField name="policies" type="array">Each entry has `policyId`, current `hits`, `previousHits`, and a chronological `series` of current-window bucket counts.</ResponseField>

<RequestExample>
  ~~~bash cURL theme={null}
  curl --request GET \
    --url "https://api-prod.usefini.com/v2/guardrail-policies/hits/public?botId=11111111-1111-4111-8111-111111111111&days=1" \
    --header "Authorization: Bearer $FINI_API_KEY"
  ~~~

  ~~~javascript Node.js theme={null}
  const response = await fetch("https://api-prod.usefini.com/v2/guardrail-policies/hits/public?botId=11111111-1111-4111-8111-111111111111&days=1", {
    method: "GET",
    headers: { Authorization: `Bearer ${process.env.FINI_API_KEY}` },
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(await response.json());
  ~~~

  ~~~python Python theme={null}
  import os
  import requests

  response = requests.get(
      "https://api-prod.usefini.com/v2/guardrail-policies/hits/public?botId=11111111-1111-4111-8111-111111111111&days=1",
      headers={"Authorization": f"Bearer {os.environ['FINI_API_KEY']}"},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ~~~
</RequestExample>

<ResponseExample>
  ~~~json 200 theme={null}
  {
    "days": 1,
    "from": "2026-09-30T09:00:00.000Z",
    "to": "2026-10-01T09:00:00.000Z",
    "bucketSeconds": 3600,
    "policies": [
      {
        "policyId": "22222222-2222-4222-8222-222222222222",
        "hits": 2,
        "previousHits": 1,
        "series": [
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          0,
          2
        ]
      }
    ]
  }
  ~~~
</ResponseExample>


## Related topics

- [Overview](/en/api-reference/guardrails.md)
- [Get guardrail policy](/en/api-reference/get-guardrail-policy.md)
- [Guardrails](/en/configuration/guardrails.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.