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

# Get Requests Overview 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](https://botbye.com/docs/api#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 ```json [ { "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.

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

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