declined events summary

# Get Declined Requests Summary Retrieves a summarized breakdown of declined requests based on different analysis dimensions. This endpoint allows you to analyze blocked traffic by attack source, country, endpoint, reason, or rule, providing actionable insights for security optimization. ## Endpoint ``` GET {base_url}/api/v1/{account_id}/projects/{project_id}/overviews/declined_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 declined request summaries | ## Query Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string | Yes | Summary type: `attack_source`, `country`, `endpoint`, `reason`, `rule` or `total_endpoint` | Additional time-based filtering parameters are supported. See [Pagination query parameters](https://botbye.com/docs/api#query-parameters). ## Response Structure An array of summary rows. `id`, `projectId` and `customerId` are on every row; the rest depend on `type`. ### Common Properties (All Summary Types) | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique identifier (format varies by summary type) | | `projectId` | string \| null | The project identifier | | `customerId` | string \| null | Set on account-level summaries, `null` for project-level data | The five declined summaries additionally carry `declinedValidationEventsCount` (integer): the number of declined requests for that row. ### Summary Type: `attack_source` Declined requests by IP address and country of origin. | Field | Type | Description | |-------|------|-------------| | `ip` | string | IP address the declined requests came from | | `country` | string | Country code (ISO 3166-1 alpha-3) of that IP | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_104.28.247.47_DEU", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "ip": "104.28.247.47", "country": "DEU", "declinedValidationEventsCount": 356 } ] ``` ### Summary Type: `country` Declined requests grouped by country. | Field | Type | Description | |-------|------|-------------| | `country` | string | Country code (ISO 3166-1 alpha-3) the requests came from | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_USA", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "country": "USA", "declinedValidationEventsCount": 1523 } ] ``` ### Summary Type: `endpoint` Declined requests grouped by endpoint. | Field | Type | Description | |-------|------|-------------| | `requestMethod` | string | HTTP method of the declined requests | | `requestUri` | string | URI that received them | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_POST_/api/v1/login", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "requestMethod": "POST", "requestUri": "/api/v1/login", "declinedValidationEventsCount": 892 } ] ``` ### Summary Type: `reason` Declined requests grouped by the reason for blocking. | Field | Type | Description | |-------|------|-------------| | `failedMessage` | string | Reason the requests were declined | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_Rate limit exceeded", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "failedMessage": "Rate limit exceeded", "declinedValidationEventsCount": 2341 } ] ``` ### Summary Type: `rule` Declined requests grouped by the rule that decided them. This summary also reports what the rule let through. | Field | Type | Description | |-------|------|-------------| | `ruleId` | string | Rule that decided the requests | | `allowedValidationEventsCount` | integer | Requests the same rule allowed | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_0198c39a-6f1b-7c4e-9a2d-5e8f10b3c7d4", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "ruleId": "0198c39a-6f1b-7c4e-9a2d-5e8f10b3c7d4", "declinedValidationEventsCount": 745, "allowedValidationEventsCount": 120 } ] ``` ### Summary Type: `total_endpoint` Total traffic per endpoint, with the trend against the previous period. This summary reports totals rather than declines, so it carries no `declinedValidationEventsCount`. | Field | Type | Description | |-------|------|-------------| | `requestMethod` | string | HTTP method | | `requestUri` | string | URI | | `total` | integer | Requests in the selected period | | `previousTotal` | integer | Requests in the previous equivalent period | | `trend` | float | Percentage change against that previous period | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_POST_/api/v1/login", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "requestMethod": "POST", "requestUri": "/api/v1/login", "total": 27794, "previousTotal": 31002, "trend": -10.35 } ] ``` ## Use Cases - **Threat Intelligence**: Identify top attack sources by IP and country - **Geographic Analysis**: Understand which countries generate the most malicious traffic - **Endpoint Protection**: Identify which endpoints are most frequently targeted - **Rule Optimization**: Analyze which security rules are most effective - **Attack Pattern Analysis**: Understand common reasons for request blocking - **Whitelist Management**: Identify legitimate traffic that may need whitelisting - **Security Reporting**: Generate detailed reports on attack patterns ## Important Notes - The `type` query parameter is required and determines the response structure - Results are typically ordered by `declinedValidationEventsCount` in descending order (most declined first) - Use this endpoint to drill down into specific aspects of your declined traffic - Combine with time filters to analyze trends over specific periods - Country codes follow ISO 3166-1 alpha-3 standard (e.g., USA, DEU, GBR) > **Accepted permissions** > `Project → Project → Info` > > **Token scope** > `Project View`