> ## 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 프롬프트 프롬프트를 클립보드에 복사 
  \`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.\`
붙여넣을 곳 이벤트 수집 가이드의 [저장된 이벤트 조회](https://docs.didit.me/ko/transaction-monitoring/events.md#이벤트-조회)를 참고합니다. 여러 대상에 걸쳐 검색하려면 [모니터링 이벤트 목록](https://docs.didit.me/ko/management-api/monitoring-events/list.md)을 사용합니다. ## OpenAPI ````yaml ko/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/ko/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`을 반환하며, 숫자가 아니거나 0 또는 음수인 값은 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`. 인코딩되지 않은 `+`는 공백으로 디코딩되어 값이 더 이상 파싱되지 않음), 또는 해당 날짜의 00:00:00 UTC를 의미하는 날짜 단독 형식(`2026-10-01`). 오프셋이 없는 값은 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`. 인코딩되지 않은 `+`는 공백으로 디코딩되어 값이 더 이상 파싱되지 않음), 또는 해당 날짜의 00:00:00 UTC를 의미하는 날짜 단독 형식(`2026-10-01`). 오프셋이 없는 값은 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보다 큽니다. 본문은 메시지 1개가 포함된 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: >- 속도 제한 초과: `GET` 요청은 API 키당 분당 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: >- 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개로 제한됩니다. 이를 바탕으로 페이지 수를 계산하지 마십시오. null이 될 때까지 `next`를 따르십시오. 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에서 반환하는 저장된 모니터링 이벤트 1건입니다. 제한된 증거(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: >- 이벤트의 주소입니다. 서버 레인에서는 전송된 `device_context.network_context.ip_address`이며, 기기 레인에서는 요청의 주소입니다. maxLength: 64 ip_country: type: string nullable: true description: >- IP 보강을 통해 확인된 `ip_address`의 국가 코드이며, 주소가 보강되지 않은 경우(누락되었거나 사설 IP이거나 주소가 이미 알려져 있지 않은 저가치 텔레메트리인 경우) null입니다. example: ES amount: type: string nullable: true description: >- `transaction_context.amount`, `payload.amount`, `payload.stake_amount` 순서대로 가져온 소수점 이하 18자리의 십진수 문자열 금액입니다. 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: >- 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.