> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.botbye.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.botbye.com/_mcp/server.

# declined events summary

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

# 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)

Reference: https://api-docs.botbye.com/bot-bye-api/protection/overview/declined-events-summary

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: collection
  version: 1.0.0
paths:
  /api/v1/{account_id}/projects/{project_id}/overviews/declined_events:
    get:
      operationId: declined-events-summary
      summary: declined events summary
      description: >-
        # 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)
      tags:
        - subpackage_overview
      parameters:
        - name: account_id
          in: path
          required: true
          schema:
            type: string
        - name: project_id
          in: path
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: >-
            (Required) attack_source, country, endpoint, total_endpoint, reason,
            rule
          required: false
          schema:
            type: string
        - name: interval
          in: query
          description: >-
            (Optional) Defines the interval for the overview. The interval is
            used in conjunction with intervalType to determine the specific time
            span of the overview. The default value is 1, meaning the current
            day (or month if interval_type = month).
          required: false
          schema:
            type: integer
        - name: interval_type
          in: query
          description: >-
            (Optional)  Specifies the type of interval for the overview. This
            can be HOUR, DAY, MONTH. The default value is DAY, meaning the
            overview will cover a single day.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: success - attack source summary
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: >-
                    #/components/schemas/ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItems
        '400':
          description: fail
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: >-
                    #/components/schemas/ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItems
servers:
  - url: '{base_url}'
    description: '{base_url}'
components:
  schemas:
    ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItemsContext:
      type: object
      properties:
        param:
          type: string
        type:
          type: string
      title: >-
        ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItemsContext
    ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItems:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        type:
          type: string
        context:
          $ref: >-
            #/components/schemas/ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItemsContext
      required:
        - message
        - code
        - type
      title: >-
        ApiV1AccountIdProjectsProjectIdOverviewsDeclinedEventsGetResponsesContentApplicationJsonSchemaItems

```

## Examples



**Response**

```json
[
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_82.209.216.44_DEU",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "82.209.216.44",
    "country": "DEU",
    "declinedReqCount": 183
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_104.28.247.47_DEU",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "104.28.247.47",
    "country": "DEU",
    "declinedReqCount": 179
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_116.202.24.183_DEU",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "116.202.24.183",
    "country": "DEU",
    "declinedReqCount": 153
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_116.202.24.183_USA",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "116.202.24.183",
    "country": "USA",
    "declinedReqCount": 118
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_82.209.216.44_BLR",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "82.209.216.44",
    "country": "BLR",
    "declinedReqCount": 113
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_104.28.247.47_USA",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "104.28.247.47",
    "country": "USA",
    "declinedReqCount": 86
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_104.28.247.47_BLR",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "104.28.247.47",
    "country": "BLR",
    "declinedReqCount": 85
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_116.202.24.183_BLR",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "116.202.24.183",
    "country": "BLR",
    "declinedReqCount": 84
  },
  {
    "id": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d_82.209.216.44_USA",
    "projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
    "remoteAddr": "82.209.216.44",
    "country": "USA",
    "declinedReqCount": 30
  }
]
```

**SDK Code**

```python Overview_declinedEventsSummary_example
import requests

url = "https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events"

querystring = {"type":"total_endpoint","interval":"1","interval_type":"DAY"}

response = requests.get(url, params=querystring)

print(response.json())
```

```javascript Overview_declinedEventsSummary_example
const url = 'https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Overview_declinedEventsSummary_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Overview_declinedEventsSummary_example
require 'uri'
require 'net/http'

url = URI("https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
```

```java Overview_declinedEventsSummary_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY")
  .asString();
```

```php Overview_declinedEventsSummary_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY');

echo $response->getBody();
```

```csharp Overview_declinedEventsSummary_example
using RestSharp;

var client = new RestClient("https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
```

```swift Overview_declinedEventsSummary_example
import Foundation

let request = NSMutableURLRequest(url: NSURL(string: "https://{base_url}/api/v1/account_id/projects/project_id/overviews/declined_events?type=total_endpoint&interval=1&interval_type=DAY")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```