declined events count | Botbye

Retrieves detailed metrics about declined requests for a specific project, including counts and trend analysis. This endpoint helps you understand the volume and patterns of blocked traffic, including custom rule violations and bot detection.

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/overviews/declined_events/count

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 declined request metrics

Query Parameters

This endpoint supports time-based filtering parameters to specify the date range for analysis:

Time period filters - Specify start/end dates for the analysis period
See Pagination query parameters for additional options

Response Structure

The response returns an object containing declined request metrics and trends, or null when the project recorded no declined requests in the requested window:

Field	Type	Description
`id`	string	Unique identifier combining `projectId`, `day`, and `hour` (format: `projectId_day_hour`)
`projectId`	string \| null	The project identifier
`customerId`	string \| null	Set on account-level summaries, `null` for project-level data
`bannedValidationEventsCount`	integer	Number of requests declined by custom rules during this period
`bannedValidationEventsTrend`	float	Percentage change against the previous period (negative = decrease)
`botValidationEventsCount`	integer	Number of requests identified as bot traffic during this period
`botValidationEventsTrend`	float	Percentage change in bot requests against the previous period
`total`	integer	All validation events recorded in this period
`totalTrend`	float	Percentage change of that total against the previous period

Example Response

{
  "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_2024-08-17_0",
  "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
  "customerId": null,
  "bannedValidationEventsCount": 56298,
  "bannedValidationEventsTrend": -63.75,
  "botValidationEventsCount": 0,
  "botValidationEventsTrend": 0,
  "total": 56298,
  "totalTrend": -63.75
}

Use Cases

Security Monitoring: Track the volume of blocked malicious requests
Trend Analysis: Identify increases or decreases in attack activity
Rule Effectiveness: Measure how many requests your custom rules are blocking
Bot Detection Metrics: Monitor automated bot traffic separately from rule-based blocks
Alert Configuration: Set up alerts when declined request trends spike
Security Reporting: Generate reports showing protection effectiveness over time

Understanding Trends

The trend values indicate percentage changes compared to the previous equivalent time period:

Negative trend (e.g., -63.75): Declined requests decreased by 63.75%
Positive trend (e.g., +45.20): Declined requests increased by 45.20%
Zero trend (0): No change from previous period

Important Notes

Trends are calculated by comparing to the equivalent previous time period
A decrease in bannedValidationEventsCount trend may indicate reduced attack activity or rule adjustments
botValidationEventsCount specifically tracks automated bot traffic detected by BotBye’s bot detection algorithms
bannedValidationEventsCount includes requests blocked by your custom security rules
The customerId field is null for project-level aggregations

Accepted permissions Project → Project → Info

Token scope Project View

# Get Declined Requests Count Retrieves detailed metrics about declined requests for a specific project, including counts and trend analysis. This endpoint helps you understand the volume and patterns of blocked traffic, including custom rule violations and bot detection. ## Endpoint ``` GET {base_url}/api/v1/{account_id}/projects/{project_id}/overviews/declined_events/count ``` ## 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 declined request metrics | ## Query Parameters This endpoint supports time-based filtering parameters to specify the date range for analysis: - **Time period filters** - Specify start/end dates for the analysis period - See [Pagination query parameters](https://botbye.com/docs/api#query-parameters) for additional options ## Response Structure The response returns an object containing declined request metrics and trends, or `null` when the project recorded no declined requests in the requested window: | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique identifier combining `projectId`, `day`, and `hour` (format: `projectId_day_hour`) | | `projectId` | string \| null | The project identifier | | `customerId` | string \| null | Set on account-level summaries, `null` for project-level data | | `bannedValidationEventsCount` | integer | Number of requests declined by custom rules during this period | | `bannedValidationEventsTrend` | float | Percentage change against the previous period (negative = decrease) | | `botValidationEventsCount` | integer | Number of requests identified as bot traffic during this period | | `botValidationEventsTrend` | float | Percentage change in bot requests against the previous period | | `total` | integer | All validation events recorded in this period | | `totalTrend` | float | Percentage change of that total against the previous period | ## Example Response ```json { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_2024-08-17_0", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "bannedValidationEventsCount": 56298, "bannedValidationEventsTrend": -63.75, "botValidationEventsCount": 0, "botValidationEventsTrend": 0, "total": 56298, "totalTrend": -63.75 } ``` ## Use Cases - **Security Monitoring**: Track the volume of blocked malicious requests - **Trend Analysis**: Identify increases or decreases in attack activity - **Rule Effectiveness**: Measure how many requests your custom rules are blocking - **Bot Detection Metrics**: Monitor automated bot traffic separately from rule-based blocks - **Alert Configuration**: Set up alerts when declined request trends spike - **Security Reporting**: Generate reports showing protection effectiveness over time ## Understanding Trends The trend values indicate percentage changes compared to the previous equivalent time period: - **Negative trend** (e.g., `-63.75`): Declined requests decreased by 63.75% - **Positive trend** (e.g., `+45.20`): Declined requests increased by 45.20% - **Zero trend** (`0`): No change from previous period ## Important Notes - Trends are calculated by comparing to the equivalent previous time period - A decrease in `bannedValidationEventsCount` trend may indicate reduced attack activity or rule adjustments - `botValidationEventsCount` specifically tracks automated bot traffic detected by BotBye's bot detection algorithms - `bannedValidationEventsCount` includes requests blocked by your custom security rules - The `customerId` field is `null` for project-level aggregations > **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

idstring

bannedValidationEventsCountinteger

bannedValidationEventsTrenddouble

botValidationEventsCountinteger

botValidationEventsTrenddouble

totalinteger

totalTrenddouble

projectIdstring or nullOptionalformat: "uuid"

customerIdstring or nullOptionalformat: "uuid"

Errors

400

Bad Request Error

Endpoint

GET {base_url}/api/v1/{account_id}/projects/{project_id}/overviews/declined_events/count

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 declined request metrics

Query Parameters

This endpoint supports time-based filtering parameters to specify the date range for analysis:

Time period filters - Specify start/end dates for the analysis period
See Pagination query parameters for additional options

Response Structure

The response returns an object containing declined request metrics and trends, or null when the project recorded no declined requests in the requested window:

Field	Type	Description
`id`	string	Unique identifier combining `projectId`, `day`, and `hour` (format: `projectId_day_hour`)
`projectId`	string \| null	The project identifier
`customerId`	string \| null	Set on account-level summaries, `null` for project-level data
`bannedValidationEventsCount`	integer	Number of requests declined by custom rules during this period
`bannedValidationEventsTrend`	float	Percentage change against the previous period (negative = decrease)
`botValidationEventsCount`	integer	Number of requests identified as bot traffic during this period
`botValidationEventsTrend`	float	Percentage change in bot requests against the previous period
`total`	integer	All validation events recorded in this period
`totalTrend`	float	Percentage change of that total against the previous period

Example Response

{
  "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_2024-08-17_0",
  "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
  "customerId": null,
  "bannedValidationEventsCount": 56298,
  "bannedValidationEventsTrend": -63.75,
  "botValidationEventsCount": 0,
  "botValidationEventsTrend": 0,
  "total": 56298,
  "totalTrend": -63.75
}

Use Cases

Security Monitoring: Track the volume of blocked malicious requests
Trend Analysis: Identify increases or decreases in attack activity
Rule Effectiveness: Measure how many requests your custom rules are blocking
Bot Detection Metrics: Monitor automated bot traffic separately from rule-based blocks
Alert Configuration: Set up alerts when declined request trends spike
Security Reporting: Generate reports showing protection effectiveness over time

Understanding Trends

The trend values indicate percentage changes compared to the previous equivalent time period:

Negative trend (e.g., -63.75): Declined requests decreased by 63.75%
Positive trend (e.g., +45.20): Declined requests increased by 45.20%
Zero trend (0): No change from previous period

Important Notes

Trends are calculated by comparing to the equivalent previous time period
A decrease in bannedValidationEventsCount trend may indicate reduced attack activity or rule adjustments
botValidationEventsCount specifically tracks automated bot traffic detected by BotBye’s bot detection algorithms
bannedValidationEventsCount includes requests blocked by your custom security rules
The customerId field is null for project-level aggregations

Accepted permissions Project → Project → Info

Token scope Project View