> ## 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. # Timeline degli eventi del soggetto API > Didit elenca ogni evento di monitoraggio di un utente o azienda, dal più recente, tenendo separati individui e aziende con lo stesso vendor_data. Prompt API per ottenere la cronologia degli eventi del soggetto Copia il prompt negli appunti 
  \`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.\`
Incolla in Vedi [Lettura degli eventi](https://docs.didit.me/it/transaction-monitoring/events.md#lettura-degli-eventi) nella guida all'acquisizione degli eventi. Per cercare tra più soggetti, usa [Elenco degli eventi di monitoraggio](https://docs.didit.me/it/management-api/monitoring-events/list.md). ## OpenAPI ````yaml it/openapi-25.json GET /v3/events/subjects/{vendor_data}/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/events/subjects/{vendor_data}/: get: tags: - Monitoring Events summary: Recupera cronologia degli eventi del soggetto description: >- Elenca ogni evento di monitoraggio di un singolo soggetto, dal più recente in base a `occurred_at`. Un `vendor_data` è univoco solo all'interno dello stesso tipo di entità, per cui lo stesso id può indicare una persona fisica e un'azienda: `entity_type` seleziona la cronologia da visualizzare e il valore predefinito è `individual`, quindi per gli eventi di un'azienda è necessario `entity_type=company`. I filtri di `GET /v3/events/` si applicano in aggiunta e un `vendor_data` senza eventi restituisce una pagina vuota anziché `404`. Una chiave API con ambito limitato richiede `transactions: read`. Vedi [Lettura degli eventi registrati](https://docs.didit.me/it/transaction-monitoring/events#lettura-degli-eventi). operationId: get_monitoring_event_subject_timeline parameters: - name: vendor_data in: path required: true description: >- Il tuo ID per il soggetto (`subject.vendor_data` dei suoi eventi). Codificalo in formato URL; un valore contenente `/` non può essere indirizzato da questo endpoint. schema: type: string minLength: 1 maxLength: 255 example: user-42 - name: entity_type in: query required: false description: >- `company` restituisce l'azienda con questo `vendor_data`; qualsiasi altro valore, o nessuno, restituisce la persona fisica. `subject_entity_type` viene accettato come alias quando `entity_type` è assente. schema: type: string enum: - individual - company default: individual example: individual - name: limit in: query required: false description: >- Numero massimo di eventi per pagina. Il valore predefinito è 50. I valori superiori a 1000000 restituiscono `400`; un valore non numerico, pari a zero o negativo viene reimpostato su 50. schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 50 - name: offset in: query required: false description: >- Numero di eventi da saltare. Il valore predefinito è 0. È preferibile seguire l'URL `next` della risposta. schema: type: integer maximum: 1000000 minimum: 0 default: 0 example: 0 - name: event_category in: query required: false description: >- Solo gli eventi in queste categorie. Ripeti il parametro per più valori (`?event_category=payment&event_category=dispute`); viene restituito un evento corrispondente a uno qualsiasi di essi. 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: >- Solo gli eventi con questi tipi di azione (esatti, con distinzione tra maiuscole e minuscole). Ripeti per più valori. style: form explode: true schema: type: array items: type: string example: - deposit_completed - chargeback_opened - name: status in: query required: false description: Solo gli eventi con questi stati. Ripeti per più valori. 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: >- Solo gli eventi in queste classi di conservazione. Ripeti per più valori. 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: >- Corrispondenza esatta sul `business.vendor_data` inviato con l'evento. schema: type: string example: merchant-7 - name: session_id in: query required: false description: Corrispondenza esatta su `session.session_id`. schema: type: string example: web-session-abc - name: device_fingerprint in: query required: false description: Corrispondenza esatta su `device_context.fingerprint`. schema: type: string example: fp-a8c1 - name: ip_address in: query required: false description: Corrispondenza esatta sull'indirizzo IP dell'evento. schema: type: string example: 203.0.113.42 - name: game_id in: query required: false description: Corrispondenza esatta su `game_id` promosso. schema: type: string example: poker-holdem-01 - name: round_id in: query required: false description: Corrispondenza esatta su `round_id` promosso. schema: type: string example: round-88231 - name: affiliate_code in: query required: false description: Corrispondenza esatta su `affiliate_code` promosso. schema: type: string example: aff-summer - name: payment_reference_id in: query required: false description: >- Corrispondenza esatta sul riferimento di pagamento (da `transaction_context.payment_reference_id` o `payload.payment_reference_id`). schema: type: string example: dep_735 - name: counterparty_vendor_data in: query required: false description: Corrispondenza esatta su `counterparty_vendor_data` promosso. schema: type: string example: user-77 - name: matched_only in: query required: false description: >- `true` (anche `1` o `yes`, senza distinzione tra maiuscole e minuscole) restituisce solo gli eventi a cui corrisponde almeno una regola (`rules_matched_count` maggiore di 0). Qualsiasi altro valore viene ignorato. schema: type: boolean default: false example: true - name: occurred_from in: query required: false description: >- Solo gli eventi con `occurred_at` pari o successivo a questo istante (incluso). Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati. schema: type: string format: date-time example: '2026-10-01T00:00:00Z' - name: occurred_to in: query required: false description: >- Solo gli eventi con `occurred_at` pari o antecedente a questo istante (incluso). Una data da sola indica l'inizio di quel giorno, quindi `occurred_to=2026-10-15` esclude il resto del 15 ottobre; invia `2026-10-15T23:59:59Z` per includerlo. Invia un valore ISO 8601: `2026-10-01T00:00:00Z`, un offset esplicito con il `+` codificato in percentuale (`2026-10-01T02:00:00%2B02:00`; un `+` non codificato viene decodificato come spazio e il valore non risulta più analizzabile), oppure solo una data (`2026-10-01`), che indica le 00:00:00 UTC di quel giorno. Un valore privo di offset viene interpretato come UTC. I valori in qualsiasi altro formato non sono accettati. schema: type: string format: date-time example: '2026-10-17T23:59:59Z' - name: search in: query required: false description: >- Corrispondenza di sottostringhe senza distinzione tra maiuscole e minuscole su `event_id`, `action_type`, `subject_vendor_data` o `counterparty_vendor_data`. schema: type: string example: chargeback responses: '200': description: Una pagina degli eventi del soggetto. 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` o `offset` è maggiore di 1000000. Il corpo è un array JSON con un messaggio. Un `limit` non numerico o non positivo utilizza il valore predefinito di 50 invece di fallire. content: application/json: examples: limit too large: summary: limit superiore a 1000000 value: - limit must not exceed 1000000. offset too large: summary: offset superiore a 1000000 value: - offset must not exceed 1000000. '401': description: >- La chiave API con ambito è scaduta. Solo una chiave scaduta riceve `401`; una chiave mancante o non valida riceve `403`. content: application/json: examples: Expired key: value: detail: This API key has expired. '403': description: >- Intestazione `x-api-key` mancante (una chiave errata, revocata o scaduta restituisce `401`), una chiave con ambito priva di `transactions: read`, una chiave limitata ad alcuni workflow o a sessioni approvate (tale chiave non accede mai ai dati di monitoraggio delle transazioni), oppure una richiesta proveniente dall'esterno dell'allowlist IP della chiave. 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: >- Limite di frequenza superato: le richieste `GET` condividono un budget di 600 richieste al minuto per chiave API. Attendi `Retry-After` secondi, quindi riprova. headers: Retry-After: description: Secondi da attendere prima di effettuare un nuovo tentativo. 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: >- Una pagina di eventi di monitoraggio, con il valore di `occurred_at` più recente per primo. required: - count - next - previous - results properties: count: type: integer description: >- Numero di eventi corrispondenti, esatto fino a 100 e con limite massimo di 100 oltre tale soglia. Non calcolare il conteggio delle pagine da questo valore; segui `next` finché non è null. next: type: string format: uri nullable: true description: URL della pagina successiva, o null nell'ultima pagina. previous: type: string format: uri nullable: true description: URL della pagina precedente, o null nella prima pagina. results: type: array items: $ref: '#/components/schemas/MonitoringEvent' MonitoringEvent: type: object description: >- Un evento di monitoraggio memorizzato come restituito dagli endpoint dell'elenco e della cronologia del soggetto. Le evidenze con accesso limitato (payload, contesto del dispositivo, evidenze della regola) vengono restituite solo da `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: >- Identificatore Didit dell'evento. Utilizzalo come `{event_uuid}` nelle chiamate di recupero e cancellazione. event_id: type: string maxLength: 128 description: Il tuo identificatore, la chiave di idempotenza che hai inviato. event_category: type: string enum: - auth - session - gameplay - bonus - affiliate - payment - dispute - security - responsible_gambling - custom description: Categoria dell'evento. action_type: type: string maxLength: 128 description: >- Cosa è successo all'interno della categoria, così come l'hai inviato. occurred_at: type: string format: date-time description: Data e ora in cui l'evento si è verificato nel tuo sistema. received_at: type: string format: date-time description: Quando Didit ha accettato l'evento. status: type: string enum: - ACCEPTED - APPROVED - IN_REVIEW - DECLINED description: >- `ACCEPTED`: memorizzato, nessuna regola corrispondente ha modificato il suo stato (la risposta normale per la maggior parte degli eventi, e sempre la risposta in un'applicazione sandbox, dove non viene eseguita alcuna regola). `APPROVED`: una regola ha trovato corrispondenza e il punteggio è rimasto al di sotto della soglia di revisione. `IN_REVIEW`: una regola ha fatto superare al punteggio la soglia di revisione o ha impostato lo stato. `DECLINED`: una regola lo ha rifiutato o il punteggio ha superato la soglia di rifiuto. score: type: integer description: >- Punteggio cumulativo delle regole. Inizia da 0; le azioni `add_score` delle regole lo modificano (sono consentiti delta negativi). subject_vendor_data: type: string maxLength: 255 description: >- `subject.vendor_data` dell'evento: il tuo identificativo per l'utente o l'azienda. subject_entity_type: type: string description: >- `individual` o `company`: indica il tipo di soggetto a cui fa riferimento `subject_vendor_data`. example: individual subject_uuid: type: string format: uuid nullable: true description: >- UUID dell'utente (persona fisica) o dell'azienda a cui l'evento è stato ricondotto, oppure null se tale record non esiste più. counterparty_vendor_data: type: string nullable: true description: >- L'altro partecipante di un evento P2P (promosso da `payload.counterparty_vendor_data`). maxLength: 255 session_id: type: string nullable: true description: '`session.session_id` inviato con l''evento.' maxLength: 255 device_fingerprint: type: string nullable: true description: '`device_context.fingerprint` inviato con l''evento.' maxLength: 255 ip_address: type: string nullable: true description: >- Indirizzo IP dell'evento. Sul lato server è `device_context.network_context.ip_address` come lo hai inviato; sul lato dispositivo è l'IP della richiesta. maxLength: 64 ip_country: type: string nullable: true description: >- Codice del paese di `ip_address` ottenuto dall'arricchimento IP, oppure null quando l'indirizzo non è stato arricchito (telemetria mancante, privata o a basso valore il cui indirizzo non era già noto). example: ES amount: type: string nullable: true description: >- Importo come stringa decimale con 18 cifre decimali, da `transaction_context.amount`, `payload.amount` o `payload.stake_amount`, in quest'ordine. example: '250.000000000000000000' currency: type: string nullable: true description: Valuta da `transaction_context.currency` o `payload.currency`. maxLength: 10 game_id: type: string nullable: true description: Promosso da `payload.game_id`. maxLength: 128 round_id: type: string nullable: true description: Promosso da `payload.round_id`. maxLength: 128 bonus_id: type: string nullable: true description: Promosso da `payload.bonus_id`. maxLength: 128 affiliate_code: type: string nullable: true description: Promosso da `payload.affiliate_code`. maxLength: 128 payment_reference_id: type: string nullable: true description: >- Riferimento di pagamento da `transaction_context.payment_reference_id` o `payload.payment_reference_id`. maxLength: 255 retention_class: type: string enum: - low_value - standard - risk_relevant - monetary_or_compliance description: >- Classe di conservazione. Gli eventi di pagamento e contestazione sono `monetary_or_compliance`; gli eventi di sicurezza e gioco responsabile sono `risk_relevant`; `session.page_view`, `session.sdk_heartbeat`, `session.sdk_loaded`, `session.device_seen`, `session.bot_signal_observed`, `bonus.promotion_viewed` e `affiliate.referral_clicked` sono `low_value`; tutto il resto è `standard`. Un evento corrispondente a una regola attiva viene promosso a `risk_relevant` (senza mai essere retrocesso). rules_matched_count: type: integer minimum: 0 description: >- Numero di regole che hanno corrisposto all'evento, incluse le regole in modalità `TEST` (che registrano le prove ma non applicano azioni). correlation_pending: type: boolean description: >- `true` mentre una regola asincrona (correlazione tra soggetti o una sequenza superiore a 24 ore) deve ancora essere eseguita per questo evento. Si risolve entro pochi minuti e `status`, `score` e `rules_matched_count` vengono aggiornati sul posto. is_droppable: type: boolean description: >- Indica se un SDK sotto contropressione (backpressure) può ignorare eventi di questo tipo. `false` per ogni evento di `security`, `payment`, `dispute` e `responsible_gambling` e per `gameplay.bet_placed`, `gameplay.bet_settled` e `gameplay.p2p_settlement`. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.