Reports per time bucket

GET

/v1/reports/histogram

const url = 'https://api.us.headerhawk.com/v1/reports/histogram?reportType=csp-violation&disposition=enforce&deviceType=desktop&bucketSize=1m';
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/histogram?reportType=csp-violation&disposition=enforce&deviceType=desktop&bucketSize=1m' \
  --header 'Authorization: Bearer <token>'

How many of the reports GET /v1/reports would list with the same filters arrived in each bucket from from to to, empty buckets included. Reads reported data, so it spends the tenant’s budget too.

Window: the last 7 days by default, as the list’s; at most 31, longer is 400. Measured worst case: 23 ms for 110,777 reports (11 MB) in 90 days in 15-minute buckets.

Authorizations

apiKey

Parameters

Query Parameters

siteId

string format: uuid

Only this site’s reports. Another tenant’s site, or none, is 404.

reportType

Every type of report HeaderHawk stores and lists. The issue types (IssueReportType) and deprecation, intervention, network-error and crash. An open enum.

string

Allowed values: csp-violation integrity-violation coep coop permissions-policy-violation document-policy-violation connection-allowlist deprecation intervention network-error crash

The type of report to read. Defaults to csp-violation.

directive

string

<= 64 characters /^[\x20-\x5B\x5D-\x7E]+$/

CSP violations only: the violated directive, such as script-src. _ matches any one character. Every text filter takes printable ASCII with no backslash.

blockedHost

string

<= 255 characters /^[\x20-\x5B\x5D-\x7E]+$/

CSP violations only: the host the policy blocked. _ matches any one character.

disposition

string

Allowed values: enforce report

Only enforced violations, or only report-only ones. Deprecations, interventions, network errors and crashes have no disposition, so it is 400 with those.

documentHost

string

<= 255 characters /^[\x20-\x5B\x5D-\x7E]+$/

The host of the page the report came from. _ matches any one character.

browserName

string

<= 64 characters /^[\x20-\x5B\x5D-\x7E]+$/

The browser that sent the report, such as Chrome.

osName

string

<= 64 characters /^[\x20-\x5B\x5D-\x7E]+$/

The operating system the browser ran on, such as Windows.

deviceType

string

Allowed values: desktop mobile tablet unknown

The kind of device the browser ran on.

feature

string

<= 128 characters /^[\x20-\x5B\x5D-\x7E]+$/

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).

blockedUrl

string

<= 512 characters /^[\x20-\x5B\x5D-\x7E]+$/

Integrity violations only: the resource loaded without integrity metadata.

blockedOrigin

string

<= 255 characters /^[\x20-\x5B\x5D-\x7E]+$/

Integrity, COEP and connection allowlist violations only: the origin that was blocked.

destination

string

<= 64 characters /^[\x20-\x5B\x5D-\x7E]+$/

Integrity and COEP violations only: the request destination, such as script.

effectivePolicy

string

<= 128 characters /^[\x20-\x5B\x5D-\x7E]+$/

COOP violations only: the policy in effect.

otherOrigin

string

<= 255 characters /^[\x20-\x5B\x5D-\x7E]+$/

COOP violations only: the other document’s origin.

sourceFile

string

<= 512 characters /^[\x20-\x5B\x5D-\x7E]+$/

Permissions and document policy violations, deprecations and interventions: the script that used the feature, without its query.

from

string format: date-time

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.

string format: date-time

Only reports received before this instant. Defaults to now.

bucketSize

string

Allowed values: 1m 5m 15m 1h 1d

The width of each bucket. Chosen from the window when omitted, and widened when the window would need more than 10,000 buckets.

Responses

200

The buckets

application/json

object

data

required

object

bucketSize

required

The width of each bucket. An open enum.

string

Allowed values: 1m 5m 15m 1h 1d

buckets

required

Array<object>

object

time

required

The start of the bucket.

string format: date-time

reportCount

required

integer

Example

{
  "data": {
    "bucketSize": "1m"
  }
}

Headers

RateLimit-Limit

integer

The budget nearest to running out, per minute.

RateLimit-Remaining

integer

What is left of that budget this minute.

RateLimit-Reset

integer

Seconds until that budget starts again.

400

A parameter was refused, or one the operation does not take was sent. The message names it.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

401

invalid_api_key: no key, or one that is malformed, unknown, revoked or expired. One answer for all of them.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

403

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.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

404

No such resource in your tenant.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

429

rate_limited: over a budget. Wait Retry-After seconds.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.

503

rate_limit_unavailable or upstream_unavailable: HeaderHawk could not serve this now. Nothing is wrong with the request; try again after Retry-After seconds.

application/json

object

error

required

object

code

required

What went wrong. An open enum: treat a code you do not know by its HTTP status.

string

Allowed values: bad_request validation_error invalid_api_key plan_upgrade_required forbidden not_found rate_limited rate_limit_unavailable upstream_unavailable internal_error

message

required

For people. Branch on code.

string

requestId

required

Quote it when you write to us about this request.

string

Example

{
  "error": {
    "code": "bad_request"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.