> ## 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/ko/sessions-api/retrieve-session.md)에 설명되어 있습니다. 이 엔드포인트는 `?include=events`를 사용하면 사용자 인증(KYC) 세션의 타임라인도 결정 정보 안에 함께 반환할 수 있습니다. ## OpenAPI ````yaml ko/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/ko/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을 초과합니다. 본문은 메시지 1개가 포함된 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: >- 인증 또는 권한 부여에 실패했습니다. 키가 누락된 경우 `403`이 반환되며, 다른 애플리케이션의 키, 이 endpoint에 필요한 권한이 없는 범위 지정 키, 키의 IP 허용 목록 외부에서 보낸 요청의 경우에도 마찬가지입니다. 잘못되었거나 취소되었거나 만료된 키는 `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: 인증 세션 이벤트 타임라인의 항목 1개입니다. 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: 기기가 이벤트를 보고한 주소입니다. 서버에 기록된 이벤트의 경우 `null`입니다. user_agent: type: string nullable: true description: 기기의 사용자 에이전트입니다. 서버에 기록된 이벤트의 경우 `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: >- Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.