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_requests ``` ## 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`, or `rule` | Additional time-based filtering parameters are supported. See [Pagination query parameters](https://botbye.com/docs/api#query-parameters). ## Response Structure ### Common Properties (All Summary Types) All summary types return an array of objects with these common fields: | Field | Type | Description | |-------|------|-------------| | `id` | string | Unique identifier (format varies by summary type) | | `projectId` | string | The project identifier | | `customerId` | null | Always null for project-level data | | `declinedReqCount` | integer | Number of declined requests for this summary item | ### Summary Type: `attack_source` Analyzes declined requests by IP address and country of origin. **Additional Fields:** | Field | Type | Description | |-------|------|-------------| | `remoteAddr` | string | IP address from which declined requests originated | | `country` | string | Country code (ISO 3166-1 alpha-3) of the IP address | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_104.28.247.47_DEU", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "remoteAddr": "104.28.247.47", "country": "DEU", "declinedReqCount": 356 } ] ``` ### Summary Type: `country` Analyzes declined requests grouped by country. **Additional Fields:** | Field | Type | Description | |-------|------|-------------| | `country` | string | Country code (ISO 3166-1 alpha-3) where requests originated | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_USA", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "country": "USA", "declinedReqCount": 1523 } ] ``` ### Summary Type: `endpoint` Analyzes declined requests grouped by API endpoint/URI. **Additional Fields:** | Field | Type | Description | |-------|------|-------------| | `requestUri` | string | The API endpoint URI that received declined requests | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_/api/v1/login", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "requestUri": "/api/v1/login", "declinedReqCount": 892 } ] ``` ### Summary Type: `reason` Analyzes declined requests grouped by the reason for blocking. **Additional Fields:** | Field | Type | Description | |-------|------|-------------| | `failedMessage` | string | The reason/message explaining why the request was 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", "declinedReqCount": 2341 } ] ``` ### Summary Type: `rule` Analyzes declined requests grouped by the security rule that blocked them. **Additional Fields:** | Field | Type | Description | |-------|------|-------------| | `ruleId` | string | The identifier of the security rule that declined the requests | | `ruleName` | string | The name of the security rule | **Example Response:** ```json [ { "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_rule-123", "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d", "customerId": null, "ruleId": "rule-123", "ruleName": "Block suspicious user agents", "declinedReqCount": 678 } ] ``` ## 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 `declinedReqCount` 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)