Skip to navigation
BotBye APIProtectionOverview

declined events count

View as Markdown

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

ParameterTypeRequiredDescription
account_idstringYesYour unique BotBye account identifier
project_idstringYesThe 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:

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:

FieldTypeDescription
idstringUnique identifier combining projectId, day, and hour (format: projectId_day_hour)
projectIdstring | nullThe project identifier
customerIdstring | nullSet on account-level summaries, null for project-level data
bannedValidationEventsCountintegerNumber of requests declined by custom rules during this period
bannedValidationEventsTrendfloatPercentage change against the previous period (negative = decrease)
botValidationEventsCountintegerNumber of requests identified as bot traffic during this period
botValidationEventsTrendfloatPercentage change in bot requests against the previous period
totalintegerAll validation events recorded in this period
totalTrendfloatPercentage 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

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.

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