Fraud Events — List, Filter, and Query the Event Log

The Events API gives you access to the immutable audit log of all fraud-related activity on your account. Every time FraudEG’s risk engine evaluates a transaction, verifies an identity, creates a device session, triggers an alert, or records a decision, it writes an event to this log. You can query events by transaction, user, type, or time range to reconstruct exactly what happened and when — making this endpoint the foundation for compliance reporting, chargeback evidence packages, and real-time monitoring pipelines.

Endpoint

GET https://api.fraudeg.com/v1/events

Query Parameters

string

Filter events associated with a specific transaction. Returns all event types that reference this transaction ID.

string

Filter events associated with a specific user. Useful for reviewing the full fraud history of a single account.

string

Narrow results to a single event type. Accepted values:

transaction.scored — Risk score computed for a transaction
transaction.blocked — Transaction rejected by a rule or model
identity.verified — Identity check completed
device.session_created — New device session established
alert.triggered — Fraud alert generated by the detection engine
decision.submitted — Manual or automated decision recorded

string

ISO 8601 timestamp. Only events created at or after this time are returned. Example: 2024-06-01T00:00:00Z.

string

ISO 8601 timestamp. Only events created before or at this time are returned. Example: 2024-06-30T23:59:59Z.

integer

default:"20"

Number of results to return per page. Accepted range: 1–100.

string

Pagination cursor. Pass the next_cursor value from a previous response to retrieve the next page of results.

Response Fields

array

Ordered list of event objects, sorted by created_at descending.

Show Event object fields

string

Unique identifier for this event. Stable and globally unique across your account.

string

The category of activity this event records. See event_type query parameter for the full list of values.

string | null

The transaction ID this event is associated with, or null if the event is not transaction-scoped (e.g., device.session_created).

string | null

The user ID this event is associated with, or null if no user context is available.

object

Event-specific data. The shape of this object varies by event_type. For example, a transaction.scored event includes risk_score and risk_factors, while a decision.submitted event includes decision and reason_codes.

string

ISO 8601 timestamp recording when this event was written to the log.

boolean

true if additional pages of results exist beyond this response.

string | null

Opaque pagination cursor. Pass this value as the after query parameter in your next request. Returns null when you have reached the last page.

Examples

curl -G https://api.fraudeg.com/v1/events \
  -H "Authorization: Bearer $FRAUDEG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-urlencode "user_id=usr_4f9a2c1d" \
  --data-urlencode "event_type=transaction.scored" \
  --data-urlencode "start_time=2024-06-01T00:00:00Z" \
  --data-urlencode "end_time=2024-06-30T23:59:59Z" \
  --data-urlencode "limit=5"

Response

{
  "data": [
    {
      "event_id": "evt_7k2mxp91bz",
      "event_type": "transaction.scored",
      "transaction_id": "txn_9d3e1a7c",
      "user_id": "usr_4f9a2c1d",
      "payload": {
        "risk_score": 87,
        "risk_level": "high",
        "risk_factors": [
          "velocity_spike",
          "device_mismatch",
          "unusual_location"
        ],
        "model_version": "v4.2.1"
      },
      "created_at": "2024-06-14T09:32:11Z"
    },
    {
      "event_id": "evt_3n8qwt55fy",
      "event_type": "transaction.blocked",
      "transaction_id": "txn_9d3e1a7c",
      "user_id": "usr_4f9a2c1d",
      "payload": {
        "rule_id": "rule_block_high_risk",
        "rule_name": "Block High-Risk Transactions",
        "threshold": 80
      },
      "created_at": "2024-06-14T09:32:12Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_eyJvZmZzZXQiOjV9"
}

Events are append-only and immutable. Once written, an event record cannot be modified or deleted. This guarantees the integrity of your audit trail and ensures that historical records remain accurate regardless of downstream changes to transactions, users, or decisions.

Use the Events API to build a complete, timestamped audit trail for compliance and chargeback evidence. When disputing a chargeback, query all events for the relevant transaction_id and export the transaction.scored, transaction.blocked, and decision.submitted events to demonstrate that your fraud controls evaluated the transaction at the time of purchase.

Overview

Transactions

Identity

Monitoring

Fraud Events — List, Filter, and Query the Event Log

Endpoint

Query Parameters

Response Fields

Examples

Response

​Endpoint

​Query Parameters

​Response Fields

​Examples

​Response

Endpoint

Query Parameters

Response Fields

Examples

Response