> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudeg.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> GET /v1/events — retrieve a paginated list of fraud events for your account. Filter by transaction, user, event type, and time range.

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

<ParamField query="transaction_id" type="string">
  Filter events associated with a specific transaction. Returns all event types
  that reference this transaction ID.
</ParamField>

<ParamField query="user_id" type="string">
  Filter events associated with a specific user. Useful for reviewing the full
  fraud history of a single account.
</ParamField>

<ParamField query="event_type" type="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
</ParamField>

<ParamField query="start_time" type="string">
  ISO 8601 timestamp. Only events created at or after this time are returned.
  Example: `2024-06-01T00:00:00Z`.
</ParamField>

<ParamField query="end_time" type="string">
  ISO 8601 timestamp. Only events created before or at this time are returned.
  Example: `2024-06-30T23:59:59Z`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results to return per page. Accepted range: `1`–`100`.
</ParamField>

<ParamField query="after" type="string">
  Pagination cursor. Pass the `next_cursor` value from a previous response to
  retrieve the next page of results.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Ordered list of event objects, sorted by `created_at` descending.

  <Expandable title="Event object fields">
    <ResponseField name="event_id" type="string">
      Unique identifier for this event. Stable and globally unique across your
      account.
    </ResponseField>

    <ResponseField name="event_type" type="string">
      The category of activity this event records. See `event_type` query
      parameter for the full list of values.
    </ResponseField>

    <ResponseField name="transaction_id" type="string | null">
      The transaction ID this event is associated with, or `null` if the event
      is not transaction-scoped (e.g., `device.session_created`).
    </ResponseField>

    <ResponseField name="user_id" type="string | null">
      The user ID this event is associated with, or `null` if no user context
      is available.
    </ResponseField>

    <ResponseField name="payload" type="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`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp recording when this event was written to the log.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  `true` if additional pages of results exist beyond this response.
</ResponseField>

<ResponseField name="next_cursor" type="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.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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"
}
```

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>