> ## 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.

# 主体事件时间线 API

> Didit 可按时间倒序列出某一用户或企业的全部监控事件，并让共享同一 vendor_data 的个人与企业彼此分开，不相互混淆。

获取主体事件时间线 API 提示词
将提示词复制到剪贴板

<pre>
  \`Read the monitoring event timeline of one user or company in my Didit application.

  Endpoint:
  GET [https://verification.didit.me/v3/events/subjects/\{vendor\_data}/](https://verification.didit.me/v3/events/subjects/\{vendor_data}/)

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

  Goal:

  * Show one subject's activity (logins, sessions, gameplay, bonuses, payments, disputes, security changes) on a customer profile or in an investigation.

  Behavior:

  * vendor\_data is my own id for the subject (subject.vendor\_data of its events). URL-encode it; it cannot contain a slash.
  * vendor\_data is unique only within an entity type: the same id can name an individual and a company, and they are two subjects with two timelines.
  * entity\_type selects the subject: individual (default) or company. Without entity\_type=company, a company id returns the individual's timeline, not both. subject\_entity\_type is accepted as an alias.
  * Newest occurred\_at first, paginated with limit (default 50) and offset. count is capped at 100, so follow next until it is null.
  * The list filters of GET /v3/events/ apply on top: event\_category, action\_type, status, retention\_class (repeat for several values), business\_vendor\_data, session\_id, device\_fingerprint, ip\_address, game\_id, round\_id, affiliate\_code, payment\_reference\_id, counterparty\_vendor\_data, matched\_only, occurred\_from, occurred\_to, search. 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).
  * A vendor\_data with no events returns an empty page, not 404.

  Example call:
  curl -X GET "[https://verification.didit.me/v3/events/subjects/acct\_9931/?entity\_type=company\&limit=50](https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company\&limit=50)" \
  -H "x-api-key: YOUR\_API\_KEY"

  What to read from the response:

  * results\[] - event summaries (event\_uuid, event\_category, action\_type, occurred\_at, status, score, rules\_matched\_count, ip\_country, device\_fingerprint).
  * results\[].subject\_uuid - the user or company the events resolved to.
  * 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 API key (a wrong, revoked or expired key gets 401), 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.\`
</pre>

粘贴到

另请参阅事件接入指南中的[读取事件](https://docs.didit.me/zh/transaction-monitoring/events.md#读取事件)。如需跨主体搜索，请使用[列出监控事件](https://docs.didit.me/zh/management-api/monitoring-events/list.md)。


## OpenAPI

````yaml zh/openapi-25.json GET /v3/events/subjects/{vendor_data}/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/events/subjects/{vendor_data}/:
    get:
      tags:
        - Monitoring Events
      summary: 获取主体事件时间线
      description: >-
        列出单个主体的所有监控事件，按 `occurred_at` 最新的优先。`vendor_data` 仅在实体类型内部具有唯一性，因此相同的 ID
        可同时命名个人和公司：`entity_type` 用于选取您获取的时间线，其默认为 `individual`，因此公司事件需要指定
        `entity_type=company`。`GET /v3/events/` 的过滤器在其之上同样适用，且没有任何事件的
        `vendor_data` 会返回空页面而非 `404`。限定范围的 API 密钥需要 `transactions: read`
        权限。参见[回读事件](https://docs.didit.me/zh/transaction-monitoring/events#读取事件)。
      operationId: get_monitoring_event_subject_timeline
      parameters:
        - name: vendor_data
          in: path
          required: true
          description: >-
            您对主体的 ID（对应其事件的 `subject.vendor_data`）。请对其进行 URL 编码；包含 `/` 的值无法被该
            endpoint 寻址。
          schema:
            type: string
            minLength: 1
            maxLength: 255
          example: user-42
        - name: entity_type
          in: query
          required: false
          description: >-
            `company` 返回具有此 `vendor_data` 的企业；任何其他值或无值则返回个人。当 `entity_type`
            不存在时，接受 `subject_entity_type` 作为别名。
          schema:
            type: string
            enum:
              - individual
              - company
            default: individual
          example: individual
        - name: limit
          in: query
          required: false
          description: 每页最大事件数。默认值为 50。超过 1000000 的值将返回 `400`；非数值、零或负值将回退至 50。
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 1000000
          example: 50
        - name: offset
          in: query
          required: false
          description: 要跳过的事件数量。默认为 0。建议使用响应中的 `next` URL。
          schema:
            type: integer
            maximum: 1000000
            minimum: 0
            default: 0
          example: 0
        - name: event_category
          in: query
          required: false
          description: >-
            仅包含这些类别中的事件。对多个值重复该参数（`?event_category=payment&event_category=dispute`）；匹配其中任一类别的事件都会被返回。
          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: 仅包含具有这些操作类型的事件（精确匹配，区分大小写）。对多个值重复使用。
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          example:
            - deposit_completed
            - chargeback_opened
        - name: status
          in: query
          required: false
          description: 仅包含具有这些状态的事件。对多个值重复使用。
          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: 仅包含这些保留类别中的事件。对多个值重复使用。
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - low_value
                - standard
                - risk_relevant
                - monetary_or_compliance
          example:
            - risk_relevant
        - name: business_vendor_data
          in: query
          required: false
          description: 对随事件发送的 `business.vendor_data` 的精确匹配。
          schema:
            type: string
          example: merchant-7
        - name: session_id
          in: query
          required: false
          description: 对 `session.session_id` 的精确匹配。
          schema:
            type: string
          example: web-session-abc
        - name: device_fingerprint
          in: query
          required: false
          description: 对 `device_context.fingerprint` 的精确匹配。
          schema:
            type: string
          example: fp-a8c1
        - name: ip_address
          in: query
          required: false
          description: 对事件的 IP 地址进行精确匹配。
          schema:
            type: string
          example: 203.0.113.42
        - name: game_id
          in: query
          required: false
          description: 对已提升的 `game_id` 的精确匹配。
          schema:
            type: string
          example: poker-holdem-01
        - name: round_id
          in: query
          required: false
          description: 对已提升的 `round_id` 的精确匹配。
          schema:
            type: string
          example: round-88231
        - name: affiliate_code
          in: query
          required: false
          description: 对已提升的 `affiliate_code` 的精确匹配。
          schema:
            type: string
          example: aff-summer
        - name: payment_reference_id
          in: query
          required: false
          description: >-
            对支付参考信息的精确匹配（来自 `transaction_context.payment_reference_id` 或
            `payload.payment_reference_id`）。
          schema:
            type: string
          example: dep_735
        - name: counterparty_vendor_data
          in: query
          required: false
          description: 对已提升的 `counterparty_vendor_data` 的精确匹配。
          schema:
            type: string
          example: user-77
        - name: matched_only
          in: query
          required: false
          description: >-
            `true`（亦可为 `1` 或 `yes`，不区分大小写）仅返回匹配至少一条规则的事件（`rules_matched_count`
            大于 0）。任何其他值将被忽略。
          schema:
            type: boolean
            default: false
          example: true
        - name: occurred_from
          in: query
          required: false
          description: >-
            仅包含 `occurred_at` 在此时间点或之后（包含）的事件。发送 ISO 8601
            格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+`
            的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+`
            会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC
            读取。不接受任何其他格式的值。
          schema:
            type: string
            format: date-time
          example: '2026-10-01T00:00:00Z'
        - name: occurred_to
          in: query
          required: false
          description: >-
            仅包含 `occurred_at` 在此时间点或之前（包含）的事件。仅日期表示当天的开始，因此
            `occurred_to=2026-10-15` 会排除 10 月 15 日的其余时间；发送
            `2026-10-15T23:59:59Z` 以包含全天。发送 ISO 8601
            格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+`
            的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+`
            会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC
            读取。不接受任何其他格式的值。
          schema:
            type: string
            format: date-time
          example: '2026-10-17T23:59:59Z'
        - name: search
          in: query
          required: false
          description: >-
            对 `event_id`、`action_type`、`subject_vendor_data` 或
            `counterparty_vendor_data` 进行不区分大小写的子字符串匹配。
          schema:
            type: string
          example: chargeback
      responses:
        '200':
          description: 该主体的一页事件。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitoringEventPage'
              examples:
                Individual timeline:
                  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
                No events:
                  value:
                    count: 0
                    next: null
                    previous: null
                    results: []
        '400':
          description: >-
            `limit` 或 `offset` 大于 1000000。响应体是包含一条消息的 JSON 数组。非数字或非正数的 `limit`
            会回退到默认值 50，而不是失败。
          content:
            application/json:
              examples:
                limit too large:
                  summary: limit 超过 1000000
                  value:
                    - limit must not exceed 1000000.
                offset too large:
                  summary: offset 超过 1000000
                  value:
                    - offset must not exceed 1000000.
        '401':
          description: 作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。
          content:
            application/json:
              examples:
                Expired key:
                  value:
                    detail: This API key has expired.
        '403':
          description: >-
            缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: read`
            权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。
          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: 超出速率限制：每个 API 密钥的 `GET` 请求共享每分钟 600 次的配额。请等待 `Retry-After` 秒，然后重试。
          headers:
            Retry-After:
              description: 重试前需要等待的秒数。
              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/subjects/user-42/?entity_type=individual&limit=50'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            for item in client.monitoring_events.retrieve_subject_timeline(
                "user-42",
            ):
                print(item)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            for await (const item of
            didit.monitoringEvents.retrieveSubjectTimeline("user-42")) {
              console.log(item);
            }
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.RetrieveSubjectTimelineAutoPaging(ctx, \"user-42\", didit.MonitoringEventsRetrieveSubjectTimelineParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            for (var item :
            client.monitoringEvents().retrieveSubjectTimeline("user-42")) {
                System.out.println(item);
            }
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            foreach
            ($didit->monitoringEvents->retrieveSubjectTimeline('user-42') as
            $item) {
                print_r($item->toArray());
            }
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            didit.monitoring_events.retrieve_subject_timeline("user-42").auto_paging_each
            do |item|
              puts item.to_h
            end
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            await foreach (var item in await
            client.MonitoringEvents.RetrieveSubjectTimelineAsync("user-42"))

            {
                Console.WriteLine(JsonSerializer.Serialize(item));
            }
components:
  schemas:
    MonitoringEventPage:
      type: object
      description: 一页监控事件，按 `occurred_at` 由新到旧排序。
      required:
        - count
        - next
        - previous
        - results
      properties:
        count:
          type: integer
          description: 匹配事件的数量，不超过 100 时为精确值，超过 100 时上限为 100。请勿据此计算页数；请跟随 `next` 直至其为 null。
        next:
          type: string
          format: uri
          nullable: true
          description: 下一页的 URL，最后一页为 null。
        previous:
          type: string
          format: uri
          nullable: true
          description: 上一页的 URL，第一页为 null。
        results:
          type: array
          items:
            $ref: '#/components/schemas/MonitoringEvent'
    MonitoringEvent:
      type: object
      description: >-
        由列表和主体时间线 endpoint 返回的一条已存储监控事件。受限证据（payload、设备上下文、规则证据）仅通过 `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 标识符。在获取和删除调用中将其用作 `{event_uuid}`。
        event_id:
          type: string
          maxLength: 128
          description: 您自己的标识符，即您发送的幂等性密钥。
        event_category:
          type: string
          enum:
            - auth
            - session
            - gameplay
            - bonus
            - affiliate
            - payment
            - dispute
            - security
            - responsible_gambling
            - custom
          description: 事件类别。
        action_type:
          type: string
          maxLength: 128
          description: 该类别中发生的情况，与您发送的内容一致。
        occurred_at:
          type: string
          format: date-time
          description: 事件在您方发生的时间。
        received_at:
          type: string
          format: date-time
          description: Didit 接受该事件的时间。
        status:
          type: string
          enum:
            - ACCEPTED
            - APPROVED
            - IN_REVIEW
            - DECLINED
          description: >-
            `ACCEPTED`：已存储，没有匹配的规则改变其状态（大多数事件的常规响应，在不运行任何规则的沙盒应用中始终为此响应）。`APPROVED`：规则命中且评分低于您的审核阈值。`IN_REVIEW`：规则使评分超过审核阈值或直接设置了该状态。`DECLINED`：规则将其拒绝或评分超过了您的拒绝阈值。
        score:
          type: integer
          description: 累积规则分数。从 0 开始；规则的 `add_score` 操作会改变该分数（允许负增量）。
        subject_vendor_data:
          type: string
          maxLength: 255
          description: 事件的 `subject.vendor_data`：您为该用户或公司设置的 id。
        subject_entity_type:
          type: string
          description: '`individual` 或 `company`：`subject_vendor_data` 所指的主体类型。'
          example: individual
        subject_uuid:
          type: string
          format: uuid
          nullable: true
          description: 事件解析关联到的用户（个人）或企业的 UUID，如果该记录已不存在则为 null。
        counterparty_vendor_data:
          type: string
          nullable: true
          description: P2P 事件的另一方参与者（从 `payload.counterparty_vendor_data` 提升）。
          maxLength: 255
        session_id:
          type: string
          nullable: true
          description: 随事件发送的 `session.session_id`。
          maxLength: 255
        device_fingerprint:
          type: string
          nullable: true
          description: 随事件一同发送的 `device_context.fingerprint`。
          maxLength: 255
        ip_address:
          type: string
          nullable: true
          description: >-
            事件的 IP 地址。在服务器通道上，这是您发送的
            `device_context.network_context.ip_address`；在设备通道上，它是请求的 IP。
          maxLength: 64
        ip_country:
          type: string
          nullable: true
          description: >-
            通过 IP 信息增强获取的 `ip_address`
            国家/地区代码；如果地址未进行信息增强（缺失、私有或地址尚不可知的低价值遥测数据），则为 null。
          example: ES
        amount:
          type: string
          nullable: true
          description: >-
            保留 18 位小数的十进制字符串形式的金额，按优先级依次取自
            `transaction_context.amount`、`payload.amount` 或
            `payload.stake_amount`。
          example: '250.000000000000000000'
        currency:
          type: string
          nullable: true
          description: 来自 `transaction_context.currency` 或 `payload.currency` 的货币。
          maxLength: 10
        game_id:
          type: string
          nullable: true
          description: 从 `payload.game_id` 提取。
          maxLength: 128
        round_id:
          type: string
          nullable: true
          description: 从 `payload.round_id` 提取。
          maxLength: 128
        bonus_id:
          type: string
          nullable: true
          description: 由 `payload.bonus_id` 提升而来。
          maxLength: 128
        affiliate_code:
          type: string
          nullable: true
          description: 由 `payload.affiliate_code` 提升而来。
          maxLength: 128
        payment_reference_id:
          type: string
          nullable: true
          description: >-
            来自 `transaction_context.payment_reference_id` 或
            `payload.payment_reference_id` 的付款参考编号。
          maxLength: 255
        retention_class:
          type: string
          enum:
            - low_value
            - standard
            - risk_relevant
            - monetary_or_compliance
          description: >-
            数据保留类别。支付和争议事件为 `monetary_or_compliance`；安全与理性博彩事件为
            `risk_relevant`；`session.page_view`、`session.sdk_heartbeat`、`session.sdk_loaded`、`session.device_seen`、`session.bot_signal_observed`、`bonus.promotion_viewed`
            和 `affiliate.referral_clicked` 为 `low_value`；其他所有事件为
            `standard`。命中生效规则的事件将被提升为 `risk_relevant`（绝不降级）。
        rules_matched_count:
          type: integer
          minimum: 0
          description: 与该事件匹配的规则数量，包括处于 `TEST` 模式的规则（该模式仅记录证据但不执行任何操作）。
        correlation_pending:
          type: boolean
          description: >-
            当此事件仍需运行异步规则（跨主体关联，或时长超过 24 小时的序列）时为 `true`。它会在数分钟内处理完成，并就地更新
            `status`、`score` 和 `rules_matched_count`。
        is_droppable:
          type: boolean
          description: >-
            处于背压状态下的 SDK 是否可以丢弃此类事件。对于所有 `security`、`payment`、`dispute` 和
            `responsible_gambling` 事件，以及
            `gameplay.bet_placed`、`gameplay.bet_settled` 和
            `gameplay.p2p_settlement` 事件，此项均为 `false`。
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.