Events

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

Get processed event by id

get

https://api.guardianstack.aihttp://localhost:3000

/request/event/{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.

Authorizations

bearerAuth

AuthorizationstringRequired

Use your Guardian secret key as a Bearer token.

Example: Authorization: Bearer sec_xxx

Do not pass the secret as a query parameter (?secret=...) — such requests are blocked by the upstream WAF and would leak credentials into access logs and referrers.

Path parameters

idstringRequired

Guardian event identifier (e.g. evt_123).

Responses

200

Processed event payload

application/json

400

Bad request

application/json

401

Unauthorized (missing or invalid secret key)

application/json

402

Payment required (free quota exceeded)

application/json

403

Forbidden (event does not belong to the key)

application/json

404

Event not found (may occur while the event is still processing)

application/json

500

Unexpected server error

application/json

get/request/event/{id}

curlNode.js

curl -sS \
  -H "Authorization: Bearer sec_xxx" \
  "https://api.guardianstack.ai/request/event/evt_123"

{
  "identification": {
    "id": "evt_123",
    "visitorId": "vis_abc",
    "ip": "203.0.113.10",
    "timestamp": "2025-01-01T12:00:00.000Z",
    "url": "https://example.com/checkout",
    "location": {
      "country": "Italy",
      "country_code": "IT",
      "city": "Milan",
      "timezone": "Europe/Rome",
      "is_eu_member": true
    },
    "browser": {
      "browserName": "Chrome",
      "browserMajorVersion": "131",
      "browserFullVersion": "131.0.6778.0",
      "platform": "mac",
      "os": "Mac OS",
      "osVersion": "14.6",
      "device": "Desktop",
      "userAgent": "Mozilla/5.0 ..."
    }
  },
  "vpn": {
    "detected": false,
    "ipTimezone": "Europe/Rome"
  },
  "botDetection": {
    "detected": false,
    "score": 12,
    "automationSignalsPresent": false,
    "indicators": []
  },
  "velocity": {
    "5m": 1,
    "1h": 3,
    "24h": 12
  },
  "visitorVelocity": {
    "5m": 1,
    "1h": 3,
    "24h": 12,
    "7d": 80
  }
}

List processed events (paginated)

get

https://api.guardianstack.aihttp://localhost:3000

/request/events

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)

Authorizations

bearerAuth

AuthorizationstringRequired

Use your Guardian secret key as a Bearer token.

Example: Authorization: Bearer sec_xxx

Do not pass the secret as a query parameter (?secret=...) — such requests are blocked by the upstream WAF and would leak credentials into access logs and referrers.

Query parameters

limitinteger · min: 1 · max: 100Optional

Maximum number of events to return (1-100).

Default: 20

cursorstringOptional

Opaque cursor for pagination. Use nextCursor from the previous response.

visitorIdstringOptional

Filter events by visitor identifier.

beforestring · date-timeOptional

Return events created before this timestamp (ISO 8601).

Example: 2025-01-31T23:59:59Z

afterstring · date-timeOptional

Return events created on or after this timestamp (ISO 8601).

Example: 2025-01-01T00:00:00Z

orderstring · enumOptional

Sort order by creation time.

Default: descPossible values:

Responses

200

Paginated list of processed events

application/json

400

Bad request (invalid cursor or parameters)

application/json

401

Unauthorized (missing or invalid secret key)

application/json

500

Unexpected server error

application/json

get/request/events

curlNode.js

# Fetch first page
curl -sS \
  -H "Authorization: Bearer sec_xxx" \
  "https://api.guardianstack.ai/request/events?limit=20"

# Fetch next page using cursor
curl -sS \
  -H "Authorization: Bearer sec_xxx" \
  "https://api.guardianstack.ai/request/events?limit=20&cursor=eyJpZCI6..."

{
  "data": [
    {
      "identification": {
        "id": "evt_123",
        "visitorId": "vis_abc",
        "ip": "203.0.113.10",
        "timestamp": "2025-01-15T12:00:00.000Z",
        "url": "https://example.com/checkout",
        "location": {
          "country": "Italy",
          "country_code": "IT",
          "city": "Milan"
        },
        "browser": {
          "browserName": "Chrome",
          "platform": "mac"
        }
      },
      "vpn": {
        "detected": false
      },
      "botDetection": {
        "detected": false,
        "score": 12,
        "automationSignalsPresent": false,
        "indicators": []
      }
    },
    {
      "identification": {
        "id": "evt_122",
        "visitorId": "vis_abc",
        "ip": "203.0.113.10",
        "timestamp": "2025-01-15T11:55:00.000Z"
      },
      "vpn": {
        "detected": false
      },
      "botDetection": {
        "detected": false,
        "score": 8,
        "automationSignalsPresent": false,
        "indicators": []
      }
    }
  ],
  "pagination": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "eyJpZCI6ImV2dF8xMjIiLCJ0cyI6IjIwMjUtMDEtMTVUMTE6NTU6MDAuMDAwWiJ9"
  }
}