Group reports by one or two dimensions
const url = 'https://api.us.headerhawk.com/v1/reports/grouped?groupBy=example&reportType=csp-violation&disposition=enforce&deviceType=desktop&limit=50';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.us.headerhawk.com/v1/reports/grouped?groupBy=example&reportType=csp-violation&disposition=enforce&deviceType=desktop&limit=50' \ --header 'Authorization: Bearer <token>'The largest groups of the reports GET /v1/reports would list with
the same filters, grouped by one dimension or two, each with its
count and its trend against the window of the same length just before
from. Reads reported data, so it spends the tenant’s budget too.
This is a ranking, not a list: it answers the top limit groups (at
most 100) and has no cursor.
Window: the last 7 days by default, as the list’s; at most 31,
longer is 400. Grouping reads every report in the window and in the
window of the same length before it, for the trend. Measured worst case: 33 ms for
110,777 reports (14 MB) in 90 days.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”One dimension, or two comma-separated. directive and
blockedHost group CSP violations only; feature, blockedUrl,
blockedOrigin, destination, effectivePolicy, otherOrigin
and sourceFile group the types whose reports carry them, as the
filters of the same names do; disposition groups a type whose
reports carry one; documentHost, browserName, osName,
deviceType and siteId group every type. Any other is 400.
Only this site’s reports. Another tenant’s site, or none, is 404.
Every type of report HeaderHawk stores and lists. The issue types
(IssueReportType) and deprecation, intervention,
network-error and crash. An open enum.
The type of report to read. Defaults to csp-violation.
CSP violations only: the violated directive, such as script-src.
_ matches any one character. Every text filter takes printable
ASCII with no backslash.
CSP violations only: the host the policy blocked. _ matches any one character.
Only enforced violations, or only report-only ones. Deprecations,
interventions, network errors and crashes have no disposition, so it
is 400 with those.
The host of the page the report came from. _ matches any one character.
The browser that sent the report, such as Chrome.
The operating system the browser ran on, such as Windows.
The kind of device the browser ran on.
The policy-controlled feature or API the report names: COEP, COOP, permissions and document policy violations, deprecations, interventions, network errors (the error type) and crashes (the reason).
Integrity violations only: the resource loaded without integrity metadata.
Integrity, COEP and connection allowlist violations only: the origin that was blocked.
Integrity and COEP violations only: the request destination, such as script.
COOP violations only: the policy in effect.
COOP violations only: the other document’s origin.
Permissions and document policy violations, deprecations and interventions: the script that used the feature, without its query.
Only reports received at or after this instant. Defaults to the start
of your retention window, or where the operation bounds its window, to
that many days before to. Earlier than your retention reaches is
400.
Only reports received before this instant. Defaults to now.
How many groups to answer, largest first.
Responses
Section titled “Responses”The largest groups
object
The dimensions asked for, in order.
object
The group’s value for each groupBy dimension, in order.
Reports stored in the group in the window.
The change against the window of the same length just before
from, in percent; null when that window had none, or reaches
back past your retention window, whose reports are deleted.
Examplegenerated
{ "groupBy": [ "example" ], "data": [ { "values": [ "example" ], "reportCount": 1, "firstSeen": "2026-04-15T12:00:00Z", "lastSeen": "2026-04-15T12:00:00Z", "trendPercent": 1 } ]}Headers
Section titled “Headers”The budget nearest to running out, per minute.
What is left of that budget this minute.
Seconds until that budget starts again.
A parameter was refused, or one the operation does not take was sent. The message names it.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}invalid_api_key: no key, or one that is malformed, unknown, revoked
or expired. One answer for all of them.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}plan_upgrade_required: the tenant’s plan does not include API access
(the key works again when it does), or does not include what this
operation reads.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}No such resource in your tenant.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}rate_limited: over a budget. Wait Retry-After seconds.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}Headers
Section titled “Headers”Seconds to wait before trying again.
rate_limit_unavailable or upstream_unavailable: HeaderHawk could
not serve this now. Nothing is wrong with the request; try again after
Retry-After seconds.
object
object
What went wrong. An open enum: treat a code you do not know by its HTTP status.
For people. Branch on code.
Quote it when you write to us about this request.
Example
{ "error": { "code": "bad_request" }}Headers
Section titled “Headers”Seconds to wait before trying again.