events
# Get Requests
Retrieves a detailed, paginated list of all requests processed by BotBye for a specific project. This endpoint provides comprehensive request-level data including headers, IP addresses, security check results, and decision outcomes, enabling deep forensic analysis and debugging.
## Endpoint
```
GET {base_url}/api/v1/{account_id}/projects/{project_id}/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 request logs |
## Query Parameters
This endpoint supports pagination and filtering parameters:
- **Pagination**: See [<code>Pagination query parameters</code>](http://botbye.com/docs/api) for details on `first`, `after`, `last`, `before` parameters
- **Filtering**: Additional filters may be available for date ranges, request status, IP addresses, etc.
## Response Structure
The response follows a cursor-based pagination pattern:
``` json
{
"edges": [
{
"cursor": "string",
"node": {
"id": "string",
"token": "string",
"customerId": "string",
"projectId": "string",
"siteKey": "string",
"serverKey": "string",
"referer": "string",
"userAgent": "string",
"host": "string",
"requestMethod": "string",
"requestUri": "string",
"remoteAddr": "string",
"serverName": "string",
"remoteUser": "string",
"serverPort": integer,
"requestInfo": "string",
"failedMessage": "string",
"failedChecks": "string",
"customFields": [],
"headers": "string",
"createdAt": "string",
"realIp": "string",
"country": "string",
"asn": "string",
"isProtected": boolean,
"isBanByRule": boolean
}
}
],
"pageInfo": {
"hasPreviousPage": boolean,
"hasNextPage": boolean,
"startCursor": "string | null",
"endCursor": "string | null",
"total": integer
}
}
```
### Response Fields
**edges** (array): Contains the request records
- **cursor** (string): Pagination cursor for this record
- **node** (object): The request data with the following fields:
| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique identifier for this request |
| `token` | string | BotBye token associated with the request |
| `customerId` | string | Customer identifier (if applicable) |
| `projectId` | string | The project identifier |
| `siteKey` | string | The site key used for this request |
| `serverKey` | string | The server key used for validation |
| `referer` | string | HTTP Referer header value |
| `userAgent` | string | User-Agent header value |
| `host` | string | Host header value |
| `requestMethod` | string | HTTP method (GET, POST, PUT, DELETE, etc.) |
| `requestUri` | string | The request URI/endpoint |
| `remoteAddr` | string | IP address of the client |
| `serverName` | string | Server name that processed the request |
| `remoteUser` | string | Remote user identifier (if authenticated) |
| `serverPort` | integer | Server port number |
| `requestInfo` | string | Additional request information |
| `failedMessage` | string | Reason for declining the request (if declined) |
| `failedChecks` | string | Specific security checks that failed |
| `customFields` | array | Custom fields passed with the request |
| `headers` | string | Complete request headers (JSON string) |
| `createdAt` | string | ISO 8601 timestamp when the request was processed |
| `realIp` | string | Real IP address (if behind proxy/CDN) |
| `country` | string | Country code (ISO 3166-1 alpha-3) of the IP |
| `asn` | string | Autonomous System Number of the IP |
| `isProtected` | boolean | Whether the request was protected by BotBye |
| `isBanByRule` | boolean | Whether the request was banned by a custom rule |
**pageInfo** (object): Pagination metadata
- **hasPreviousPage** (boolean): Whether there are more results before the current page
- **hasNextPage** (boolean): Whether there are more results after the current page
- **startCursor** (string | null): Cursor pointing to the first item
- **endCursor** (string | null): Cursor pointing to the last item
- **total** (integer): Total number of requests found
## Example Response
``` json
{
"edges": [
{
"cursor": "YXJyYXljb25uZWN0aW9uOjA=",
"node": {
"id": "req_abc123xyz",
"token": "tok_def456",
"customerId": "cust_789",
"projectId": "185071d5-d4fe-4bea-93df-19d0bd8c2d0d",
"siteKey": "sk_live_abc123",
"serverKey": "srv_key_xyz",
"referer": "https://example.com/login",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
"host": "api.example.com",
"requestMethod": "POST",
"requestUri": "/api/v1/auth/login",
"remoteAddr": "203.0.113.42",
"serverName": "api-server-01",
"remoteUser": null,
"serverPort": 443,
"requestInfo": "Login attempt",
"failedMessage": "Rate limit exceeded",
"failedChecks": "rate_limit",
"customFields": [],
"headers": "{\"Content-Type\":\"application/json\",\"Authorization\":\"Bearer ...\"}",
"createdAt": "2024-08-24T15:32:10Z",
"realIp": "203.0.113.42",
"country": "USA",
"asn": "AS15169",
"isProtected": true,
"isBanByRule": true
}
}
],
"pageInfo": {
"hasPreviousPage": false,
"hasNextPage": true,
"startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
"endCursor": "YXJyYXljb25uZWN0aW9uOjA=",
"total": 15847
}
}
```
## Use Cases
- **Security Investigation**: Analyze specific requests to understand security decisions
- **Debugging**: Troubleshoot why legitimate requests are being blocked
- **Audit Logging**: Maintain comprehensive logs for compliance and security audits
- **Threat Analysis**: Study attack patterns by examining declined request details
- **False Positive Analysis**: Review blocked requests to tune security rules
- **Performance Monitoring**: Track request patterns and identify bottlenecks
- **Customer Support**: Investigate user-reported issues with specific requests
- **Forensic Analysis**: Deep-dive into security incidents with complete request data
## Pagination Example
To retrieve the next page of results:
```
GET {base_url}/api/v1/{account_id}/projects/{project_id}/requests?after=YXJyYXljb25uZWN0aW9uOjA=&first=50
```
## Important Notes
- **Data Volume**: This endpoint can return large amounts of data; use pagination effectively
- **Headers**: The `headers` field contains a JSON string that needs to be parsed
- **IP Addresses**: `remoteAddr` shows the direct connection IP, while `realIp` shows the actual client IP (useful when behind proxies/CDNs)
- **Failed Requests**: Check `failedMessage` and `failedChecks` to understand why requests were declined
- **Custom Fields**: Use `customFields` to pass and retrieve application-specific data
- **Data Retention**: Request logs are retained according to your BotBye plan
- **Performance**: For high-traffic projects, consider filtering by date range to improve query performance
- **Privacy**: Request data may contain sensitive information; handle according to your privacy policies
## Filtering Best Practices
- Filter by date range for better performance on high-traffic projects
- Use `isBanByRule: true` to focus on rule-based blocks
- Filter by `country` or `asn` to analyze geographic patterns
- Combine filters to narrow down specific security events
Path parameters
account_id
project_id
Query parameters
cursor
(Optional): a cursor for pagination.
- `after` (string): Pointer to the item after which the items are to be retrieved.
- `before` (string): Pointer to the item before which the items are to be retrieved.
where
(Optional): is used to create conditions for data filtering. It can be used to create simple conditions (leaf nodes) as well as compound logical expressions (branch nodes).
- `predicate` (string): The filtering condition (e.g., `gte`, `lte`, `eq` for a leaf or `and`, `or` for a branch). Possible values [[#Predicate]]
- `opearands` (string): A list of nested conditions (used only for branches, such as `and`, `or`).
- `fieldPath` (string): The field to which the filtering condition is applied (used only for a leaf. Each entity has its own fieldPath list).
- `value` (string): The value to compare against the field (used only for a leaf).
order_by
(Optional): property by which to order by.
- `fieldPath` (string): name of order field.
- `direction` (string): `ASC` or `DESC`
limit
(Optional): specifies the maximum number of results to return in a single response. By default - 20, max - 100.
Response headers
Content-Length
Connection
Response
success
edges
pageInfo
attributes
Errors
400
Bad Request Error