> ## 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 验证会话事件接口：读取指定会话的事件时间线，包括设备上报的步骤、状态变更和工作流路由，按从新到旧排序并分页返回。 列出会话事件 API 提示 将提示词复制到剪贴板 
  \`Read the event timeline of one Didit verification session through the API.

  Endpoint:
  GET [https://verification.didit.me/v3/session/\{session\_id}/events/](https://verification.didit.me/v3/session/\{session_id}/events/)

  Authentication:
  Send my Didit API key in the x-api-key header. A scoped key needs sessions: read and decisions: read.

  Goal:

  * See what happened during a session, step by step: which screens the user saw, where they stopped, which attempts failed, when the status changed and how the workflow routed the session.

  Behavior:

  * Works for user (KYC) and business (KYB) session IDs.
  * Ordered by sent\_at, newest first. sent\_at is a Unix timestamp in milliseconds.
  * Paginated with limit (default 50) and offset. The response is { count, next, previous, results }. Follow next until it is null.
  * Device-reported event types: LINK\_OPENED, STEP\_RENDERED, BUTTON\_CLICKED, FORM\_SUBMITTED, FILE\_UPLOADED, ATTEMPT\_FAILED, LOG. Server-recorded types include SESSION\_CREATED, SESSION\_STATUS\_CHANGED (details.old\_status, details.current\_status), FEATURE\_STEP\_CHANGED, WORKFLOW\_BRANCH\_EVALUATED and WORKFLOW\_STATUS\_NODE\_REACHED.
  * Events are stored asynchronously, so a new event can take a few seconds to appear.
  * file\_url is a short-lived presigned link; a scoped key without media: read receives it as null.

  Example call:
  curl -X GET "[https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?limit=50](https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?limit=50)" \
  -H "x-api-key: YOUR\_API\_KEY"

  What to read from the response:

  * results\[].event\_type, feature\_step (OCR, LIVENESS, FACE\_MATCH, ...) and step (the screen, for example DOCUMENT\_CAPTURE\_FRONT).
  * results\[].details: event-specific data; the keys vary by event\_type.
  * results\[].ip\_address, user\_agent and device\_info for device-reported events.
  * count, next and previous for pagination.

  Failure modes:

  * 400: limit or offset above 1,000,000.
  * 401: the API key has expired.
  * 403: missing key (a wrong, revoked or expired key gets 401), a key of another application, a scoped key without the permissions above, or a request from outside the key's IP allowlist.
  * 404: the session does not exist, was deleted, or is outside a scoped key's workflow or status limits.

  Side effects: none. This is a pure read.

  For the full integration shape, see /integration/integration-prompt.\`
粘贴到 工作流路由事件（`WORKFLOW_BRANCH_EVALUATED`、`WORKFLOW_STATUS_NODE_REACHED`）及其 `details` 在 [检索会话](https://docs.didit.me/zh/sessions-api/retrieve-session.md) 中有说明。该接口还可以通过 `?include=events` 在其决策中返回用户验证（KYC）会话的时间线。 ## OpenAPI ````yaml zh/openapi-25.json GET /v3/session/{sessionId}/events/ 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/session/{sessionId}/events/: get: tags: - Sessions summary: 列出会话事件 description: >- 读取单个验证会话的事件时间线，按 `sent_at` 倒序排列（最新的排在最前）：用户看到的页面、按钮点击和上传、失败的尝试、状态和功能步骤变更，以及工作流路由追踪。适用于用户验证（KYC）和企业验证（KYB）会话 ID。事件采用异步存储，因此新事件可能需要几秒钟才会显示。结果通过 `limit` 和 `offset` 进行分页；跟随 `next` 直至其为 `null`。限定作用域的 API 密钥需要 `sessions: read` 和 `decisions: read` 权限，若缺少 `media: read` 权限，接收到的 `file_url` 将为 `null`。路由事件在[检索会话](https://docs.didit.me/zh/sessions-api/retrieve-session)中进行了说明。 operationId: get_v3_session_events parameters: - name: sessionId in: path required: true description: >- 验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。 schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 - name: limit in: query required: false description: 每页最大事件数。默认值为 50。小于 1 的值或非数值将回退至 50；超过 1,000,000 的值将返回 `400`。 schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 50 - name: offset in: query required: false description: >- 返回第一条结果前跳过的结果数量。默认为 0；负数或非数字值将回退为 0，大于 1,000,000 的值将返回 `400`。建议优先使用 `next` 和 `previous` URL。 schema: type: integer default: 0 minimum: 0 maximum: 1000000 example: 0 - name: ordering in: query required: false description: >- 可选的排序覆盖设置。默认顺序为 `-sent_at`。传入结果字段名称（例如 `sent_at`、`created_at`、`event_type`、`feature_step` 或 `step`）进行升序排序，添加 `-` 前缀进行降序排序，多个字段之间用逗号分隔。未知字段将被忽略。 schema: type: string example: sent_at responses: '200': description: 该会话的一页事件，最新的排在最前。 content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer description: 会话的事件总数。 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/SessionEvent' examples: Completed session: value: count: 3 next: null previous: null results: - uuid: aaaaaaaa-1111-2222-3333-444444444444 event_type: SESSION_STATUS_CHANGED created_at: '2026-09-14T10:02:13.904512Z' component: null feature_step: null step: null details: old_status: In Progress current_status: Approved ip_address: null user_agent: null device_info: null file_url: null sent_at: 1789380131482 - uuid: bbbbbbbb-1111-2222-3333-444444444444 event_type: FEATURE_STEP_CHANGED created_at: '2026-09-14T10:01:49.210377Z' component: null feature_step: null step: null details: old_feature_step: OCR current_feature_step: LIVENESS ip_address: null user_agent: null device_info: null file_url: null sent_at: 1789380107103 - uuid: cccccccc-1111-2222-3333-444444444444 event_type: STEP_RENDERED created_at: '2026-09-14T10:01:00.581930Z' component: DocumentCapture feature_step: OCR step: DOCUMENT_CAPTURE_FRONT details: {} ip_address: 203.0.113.24 user_agent: >- Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1 device_info: device_model: iPhone file_url: null sent_at: 1789380058776 '400': description: '`limit` 或 `offset` 超过 1,000,000。响应体是包含一条消息的 JSON 数组。' content: application/json: examples: Limit too large: summary: limit=2000000 value: - limit must not exceed 1000000. Offset too large: summary: offset=2000000 value: - offset must not exceed 1000000. schema: type: array items: type: string '401': description: 作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。 content: application/json: schema: type: object properties: detail: type: string description: 便于人类阅读的错误消息。 examples: Expired key: summary: 密钥的到期日期已过 value: detail: This API key has expired. '403': description: >- 身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。 content: application/json: schema: type: object properties: detail: type: string description: 便于人类阅读的错误消息。 examples: Missing or invalid credentials: summary: 缺少 x-api-key 请求头，或该密钥验证失败 value: detail: >- Authentication credentials were not provided or are invalid. Other application: summary: 属于与该会话不同应用的有效密钥 value: detail: You do not have permission to perform this action. Scoped key without sessions read: summary: '作用域密钥缺少 sessions: read 权限' value: detail: This API key has no read access to sessions. Scoped key without decisions read: summary: '作用域密钥缺少 decisions: read 权限' value: detail: This API key has no read access to decisions. IP not allowed: summary: 来自密钥 IP 白名单之外的请求 value: detail: This API key can't be used from this IP address. '404': description: >- 会话不存在、已被删除，或超出了限定作用域密钥的工作流或仅限已通过状态的限制。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。 content: application/json: schema: type: object properties: detail: type: string description: 便于人类阅读的错误消息。 examples: Unknown session: summary: 不存在具有此 ID 的会话，或该会话已被删除 value: detail: Not found. Outside key limits: summary: 会话超出了限定作用域密钥的工作流或仅限已通过状态的限制 value: detail: Session not found. '429': description: >- 超出速率限制：每个 API 密钥每分钟最多 600 次 GET 请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 请求头显示了配额状态。 content: application/json: schema: type: object properties: detail: type: string description: 便于人类阅读的错误消息。 examples: Rate limited: summary: 当前分钟的预算已耗尽 value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. headers: Retry-After: description: 重试前需要等待的秒数。 schema: type: integer minimum: 1 example: 30 security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?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.sessions.list_events( "11111111-2222-3333-4444-555555555555", ): 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.sessions.listEvents("11111111-2222-3333-4444-555555555555")) { console.log(item); } - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListEventsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListEventsParams{})\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.sessions().listEvents("11111111-2222-3333-4444-555555555555")) { System.out.println(item); } - lang: php label: PHP source: >- sessions->listEvents('11111111-2222-3333-4444-555555555555') as $item) { print_r($item->toArray()); } - lang: ruby label: Ruby source: >- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new didit.sessions.list_events("11111111-2222-3333-4444-555555555555").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.Sessions.ListEventsAsync("11111111-2222-3333-4444-555555555555")) { Console.WriteLine(JsonSerializer.Serialize(item)); } components: schemas: SessionEvent: type: object description: 验证会话事件时间线中的一个条目。 required: - uuid - event_type - created_at - component - feature_step - step - details - ip_address - user_agent - device_info - file_url - sent_at properties: uuid: type: string format: uuid description: 事件标识符。 event_type: type: string enum: - SESSION_CREATED - SESSION_COMPLETED - SESSION_STATUS_CHANGED - LINK_OPENED - FORM_SUBMITTED - BUTTON_CLICKED - FILE_UPLOADED - ATTEMPT_FAILED - FEATURE_STEP_CHANGED - STEP_RENDERED - NOTE_ADDED - MANUAL_REVIEW_STARTED - WORKFLOW_BRANCH_EVALUATED - WORKFLOW_STATUS_NODE_REACHED - LOG description: >- 发生的情况。由设备在托管流程或 SDK 期间报告：`LINK_OPENED`、`STEP_RENDERED`、`BUTTON_CLICKED`、`FORM_SUBMITTED`、`FILE_UPLOADED`、`ATTEMPT_FAILED` 和 `LOG`（调试）。由服务器记录：`SESSION_CREATED`、`SESSION_STATUS_CHANGED`（`details.old_status`、`details.current_status`）、`FEATURE_STEP_CHANGED`（`details.old_feature_step`、`details.current_feature_step`）、`WORKFLOW_BRANCH_EVALUATED` 和 `WORKFLOW_STATUS_NODE_REACHED`（工作流路由追踪）。`SESSION_COMPLETED`、`NOTE_ADDED` 和 `MANUAL_REVIEW_STARTED` 可能会出现在较早的会话中。 created_at: type: string format: date-time description: Didit 存储该事件的时间。事件为异步存储，通常在 `sent_at` 之后数秒完成。 component: type: string nullable: true description: 报告该事件的 UI 组件（仅限设备事件）。 feature_step: type: string nullable: true enum: - OCR - OCR_BACK - NFC - AML - FACE - LIVENESS - FACE_MATCH - IP_ANALYSIS - AGE_ESTIMATION - PROOF_OF_ADDRESS - PHONE_VERIFICATION - EMAIL_VERIFICATION - FACE_SEARCH - DATABASE_VALIDATION - QUESTIONNAIRE - KYB_REGISTRY - KYB_DOCUMENTS - KYB_KEY_PEOPLE - DOCUMENT_AI - GEOLOCATION - null description: 事件发生时会话所处的验证功能。 step: type: string nullable: true description: 功能中的页面，例如 `DOCUMENT_CAPTURE_FRONT` 或 `FACE_PASSIVE_LIVENESS`。 details: type: object nullable: true additionalProperties: true description: 特定事件的数据。键取决于 `event_type`。 ip_address: type: string nullable: true description: 设备报告事件时所在的 IP 地址。对于服务器记录的事件为 `null`。 user_agent: type: string nullable: true description: 设备的 User-Agent。对于服务器记录的事件为 `null`。 device_info: type: object nullable: true additionalProperties: true description: SDK 或浏览器报告的设备详情。 file_url: type: string format: uri nullable: true description: >- 事件所附加文件（例如捕获的图像）的短期预签名链接。不存在时为 `null`，对于不具备 `media: read` 权限的受限作用域 API 密钥始终为 `null`。 sent_at: type: integer format: int64 description: 事件发生的时间，为 Unix 毫秒时间戳。结果按此排序。 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.