> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # List Monitoring Events > List monitoring events with filters for category, status, subject, device, IP, payment reference and time window, newest first. List Monitoring Events API Prompt Copy prompt to clipboard 
  \`List and filter the monitoring events (logins, sessions, gameplay, bonuses, payments, disputes, security changes) stored for my Didit application.

  Endpoint:
  GET [https://verification.didit.me/v3/events/](https://verification.didit.me/v3/events/)

  Authentication:
  Use the x-api-key header with my Didit API key. A scoped key needs transactions: read.

  Goal:

  * Search events for a back-office screen, an export job or an investigation: for example every payment and dispute event a rule matched last week, or every event from one device fingerprint or IP address.

  Behavior:

  * Newest occurred\_at first. Paginated with limit (default 50) and offset; follow next until it is null.
  * count is exact up to 100 and capped at 100 above that, so never use it to compute the number of pages.
  * Every filter is optional and filters combine with AND. Multi-value filters repeat the parameter (?event\_category=payment\&event\_category=dispute) and match any of the values.
  * Filters: event\_category, action\_type, status, retention\_class (multi-value); subject\_vendor\_data, subject\_entity\_type (company for a company, any other value for an individual), business\_vendor\_data, session\_id, device\_fingerprint, ip\_address, game\_id, round\_id, affiliate\_code, payment\_reference\_id, counterparty\_vendor\_data (exact match); matched\_only=true; occurred\_from and occurred\_to (inclusive; ISO 8601 with Z or an offset whose + is sent as %2B, for example 2026-10-17T09:00:00Z, or a date alone, which means 00:00 UTC of that day); search (case-insensitive substring of event\_id, action\_type, subject\_vendor\_data or counterparty\_vendor\_data).
  * Each result is a summary. Call GET /v3/events/{event_uuid}/ for the payload, device context, IP enrichment and rule evidence.
  * For one subject, prefer GET /v3/events/subjects/{vendor_data}/, which keeps an individual and a company with the same vendor\_data apart.
  * Reads work whether or not event ingestion is switched on.

  Example call:
  curl -X GET "[https://verification.didit.me/v3/events/?event\_category=payment\&event\_category=dispute\&matched\_only=true\&limit=50](https://verification.didit.me/v3/events/?event_category=payment\&event_category=dispute\&matched_only=true\&limit=50)" \
  -H "x-api-key: YOUR\_API\_KEY"

  What to read from the response:

  * results\[].event\_uuid - Didit id of the event; use it as {event_uuid} in the detail and delete calls.
  * results\[].event\_id - your own id (the idempotency key you sent).
  * results\[].event\_category, action\_type, occurred\_at, received\_at.
  * results\[].status (ACCEPTED, APPROVED, IN\_REVIEW, DECLINED) and score.
  * results\[].rules\_matched\_count and correlation\_pending (true while an asynchronous rule still has to run).
  * results\[].ip\_country, device\_fingerprint, session\_id, amount, currency, payment\_reference\_id.
  * results\[].is\_droppable - whether an SDK under backpressure may drop events of this kind.
  * next - URL of the next page, or null.

  Failure modes:

  * 400 - limit or offset larger than 1000000.
  * 401 - the API key has expired.
  * 403 - missing or invalid API key, a scoped key without transactions: read, or a request from outside the key's IP list.
  * 429 - more than 600 reads per minute for this API key; honor Retry-After.

  Side effects: none. This is a pure read.

  For the full integration shape, see /integration/integration-prompt.\`
Paste into Events are filed in [retention classes](/transaction-monitoring/events.md#retention), so an event past the end of its class no longer appears here. See [Event ingestion](/transaction-monitoring/events.md#reading-events-back) for the filter reference and [Rules on events](/transaction-monitoring/event-rules.md) for what makes `rules_matched_count` move. ## OpenAPI ````yaml GET /v3/events/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: Identity verification API. Authenticate with x-api-key header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/events/: get: tags: - Monitoring Events summary: List monitoring events description: >- List the monitoring events stored for your application, newest `occurred_at` first, with optional filters that combine with AND. Multi-value filters (`event_category`, `action_type`, `status`, `retention_class`) repeat the parameter and match any of the values; the other filters are exact matches, and unknown values simply return no events. Each result is a summary: call `GET /v3/events/{event_uuid}/` for the payload, device context, IP enrichment and rule evidence, and prefer `GET /v3/events/subjects/{vendor_data}/` for one subject's history. Reads work whether or not event ingestion is switched on. A scoped API key needs `transactions: read`. See [Event ingestion](https://docs.didit.me/transaction-monitoring/events). operationId: list_monitoring_events parameters: - name: limit in: query required: false description: >- Maximum number of events per page. Defaults to 50. Values above 1000000 return `400`; a non-numeric, zero or negative value falls back to 50. schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 50 - name: offset in: query required: false description: >- Number of events to skip. Defaults to 0. Prefer following the `next` URL from the response. schema: type: integer maximum: 1000000 minimum: 0 default: 0 example: 0 - name: event_category in: query required: false description: >- Only events in these categories. Repeat the parameter for several values (`?event_category=payment&event_category=dispute`); an event matching any of them is returned. style: form explode: true schema: type: array items: type: string enum: - auth - session - gameplay - bonus - affiliate - payment - dispute - security - responsible_gambling - custom example: - payment - dispute - name: action_type in: query required: false description: >- Only events with these action types (exact, case-sensitive). Repeat for several values. style: form explode: true schema: type: array items: type: string example: - deposit_completed - chargeback_opened - name: status in: query required: false description: Only events with these statuses. Repeat for several values. style: form explode: true schema: type: array items: type: string enum: - ACCEPTED - APPROVED - IN_REVIEW - DECLINED example: - IN_REVIEW - DECLINED - name: retention_class in: query required: false description: Only events in these retention classes. Repeat for several values. style: form explode: true schema: type: array items: type: string enum: - low_value - standard - risk_relevant - monetary_or_compliance example: - risk_relevant - name: subject_vendor_data in: query required: false description: >- Exact match on the subject's `vendor_data`. The same id can name an individual and a company; add `subject_entity_type` to pick one, or use `GET /v3/events/subjects/{vendor_data}/`. schema: type: string example: user-42 - name: subject_entity_type in: query required: false description: >- `company` returns only events of company subjects; any other non-empty value (for example `individual`) returns only events of individuals. Omit it to return both. schema: type: string enum: - individual - company example: individual - name: business_vendor_data in: query required: false description: Exact match on the `business.vendor_data` sent with the event. schema: type: string example: merchant-7 - name: session_id in: query required: false description: Exact match on `session.session_id`. schema: type: string example: web-session-abc - name: device_fingerprint in: query required: false description: Exact match on `device_context.fingerprint`. schema: type: string example: fp-a8c1 - name: ip_address in: query required: false description: Exact match on the event's IP address. schema: type: string example: 203.0.113.42 - name: game_id in: query required: false description: Exact match on the promoted `game_id`. schema: type: string example: poker-holdem-01 - name: round_id in: query required: false description: Exact match on the promoted `round_id`. schema: type: string example: round-88231 - name: affiliate_code in: query required: false description: Exact match on the promoted `affiliate_code`. schema: type: string example: aff-summer - name: payment_reference_id in: query required: false description: >- Exact match on the payment reference (from `transaction_context.payment_reference_id` or `payload.payment_reference_id`). schema: type: string example: dep_735 - name: counterparty_vendor_data in: query required: false description: Exact match on the promoted `counterparty_vendor_data`. schema: type: string example: user-77 - name: matched_only in: query required: false description: >- `true` (also `1` or `yes`, case-insensitive) returns only events at least one rule matched (`rules_matched_count` above 0). Any other value is ignored. schema: type: boolean default: false example: true - name: occurred_from in: query required: false description: >- Only events with `occurred_at` at or after this instant (inclusive). Send an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with the `+` percent-encoded (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value no longer parses), or a date alone (`2026-10-01`), which means 00:00:00 UTC of that day. A value without an offset is read as UTC. Values in any other format are not accepted. schema: type: string format: date-time example: '2026-10-01T00:00:00Z' - name: occurred_to in: query required: false description: >- Only events with `occurred_at` at or before this instant (inclusive). A date alone means the start of that day, so `occurred_to=2026-10-15` excludes the rest of 15 October; send `2026-10-15T23:59:59Z` to include it. Send an ISO 8601 value: `2026-10-01T00:00:00Z`, an explicit offset with the `+` percent-encoded (`2026-10-01T02:00:00%2B02:00`; an unencoded `+` is decoded as a space and the value no longer parses), or a date alone (`2026-10-01`), which means 00:00:00 UTC of that day. A value without an offset is read as UTC. Values in any other format are not accepted. schema: type: string format: date-time example: '2026-10-17T23:59:59Z' - name: search in: query required: false description: >- Case-insensitive substring match on `event_id`, `action_type`, `subject_vendor_data` or `counterparty_vendor_data`. schema: type: string example: chargeback responses: '200': description: One page of event summaries. content: application/json: schema: $ref: '#/components/schemas/MonitoringEventPage' examples: Payment and dispute events: value: count: 2 next: null previous: null results: - event_uuid: 11111111-2222-3333-4444-555555555555 event_id: chargeback-2026-10-16-000318 event_category: dispute action_type: chargeback_opened occurred_at: '2026-10-16T14:02:11Z' received_at: '2026-10-16T14:02:12.418230Z' status: IN_REVIEW score: 60 subject_vendor_data: user-42 subject_entity_type: individual subject_uuid: 66666666-7777-8888-9999-000000000000 counterparty_vendor_data: null session_id: null device_fingerprint: null ip_address: null ip_country: null amount: '250.000000000000000000' currency: EUR game_id: null round_id: null bonus_id: null affiliate_code: null payment_reference_id: dep_735 retention_class: monetary_or_compliance rules_matched_count: 1 correlation_pending: false is_droppable: false - event_uuid: 22222222-3333-4444-5555-666666666666 event_id: login-2026-10-15-000912 event_category: auth action_type: login occurred_at: '2026-10-15T08:30:00.120000Z' received_at: '2026-10-15T08:30:00.734512Z' status: ACCEPTED score: 0 subject_vendor_data: user-42 subject_entity_type: individual subject_uuid: 66666666-7777-8888-9999-000000000000 counterparty_vendor_data: null session_id: web-session-abc device_fingerprint: fp-a8c1 ip_address: 203.0.113.42 ip_country: ES amount: null currency: null game_id: null round_id: null bonus_id: null affiliate_code: null payment_reference_id: null retention_class: standard rules_matched_count: 0 correlation_pending: false is_droppable: true '400': description: >- `limit` or `offset` is larger than 1000000. The body is a JSON array with one message. A non-numeric or non-positive `limit` falls back to the default of 50 instead of failing. content: application/json: examples: limit too large: summary: limit above 1000000 value: - limit must not exceed 1000000. offset too large: summary: offset above 1000000 value: - offset must not exceed 1000000. '401': description: >- The scoped API key has expired. Only an expired key gets `401`; a missing or invalid key gets `403`. content: application/json: examples: Expired key: value: detail: This API key has expired. '403': description: >- Missing or invalid `x-api-key` (this endpoint answers `403`, never `401`, for a missing or invalid key), a scoped key without `transactions: read`, a key limited to some workflows or to approved sessions (such a key never reaches transaction monitoring data), or a request from outside the key's IP allowlist. content: application/json: examples: Missing or invalid API key: value: detail: You do not have permission to perform this action. Scoped key without access: value: detail: This API key has no read access to transactions. Key limited to workflows or approved sessions: value: detail: >- This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint. IP not allowed: value: detail: This API key can't be used from this IP address. '429': description: >- Rate limit exceeded: `GET` requests share a budget of 600 requests per minute per API key. Wait `Retry-After` seconds, then retry. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 example: 30 content: application/json: examples: Throttled: value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X GET 'https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true&occurred_from=2026-10-01T00:00:00Z&limit=50' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- import os import requests url = 'https://verification.didit.me/v3/events/' params = { 'event_category': ['payment', 'dispute'], 'matched_only': 'true', 'occurred_from': '2026-10-01T00:00:00Z', 'limit': 50, } while url: resp = requests.get( url, headers={'x-api-key': os.environ['DIDIT_API_KEY']}, params=params, timeout=10, ) resp.raise_for_status() page = resp.json() for event in page['results']: print(event['event_uuid'], event['action_type'], event['status']) url, params = page['next'], None - lang: javascript label: JavaScript source: |- const params = new URLSearchParams([ ['event_category', 'payment'], ['event_category', 'dispute'], ['matched_only', 'true'], ['occurred_from', '2026-10-01T00:00:00Z'], ['limit', '50'], ]); let url = `https://verification.didit.me/v3/events/?${params}`; while (url) { const resp = await fetch(url, { headers: { 'x-api-key': process.env.DIDIT_API_KEY }, }); if (!resp.ok) throw new Error(`Request failed: ${resp.status}`); const page = await resp.json(); for (const event of page.results) console.log(event.event_uuid, event.action_type, event.status); url = page.next; } components: schemas: MonitoringEventPage: type: object description: One page of monitoring events, newest `occurred_at` first. required: - count - next - previous - results properties: count: type: integer description: >- Number of matching events, exact up to 100 and capped at 100 above that. Do not compute page counts from it; follow `next` until it is null. next: type: string format: uri nullable: true description: URL of the next page, or null on the last page. previous: type: string format: uri nullable: true description: URL of the previous page, or null on the first page. results: type: array items: $ref: '#/components/schemas/MonitoringEvent' MonitoringEvent: type: object description: >- One stored monitoring event as returned by the list and subject-timeline endpoints. Restricted evidence (payload, device context, rule evidence) is only returned by `GET /v3/events/{event_uuid}/`. required: - event_uuid - event_id - event_category - action_type - occurred_at - received_at - status - score - subject_vendor_data - subject_entity_type - subject_uuid - counterparty_vendor_data - session_id - device_fingerprint - ip_address - ip_country - amount - currency - game_id - round_id - bonus_id - affiliate_code - payment_reference_id - retention_class - rules_matched_count - correlation_pending - is_droppable properties: event_uuid: type: string format: uuid description: >- Didit identifier of the event. Use it as `{event_uuid}` in the retrieve and delete calls. event_id: type: string maxLength: 128 description: Your own identifier, the idempotency key you sent. event_category: type: string enum: - auth - session - gameplay - bonus - affiliate - payment - dispute - security - responsible_gambling - custom description: Event category. action_type: type: string maxLength: 128 description: What happened within the category, as you sent it. occurred_at: type: string format: date-time description: When the event happened on your side. received_at: type: string format: date-time description: When Didit accepted the event. status: type: string enum: - ACCEPTED - APPROVED - IN_REVIEW - DECLINED description: >- `ACCEPTED`: stored, no matched rule changed its standing (the normal answer for most events, and always the answer in a sandbox application, where no rules run). `APPROVED`: a rule matched and the score stayed under your review threshold. `IN_REVIEW`: a rule pushed the score over the review threshold or set the status. `DECLINED`: a rule declined it or the score crossed your decline threshold. score: type: integer description: >- Accumulated rule score. Starts at 0; rule `add_score` actions move it (negative deltas are allowed). subject_vendor_data: type: string maxLength: 255 description: '`subject.vendor_data` of the event: your id for the user or company.' subject_entity_type: type: string description: >- `individual` or `company`: which kind of subject `subject_vendor_data` names. example: individual subject_uuid: type: string format: uuid nullable: true description: >- UUID of the user (individual) or company the event resolved to, or null when that record no longer exists. counterparty_vendor_data: type: string nullable: true description: >- The other player of a P2P event (promoted from `payload.counterparty_vendor_data`). maxLength: 255 session_id: type: string nullable: true description: '`session.session_id` sent with the event.' maxLength: 255 device_fingerprint: type: string nullable: true description: '`device_context.fingerprint` sent with the event.' maxLength: 255 ip_address: type: string nullable: true description: >- IP address of the event. On the server lane this is `device_context.network_context.ip_address` as you sent it; on the device lane it is the IP of the request. maxLength: 64 ip_country: type: string nullable: true description: >- Country code of `ip_address` from IP enrichment, or null when the address was not enriched (missing, private, or low-value telemetry whose address was not already known). example: ES amount: type: string nullable: true description: >- Amount as a decimal string with 18 decimal places, from `transaction_context.amount`, `payload.amount` or `payload.stake_amount`, in that order. example: '250.000000000000000000' currency: type: string nullable: true description: Currency from `transaction_context.currency` or `payload.currency`. maxLength: 10 game_id: type: string nullable: true description: Promoted from `payload.game_id`. maxLength: 128 round_id: type: string nullable: true description: Promoted from `payload.round_id`. maxLength: 128 bonus_id: type: string nullable: true description: Promoted from `payload.bonus_id`. maxLength: 128 affiliate_code: type: string nullable: true description: Promoted from `payload.affiliate_code`. maxLength: 128 payment_reference_id: type: string nullable: true description: >- Payment reference from `transaction_context.payment_reference_id` or `payload.payment_reference_id`. maxLength: 255 retention_class: type: string enum: - low_value - standard - risk_relevant - monetary_or_compliance description: >- Retention class. Payment and dispute events are `monetary_or_compliance`; security and responsible-gambling events are `risk_relevant`; `session.page_view`, `session.sdk_heartbeat`, `session.sdk_loaded`, `session.device_seen`, `session.bot_signal_observed`, `bonus.promotion_viewed` and `affiliate.referral_clicked` are `low_value`; everything else is `standard`. An event an active rule matched is promoted to `risk_relevant` (never demoted). rules_matched_count: type: integer minimum: 0 description: >- Number of rules that matched the event, including rules in `TEST` mode (which record evidence but apply no actions). correlation_pending: type: boolean description: >- `true` while an asynchronous rule (cross-subject correlation, or a sequence longer than 24 hours) still has to run for this event. It resolves within minutes and `status`, `score` and `rules_matched_count` update in place. is_droppable: type: boolean description: >- Whether an SDK under backpressure may drop events of this kind. `false` for every `security`, `payment`, `dispute` and `responsible_gambling` event and for `gameplay.bet_placed`, `gameplay.bet_settled` and `gameplay.p2p_settlement`. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is missing, wrong, revoked or expired; 403 means the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.