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}/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 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. Every field of a record is nullable except `signalsHiddenByPlan`: a record carries only what the integration reported and what the validator resolved for it, and the key is present with `null` otherwise. ``` json { "edges": [ { "cursor": "string", "node": { "id": "string", "version": integer, "validatorVersion": integer, "customerId": "string", "projectId": "string", "siteKey": "string", "serverKey": "string", "createdAt": "string", "eventType": "string", "eventStatus": "string", "requestMethod": "string", "requestUri": "string", "referer": "string", "accountId": "string", "username": "string", "email": "string", "phone": "string", "ip": "string", "realIp": "string", "userAgent": "string", "fingerprint": "string", "deviceMarks": "string", "visitorId": "string", "sessionId": "string", "country": "string", "realCountry": "string", "asn": "string", "longitude": number, "latitude": number, "shaKey": "string", "base64Token": "string", "behavioralToken": "string", "decision": "string", "dimensionScores": {}, "isBot": boolean, "isProtected": boolean, "signals": [], "signalsHiddenByPlan": boolean, "failedMessage": "string", "failedChecks": "string", "isBanByRule": boolean, "isAllowedByRule": boolean, "ruleId": "string", "captchaTaskId": "string", "isCaptchaEnabled": boolean, "isCaptchaSolved": boolean, "rate": integer, "requestTag": "string", "taggedCount": integer, "moduleName": "string", "moduleVersion": "string", "headers": {}, "customFields": {}, "host": "string", "contentType": "string", "connection": "string", "acceptEncoding": "string", "origin": "string", "xForwardedProto": "string", "accept": "string", "contentLength": integer, "priority": "string", "acceptLanguage": "string", "upgrade": "string", "realOrigin": "string", "ttlDays": integer } } ], "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 of the request record. | | `version` | integer | Event schema version reported by the integration. | | `validatorVersion` | integer | Version of the validator that processed the request. | | `customerId` | string | Customer that owns the project. | | `projectId` | string | Project the request belongs to. | | `siteKey` | string | Site key used for this request. | | `serverKey` | string | Server key used for validation. | | `createdAt` | string | When the request was processed, epoch milliseconds. | | `eventType` | string | Event kind reported by the integration, for example a login. | | `eventStatus` | string | Outcome of the event in your own system. | | `requestMethod` | string | HTTP method. | | `requestUri` | string | Request URI. | | `referer` | string | Referer header. | | `accountId` | string | End-user account id reported by the integration. | | `username` | string | Username reported by the integration. | | `email` | string | Email reported by the integration. | | `phone` | string | Phone reported by the integration. | | `ip` | string | Client IP the request arrived from. | | `realIp` | string | Client IP resolved behind proxies and CDNs. | | `userAgent` | string | User-Agent header. | | `fingerprint` | string | Device fingerprint reported by the SDK. | | `deviceMarks` | string | Device marks reported by the SDK. | | `visitorId` | string | Visitor identifier assigned by the SDK. | | `sessionId` | string | Session identifier assigned by the SDK. | | `country` | string | Country resolved from `ip`. | | `realCountry` | string | Country resolved from `realIp`. | | `asn` | string | Autonomous system the IP belongs to. | | `longitude` | number | Longitude resolved from the IP. | | `latitude` | number | Latitude resolved from the IP. | | `shaKey` | string | — | | `base64Token` | string | — | | `behavioralToken` | string | — | | `decision` | string | Verdict returned for the request. | | `dimensionScores` | object | Score per risk dimension, keyed by dimension id. | | `isBot` | boolean | Whether the request was classified as a bot. | | `isProtected` | boolean | Whether the project was protected when the request arrived. | | `signals` | array | Signals raised for this request. | | `signalsHiddenByPlan` | boolean | Whether `signals` was withheld because the subscription plan does not include it. | | `failedMessage` | string | Reason the request was declined. | | `failedChecks` | string | Checks that failed. | | `isBanByRule` | boolean | Whether a custom rule blocked the request. | | `isAllowedByRule` | boolean | Whether a custom rule allowed the request. | | `ruleId` | string | Custom rule that decided the request. | | `captchaTaskId` | string | CAPTCHA task issued for the request. | | `isCaptchaEnabled` | boolean | Whether CAPTCHA was enabled for the project. | | `isCaptchaSolved` | boolean | Whether the CAPTCHA was solved. | | `rate` | integer | Requests counted for the rate limiter that matched. | | `requestTag` | string | Tag assigned to the request. | | `taggedCount` | integer | Requests counted under the same tag. | | `moduleName` | string | Integration module that sent the request. | | `moduleVersion` | string | Version of that integration module. | | `headers` | object | Request headers, as name/value pairs. | | `customFields` | object | Custom fields sent by the integration. | | `host` | string | Host header. | | `contentType` | string | Content-Type header. | | `connection` | string | Connection header. | | `acceptEncoding` | string | Accept-Encoding header. | | `origin` | string | Origin header. | | `xForwardedProto` | string | X-Forwarded-Proto header. | | `accept` | string | Accept header. | | `contentLength` | integer | Content-Length header. | | `priority` | string | Priority header. | | `acceptLanguage` | string | Accept-Language header. | | `upgrade` | string | Upgrade header. | | `realOrigin` | string | Origin carried inside the SDK token. | | `ttlDays` | integer | Retention of this record, in days. | > **Accepted permissions** > `Project → Events → Events` > > **Token scope** > `Request View`