events overview | Botbye

Retrieves aggregated request statistics for a specific project over a given time period. This endpoint provides time-series data showing allowed and declined request counts, enabling you to monitor traffic patterns and security events.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/overviews/events

Authentication

Requires API key authentication:

Authorization: Bearer {api_key}

Path Parameters

Parameter	Type	Required	Description
`account_id`	string	Yes	Your unique BotBye account identifier
`project_id`	string	Yes	The project identifier for which to retrieve overview data

Query Parameters

This endpoint supports standard time-based filtering parameters to specify the date range and granularity of the data:

Time period filters - Specify start/end dates and aggregation level (hourly, daily, monthly)
See Pagination query parameters for additional options

Response Structure

The response returns an array of time-series data points, each containing:

Field	Type	Description
`day`	string	Date in `YYYY-MM-DD` format for the data point
`hour`	integer	Hour interval (0-23) for hourly aggregation
`id`	string	Unique identifier combining `projectId`, `day`, and `hour` (format: `projectId_day_hour`)
`projectId`	string	The project identifier
`customerId`	string \| null	Set on account-level summaries, `null` for project-level data
`allowedValidationEventsCount`	integer	Number of requests that were allowed during this period
`declinedValidationEventsCount`	integer	Number of requests that were declined during this period
`total`	integer	Total requests (`allowedValidationEventsCount + declinedValidationEventsCount`)

Example Response

[
  {
    "day": "2024-08-24",
    "hour": 0,
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_2024-08-24_0",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "customerId": null,
    "allowedValidationEventsCount": 13941,
    "declinedValidationEventsCount": 13853,
    "total": 27794
  },
  {
    "day": "2024-08-24",
    "hour": 1,
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_2024-08-24_1",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "customerId": null,
    "allowedValidationEventsCount": 15234,
    "declinedValidationEventsCount": 12456,
    "total": 27690
  }
]

Use Cases

Traffic Monitoring: Track overall request volume trends over time
Security Dashboard: Visualize allowed vs. declined request ratios
Capacity Planning: Understand peak traffic periods
Anomaly Detection: Identify unusual spikes in declined requests
Performance Reporting: Generate reports on API protection effectiveness
Trend Analysis: Compare traffic patterns across different time periods

Important Notes

Data granularity depends on the time range requested (hourly for short periods, daily/monthly for longer periods)
The customerId field is always null for project-level aggregations
Use the id field as a unique key when storing or processing this data
Historical data availability depends on your BotBye plan’s retention policy

Accepted permissions Project → Project → Info

Token scope Project View

Authentication

X-Api-Keystring

Personal access token. Create it in your BotBye account under Profile → Personal Access Tokens, tick the scopes the endpoints you call require (see each endpoint’s Token scope), and send the token in the X-Api-Key request header. A token works only for the account it was created in.

Path parameters

account_idstringRequired

project_idstringRequired

Query parameters

intervalintegerOptional

(Optional) Size of the lookback window, counted in interval_type units back from now. The default value is 1, meaning the current day (or the current hour if interval_type is HOUR). A negative value is rejected.

interval_typestringOptional

(Optional) Unit of the lookback window: HOUR or DAY, case-insensitive. Defaults to DAY. Any other value is rejected.

Response headers

Content-Lengthinteger

ConnectionstringOptional

Response

success

messagestring

codestring

typestring

contextobjectOptional

Errors

400

Bad Request Error