> For the complete documentation index, see [llms.txt](https://docs.guardianstack.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guardianstack.ai/api-reference/reference/events.md).

# Events

Retrieve processed events for server-side fraud/risk decisions.

## Get processed event by id

> Returns a processed view of an event for fraud / risk evaluation.\
> \
> \*\*Authentication\*\*\
> Pass your secret key as a Bearer token: \`Authorization: Bearer \<secret>\`.\
> Secrets must not be sent as query parameters — they would be rejected by the upstream WAF\
> and exposed in access logs.\
> \
> \*\*Event availability / eventual consistency\*\*\
> Events are processed asynchronously; the event may temporarily return \`404\` shortly after creation.\
> The official Server SDK retries \`404\` for a short time window.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guardian Stack API","version":"1.0.0"},"tags":[{"name":"Events","description":"Retrieve processed events for server-side fraud/risk decisions."}],"servers":[{"url":"https://api.guardianstack.ai","description":"Production (default base URL used by the Server SDK)"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"token","description":"Use your Guardian **secret key** as a Bearer token.\n\nExample: `Authorization: Bearer sec_xxx`\n\nDo not pass the secret as a query parameter (`?secret=...`) — such requests are blocked\nby the upstream WAF and would leak credentials into access logs and referrers.\n"}},"schemas":{"ProcessedEventResponse":{"type":"object","required":["identification"],"properties":{"identification":{"$ref":"#/components/schemas/ProcessedEventIdentification"},"ipInfo":{"allOf":[{"$ref":"#/components/schemas/IpApiIsResponse"}],"nullable":true,"description":"IP intelligence payload used during processing.\nNote: some fields (e.g. `company.whois`, `asn.whois`) may be sanitized server-side.\n"},"vpn":{"allOf":[{"$ref":"#/components/schemas/ProcessedEventVpnSummary"}],"nullable":true},"velocity":{"allOf":[{"$ref":"#/components/schemas/ProcessedEventVelocity"}],"nullable":true,"description":"Event-level request velocity (counts) over sliding windows."},"visitorVelocity":{"allOf":[{"$ref":"#/components/schemas/ProcessedVisitorVelocity"}],"nullable":true,"description":"Visitor-level request velocity (counts) over sliding windows."},"botDetection":{"allOf":[{"$ref":"#/components/schemas/BotDetectionSummary"}],"nullable":true},"tampering":{"allOf":[{"$ref":"#/components/schemas/TamperingSummary"}],"nullable":true},"privacySettings":{"allOf":[{"$ref":"#/components/schemas/PrivacySettingsSummary"}],"nullable":true},"virtualization":{"allOf":[{"$ref":"#/components/schemas/VirtualizationSummary"}],"nullable":true},"incognito":{"allOf":[{"$ref":"#/components/schemas/IncognitoSummary"}],"nullable":true}}},"ProcessedEventIdentification":{"type":"object","required":["id","ip"],"properties":{"id":{"type":"string","description":"Guardian event identifier."},"visitorId":{"type":"string","nullable":true,"description":"Stable, server-issued identifier for the visitor (site-scoped)."},"ip":{"type":"string","description":"Server-observed client IP address for the event."},"timestamp":{"type":"string","format":"date-time","nullable":true,"description":"ISO timestamp of event creation."},"url":{"type":"string","nullable":true,"description":"Page URL as reported by the client during collection."},"location":{"allOf":[{"$ref":"#/components/schemas/LocationInfo"}],"nullable":true},"browser":{"$ref":"#/components/schemas/BrowserInfo"}}},"LocationInfo":{"type":"object","properties":{"is_eu_member":{"type":"boolean","nullable":true},"calling_code":{"type":"string","nullable":true},"currency_code":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true,"description":"Continent code (e.g. `EU`, `AS`, `NA`)."},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"latitude":{"type":"number","format":"float","nullable":true},"longitude":{"type":"number","format":"float","nullable":true},"zip":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"local_time":{"type":"string","nullable":true,"description":"Local time at the IP-derived location (ISO string)."},"is_dst":{"type":"boolean","nullable":true}}},"BrowserInfo":{"type":"object","properties":{"browserName":{"type":"string","nullable":true},"browserMajorVersion":{"type":"string","nullable":true},"browserFullVersion":{"type":"string","nullable":true},"platform":{"type":"string","nullable":true,"description":"Normalized platform label (e.g. `windows`, `mac`, `ios`, `android`, `linux`, `chromeos`)."},"os":{"type":"string","nullable":true},"osVersion":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true}}},"IpApiIsResponse":{"type":"object","required":["ip","is_bogon","is_mobile","is_satellite","is_crawler","is_datacenter","is_tor","is_proxy","is_vpn","is_abuser"],"properties":{"ip":{"type":"string"},"rir":{"type":"string","nullable":true,"description":"Regional Internet Registry (e.g. `RIPE`, `ARIN`)."},"is_bogon":{"type":"boolean"},"is_mobile":{"type":"boolean"},"is_satellite":{"type":"boolean"},"is_crawler":{"type":"boolean"},"is_datacenter":{"type":"boolean"},"is_tor":{"type":"boolean"},"is_proxy":{"type":"boolean"},"is_vpn":{"type":"boolean"},"is_abuser":{"type":"boolean"},"vpn":{"allOf":[{"$ref":"#/components/schemas/IpApiVpnInfo"}],"nullable":true},"datacenter":{"allOf":[{"$ref":"#/components/schemas/IpApiDatacenterInfo"}],"nullable":true},"company":{"allOf":[{"$ref":"#/components/schemas/IpApiCompanyInfo"}],"nullable":true},"abuse":{"allOf":[{"$ref":"#/components/schemas/IpApiAbuseContact"}],"nullable":true},"asn":{"allOf":[{"$ref":"#/components/schemas/IpApiAsnInfo"}],"nullable":true},"location":{"allOf":[{"$ref":"#/components/schemas/IpApiLocationInfo"}],"nullable":true},"elapsed_ms":{"type":"number","nullable":true,"description":"Upstream lookup latency in milliseconds (when available)."}}},"IpApiVpnInfo":{"type":"object","required":["ip","service","url","type","last_seen","last_seen_str"],"properties":{"ip":{"type":"string"},"service":{"type":"string"},"url":{"type":"string"},"type":{"type":"string","description":"Category (e.g. `vpn_server`)."},"last_seen":{"type":"number","description":"Epoch milliseconds."},"last_seen_str":{"type":"string","description":"ISO timestamp."},"exit_node_region":{"type":"string","nullable":true}}},"IpApiDatacenterInfo":{"type":"object","required":["datacenter","domain","network"],"properties":{"datacenter":{"type":"string"},"domain":{"type":"string"},"network":{"type":"string"}}},"IpApiCompanyInfo":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"abuser_score":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"Organization type (e.g. `hosting`)."},"network":{"type":"string","nullable":true},"whois":{"type":"string","nullable":true,"description":"May be omitted or sanitized server-side."}}},"IpApiAbuseContact":{"type":"object","properties":{"name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}},"IpApiAsnInfo":{"type":"object","required":["asn"],"properties":{"asn":{"type":"number"},"abuser_score":{"type":"string","nullable":true},"route":{"type":"string","nullable":true},"descr":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Lowercase country code."},"active":{"type":"boolean","nullable":true},"org":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"abuse":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"created":{"type":"string","nullable":true,"description":"YYYY-MM-DD."},"updated":{"type":"string","nullable":true,"description":"YYYY-MM-DD."},"rir":{"type":"string","nullable":true},"whois":{"type":"string","nullable":true,"description":"May be omitted or sanitized server-side."}}},"IpApiLocationInfo":{"type":"object","properties":{"is_eu_member":{"type":"boolean","nullable":true},"calling_code":{"type":"string","nullable":true},"currency_code":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"latitude":{"type":"number","format":"float","nullable":true},"longitude":{"type":"number","format":"float","nullable":true},"zip":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"local_time":{"type":"string","nullable":true,"description":"ISO string."},"local_time_unix":{"type":"number","nullable":true,"description":"Epoch seconds."},"is_dst":{"type":"boolean","nullable":true}}},"ProcessedEventVpnSummary":{"type":"object","required":["detected"],"properties":{"detected":{"type":"boolean","description":"Whether VPN/proxy usage is detected."},"confidence":{"type":"string","nullable":true,"description":"Confidence label (when available)."},"reason":{"type":"string","nullable":true,"description":"Reason/category for the VPN decision (when available)."},"browserTimezone":{"type":"string","nullable":true,"description":"Timezone reported by the browser/client signals."},"ipTimezone":{"type":"string","nullable":true,"description":"Timezone derived from IP intelligence."},"timezoneDifference":{"type":"number","nullable":true,"description":"Difference between browser and IP timezones in minutes (when available)."}}},"ProcessedEventVelocity":{"type":"object","required":["5m","1h","24h"],"properties":{"5m":{"type":"number","description":"Count in the last 5 minutes."},"1h":{"type":"number","description":"Count in the last 1 hour."},"24h":{"type":"number","description":"Count in the last 24 hours."}}},"ProcessedVisitorVelocity":{"type":"object","required":["5m","1h","24h","7d"],"properties":{"5m":{"type":"number"},"1h":{"type":"number"},"24h":{"type":"number"},"7d":{"type":"number"}}},"BotDetectionSummary":{"type":"object","required":["detected","score","automationSignalsPresent","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number","description":"Numeric score (higher generally indicates higher likelihood)."},"automationSignalsPresent":{"type":"boolean"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"IndicatorSeverity":{"type":"object","required":["source","severity"],"properties":{"source":{"type":"string"},"severity":{"type":"string","description":"Severity label for this indicator."}}},"TamperingSummary":{"type":"object","required":["detected","anomalyScore","antiDetectBrowser","indicators"],"properties":{"detected":{"type":"boolean"},"anomalyScore":{"type":"number"},"antiDetectBrowser":{"type":"boolean"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"PrivacySettingsSummary":{"type":"object","required":["detected","score","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"VirtualizationSummary":{"type":"object","required":["detected","confidence","indicators"],"properties":{"detected":{"type":"boolean"},"confidence":{"type":"string"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/VirtualizationIndicator"}}}},"VirtualizationIndicator":{"type":"object","required":["source","confidence"],"properties":{"source":{"type":"string"},"confidence":{"type":"string"}}},"IncognitoSummary":{"type":"object","required":["detected","score","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"ErrorResponse":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Human-readable error message."},"stack":{"type":"string","nullable":true,"description":"Present only in non-production environments."}}}}},"paths":{"/request/event/{id}":{"get":{"tags":["Events"],"operationId":"getProcessedEventById","summary":"Get processed event by id","description":"Returns a processed view of an event for fraud / risk evaluation.\n\n**Authentication**\nPass your secret key as a Bearer token: `Authorization: Bearer <secret>`.\nSecrets must not be sent as query parameters — they would be rejected by the upstream WAF\nand exposed in access logs.\n\n**Event availability / eventual consistency**\nEvents are processed asynchronously; the event may temporarily return `404` shortly after creation.\nThe official Server SDK retries `404` for a short time window.\n","parameters":[{"in":"path","name":"id","required":true,"description":"Guardian event identifier (e.g. `evt_123`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Processed event payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessedEventResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing or invalid secret key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Payment required (free quota exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden (event does not belong to the key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event not found (may occur while the event is still processing)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## List processed events (paginated)

> Returns a paginated list of processed events for the authenticated site.\
> \
> \*\*Authentication\*\*\
> Pass your secret key as a Bearer token: \`Authorization: Bearer \<secret>\`.\
> Secrets must not be sent as query parameters — they would be rejected by the upstream WAF\
> and exposed in access logs.\
> \
> \*\*Pagination\*\*\
> Uses cursor-based pagination for stable, efficient traversal.\
> \- Use \`limit\` to control page size (1-100, default 20)\
> \- Use \`cursor\` from the previous response's \`pagination.nextCursor\` to fetch the next page\
> \- Check \`pagination.hasMore\` to determine if more results exist\
> \
> \*\*Filtering\*\*\
> \- \`visitorId\`: Filter events by visitor identifier\
> \- \`before\` / \`after\`: Filter by timestamp range (ISO 8601 format)\
> \- \`order\`: Sort direction (\`desc\` for newest first, \`asc\` for oldest first)<br>

```json
{"openapi":"3.0.3","info":{"title":"Guardian Stack API","version":"1.0.0"},"tags":[{"name":"Events","description":"Retrieve processed events for server-side fraud/risk decisions."}],"servers":[{"url":"https://api.guardianstack.ai","description":"Production (default base URL used by the Server SDK)"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"token","description":"Use your Guardian **secret key** as a Bearer token.\n\nExample: `Authorization: Bearer sec_xxx`\n\nDo not pass the secret as a query parameter (`?secret=...`) — such requests are blocked\nby the upstream WAF and would leak credentials into access logs and referrers.\n"}},"schemas":{"PaginatedEventsResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProcessedEventResponse"},"description":"Array of processed events for the current page."},"pagination":{"$ref":"#/components/schemas/PaginationMeta"}}},"ProcessedEventResponse":{"type":"object","required":["identification"],"properties":{"identification":{"$ref":"#/components/schemas/ProcessedEventIdentification"},"ipInfo":{"allOf":[{"$ref":"#/components/schemas/IpApiIsResponse"}],"nullable":true,"description":"IP intelligence payload used during processing.\nNote: some fields (e.g. `company.whois`, `asn.whois`) may be sanitized server-side.\n"},"vpn":{"allOf":[{"$ref":"#/components/schemas/ProcessedEventVpnSummary"}],"nullable":true},"velocity":{"allOf":[{"$ref":"#/components/schemas/ProcessedEventVelocity"}],"nullable":true,"description":"Event-level request velocity (counts) over sliding windows."},"visitorVelocity":{"allOf":[{"$ref":"#/components/schemas/ProcessedVisitorVelocity"}],"nullable":true,"description":"Visitor-level request velocity (counts) over sliding windows."},"botDetection":{"allOf":[{"$ref":"#/components/schemas/BotDetectionSummary"}],"nullable":true},"tampering":{"allOf":[{"$ref":"#/components/schemas/TamperingSummary"}],"nullable":true},"privacySettings":{"allOf":[{"$ref":"#/components/schemas/PrivacySettingsSummary"}],"nullable":true},"virtualization":{"allOf":[{"$ref":"#/components/schemas/VirtualizationSummary"}],"nullable":true},"incognito":{"allOf":[{"$ref":"#/components/schemas/IncognitoSummary"}],"nullable":true}}},"ProcessedEventIdentification":{"type":"object","required":["id","ip"],"properties":{"id":{"type":"string","description":"Guardian event identifier."},"visitorId":{"type":"string","nullable":true,"description":"Stable, server-issued identifier for the visitor (site-scoped)."},"ip":{"type":"string","description":"Server-observed client IP address for the event."},"timestamp":{"type":"string","format":"date-time","nullable":true,"description":"ISO timestamp of event creation."},"url":{"type":"string","nullable":true,"description":"Page URL as reported by the client during collection."},"location":{"allOf":[{"$ref":"#/components/schemas/LocationInfo"}],"nullable":true},"browser":{"$ref":"#/components/schemas/BrowserInfo"}}},"LocationInfo":{"type":"object","properties":{"is_eu_member":{"type":"boolean","nullable":true},"calling_code":{"type":"string","nullable":true},"currency_code":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true,"description":"Continent code (e.g. `EU`, `AS`, `NA`)."},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"latitude":{"type":"number","format":"float","nullable":true},"longitude":{"type":"number","format":"float","nullable":true},"zip":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"local_time":{"type":"string","nullable":true,"description":"Local time at the IP-derived location (ISO string)."},"is_dst":{"type":"boolean","nullable":true}}},"BrowserInfo":{"type":"object","properties":{"browserName":{"type":"string","nullable":true},"browserMajorVersion":{"type":"string","nullable":true},"browserFullVersion":{"type":"string","nullable":true},"platform":{"type":"string","nullable":true,"description":"Normalized platform label (e.g. `windows`, `mac`, `ios`, `android`, `linux`, `chromeos`)."},"os":{"type":"string","nullable":true},"osVersion":{"type":"string","nullable":true},"device":{"type":"string","nullable":true},"userAgent":{"type":"string","nullable":true}}},"IpApiIsResponse":{"type":"object","required":["ip","is_bogon","is_mobile","is_satellite","is_crawler","is_datacenter","is_tor","is_proxy","is_vpn","is_abuser"],"properties":{"ip":{"type":"string"},"rir":{"type":"string","nullable":true,"description":"Regional Internet Registry (e.g. `RIPE`, `ARIN`)."},"is_bogon":{"type":"boolean"},"is_mobile":{"type":"boolean"},"is_satellite":{"type":"boolean"},"is_crawler":{"type":"boolean"},"is_datacenter":{"type":"boolean"},"is_tor":{"type":"boolean"},"is_proxy":{"type":"boolean"},"is_vpn":{"type":"boolean"},"is_abuser":{"type":"boolean"},"vpn":{"allOf":[{"$ref":"#/components/schemas/IpApiVpnInfo"}],"nullable":true},"datacenter":{"allOf":[{"$ref":"#/components/schemas/IpApiDatacenterInfo"}],"nullable":true},"company":{"allOf":[{"$ref":"#/components/schemas/IpApiCompanyInfo"}],"nullable":true},"abuse":{"allOf":[{"$ref":"#/components/schemas/IpApiAbuseContact"}],"nullable":true},"asn":{"allOf":[{"$ref":"#/components/schemas/IpApiAsnInfo"}],"nullable":true},"location":{"allOf":[{"$ref":"#/components/schemas/IpApiLocationInfo"}],"nullable":true},"elapsed_ms":{"type":"number","nullable":true,"description":"Upstream lookup latency in milliseconds (when available)."}}},"IpApiVpnInfo":{"type":"object","required":["ip","service","url","type","last_seen","last_seen_str"],"properties":{"ip":{"type":"string"},"service":{"type":"string"},"url":{"type":"string"},"type":{"type":"string","description":"Category (e.g. `vpn_server`)."},"last_seen":{"type":"number","description":"Epoch milliseconds."},"last_seen_str":{"type":"string","description":"ISO timestamp."},"exit_node_region":{"type":"string","nullable":true}}},"IpApiDatacenterInfo":{"type":"object","required":["datacenter","domain","network"],"properties":{"datacenter":{"type":"string"},"domain":{"type":"string"},"network":{"type":"string"}}},"IpApiCompanyInfo":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"abuser_score":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"Organization type (e.g. `hosting`)."},"network":{"type":"string","nullable":true},"whois":{"type":"string","nullable":true,"description":"May be omitted or sanitized server-side."}}},"IpApiAbuseContact":{"type":"object","properties":{"name":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}},"IpApiAsnInfo":{"type":"object","required":["asn"],"properties":{"asn":{"type":"number"},"abuser_score":{"type":"string","nullable":true},"route":{"type":"string","nullable":true},"descr":{"type":"string","nullable":true},"country":{"type":"string","nullable":true,"description":"Lowercase country code."},"active":{"type":"boolean","nullable":true},"org":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"abuse":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"created":{"type":"string","nullable":true,"description":"YYYY-MM-DD."},"updated":{"type":"string","nullable":true,"description":"YYYY-MM-DD."},"rir":{"type":"string","nullable":true},"whois":{"type":"string","nullable":true,"description":"May be omitted or sanitized server-side."}}},"IpApiLocationInfo":{"type":"object","properties":{"is_eu_member":{"type":"boolean","nullable":true},"calling_code":{"type":"string","nullable":true},"currency_code":{"type":"string","nullable":true},"continent":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"latitude":{"type":"number","format":"float","nullable":true},"longitude":{"type":"number","format":"float","nullable":true},"zip":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"local_time":{"type":"string","nullable":true,"description":"ISO string."},"local_time_unix":{"type":"number","nullable":true,"description":"Epoch seconds."},"is_dst":{"type":"boolean","nullable":true}}},"ProcessedEventVpnSummary":{"type":"object","required":["detected"],"properties":{"detected":{"type":"boolean","description":"Whether VPN/proxy usage is detected."},"confidence":{"type":"string","nullable":true,"description":"Confidence label (when available)."},"reason":{"type":"string","nullable":true,"description":"Reason/category for the VPN decision (when available)."},"browserTimezone":{"type":"string","nullable":true,"description":"Timezone reported by the browser/client signals."},"ipTimezone":{"type":"string","nullable":true,"description":"Timezone derived from IP intelligence."},"timezoneDifference":{"type":"number","nullable":true,"description":"Difference between browser and IP timezones in minutes (when available)."}}},"ProcessedEventVelocity":{"type":"object","required":["5m","1h","24h"],"properties":{"5m":{"type":"number","description":"Count in the last 5 minutes."},"1h":{"type":"number","description":"Count in the last 1 hour."},"24h":{"type":"number","description":"Count in the last 24 hours."}}},"ProcessedVisitorVelocity":{"type":"object","required":["5m","1h","24h","7d"],"properties":{"5m":{"type":"number"},"1h":{"type":"number"},"24h":{"type":"number"},"7d":{"type":"number"}}},"BotDetectionSummary":{"type":"object","required":["detected","score","automationSignalsPresent","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number","description":"Numeric score (higher generally indicates higher likelihood)."},"automationSignalsPresent":{"type":"boolean"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"IndicatorSeverity":{"type":"object","required":["source","severity"],"properties":{"source":{"type":"string"},"severity":{"type":"string","description":"Severity label for this indicator."}}},"TamperingSummary":{"type":"object","required":["detected","anomalyScore","antiDetectBrowser","indicators"],"properties":{"detected":{"type":"boolean"},"anomalyScore":{"type":"number"},"antiDetectBrowser":{"type":"boolean"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"PrivacySettingsSummary":{"type":"object","required":["detected","score","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"VirtualizationSummary":{"type":"object","required":["detected","confidence","indicators"],"properties":{"detected":{"type":"boolean"},"confidence":{"type":"string"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/VirtualizationIndicator"}}}},"VirtualizationIndicator":{"type":"object","required":["source","confidence"],"properties":{"source":{"type":"string"},"confidence":{"type":"string"}}},"IncognitoSummary":{"type":"object","required":["detected","score","indicators"],"properties":{"detected":{"type":"boolean"},"score":{"type":"number"},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/IndicatorSeverity"}}}},"PaginationMeta":{"type":"object","required":["limit","hasMore"],"properties":{"limit":{"type":"integer","description":"Maximum number of items per page."},"hasMore":{"type":"boolean","description":"Whether there are more items after this page."},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor to fetch the next page.\nPass this value as the `cursor` query parameter in the next request.\nAbsent when there are no more results.\n"},"totalCount":{"type":"integer","nullable":true,"description":"Total count of matching items (only included when explicitly requested)."}}},"ErrorResponse":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Human-readable error message."},"stack":{"type":"string","nullable":true,"description":"Present only in non-production environments."}}}}},"paths":{"/request/events":{"get":{"tags":["Events"],"operationId":"getProcessedEvents","summary":"List processed events (paginated)","description":"Returns a paginated list of processed events for the authenticated site.\n\n**Authentication**\nPass your secret key as a Bearer token: `Authorization: Bearer <secret>`.\nSecrets must not be sent as query parameters — they would be rejected by the upstream WAF\nand exposed in access logs.\n\n**Pagination**\nUses cursor-based pagination for stable, efficient traversal.\n- Use `limit` to control page size (1-100, default 20)\n- Use `cursor` from the previous response's `pagination.nextCursor` to fetch the next page\n- Check `pagination.hasMore` to determine if more results exist\n\n**Filtering**\n- `visitorId`: Filter events by visitor identifier\n- `before` / `after`: Filter by timestamp range (ISO 8601 format)\n- `order`: Sort direction (`desc` for newest first, `asc` for oldest first)\n","parameters":[{"in":"query","name":"limit","required":false,"description":"Maximum number of events to return (1-100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"cursor","required":false,"description":"Opaque cursor for pagination. Use `nextCursor` from the previous response.","schema":{"type":"string"}},{"in":"query","name":"visitorId","required":false,"description":"Filter events by visitor identifier.","schema":{"type":"string"}},{"in":"query","name":"before","required":false,"description":"Return events created before this timestamp (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"after","required":false,"description":"Return events created on or after this timestamp (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"order","required":false,"description":"Sort order by creation time.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Paginated list of processed events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEventsResponse"}}}},"400":{"description":"Bad request (invalid cursor or parameters)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized (missing or invalid secret key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.guardianstack.ai/api-reference/reference/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.