> ## 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. # Sitzungsereignisse abrufen API > Ruft die Ereignis-Timeline einer Sitzung in Didit ab: Geräteschritte, Statusänderungen, Workflow-Routing, neueste zuerst, paginiert. Prompt für die API zum Auflisten von Sitzungsereignissen Prompt in die Zwischenablage kopieren 
  \`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.\`
Einfügen in Die Workflow-Routing-Ereignisse (`WORKFLOW_BRANCH_EVALUATED`, `WORKFLOW_STATUS_NODE_REACHED`) und ihre `details` werden in [Sitzung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session.md) beschrieben. Dort kann mit `?include=events` außerdem die Zeitleiste einer Sitzung der Benutzerverifizierung (KYC) innerhalb ihrer Entscheidung zurückgegeben werden. ## OpenAPI ````yaml de/openapi-25.json GET /v3/session/{sessionId}/events/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/session/{sessionId}/events/: get: tags: - Sessions summary: Sitzungsereignisse auflisten description: >- Lesen Sie die Ereignis-Zeitleiste einer einzelnen Verifizierungssitzung aus, sortiert nach `sent_at` (neueste zuerst): die Bildschirme, die der Benutzer gesehen hat, Schaltflächen und Uploads, fehlgeschlagene Versuche, Status- und Funktionsschritt-Änderungen sowie das Workflow-Routing-Protokoll. Funktioniert für Sitzungs-IDs der Benutzerverifizierung (KYC) und Unternehmensverifizierung (KYB). Ereignisse werden asynchron gespeichert, sodass ein neues Ereignis einige Sekunden benötigen kann, um zu erscheinen. Die Ergebnisse sind mit `limit` und `offset` paginiert; folgen Sie `next`, bis dieser `null` ist. Ein berechtigungsbeschränkter API-Schlüssel erfordert `sessions: read` und `decisions: read`; ohne `media: read` wird `file_url` als `null` zurückgegeben. Die Routing-Ereignisse sind in [Sitzung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session) beschrieben. operationId: get_v3_session_events parameters: - name: sessionId in: path required: true description: >- UUID der Verifizierungssitzung (die von `POST /v3/session/` zurückgegebene `session_id`). Akzeptiert Sitzungs-IDs sowohl für die Benutzerverifizierung (KYC) als auch für die Unternehmensverifizierung (KYB): Der Server löst die ID über beide Sitzungstypen hinweg auf. Muss eine wohlgeformte UUID sein; ein fehlerhafter Wert entspricht nicht der Route und gibt ein HTML-`404` zurück. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 - name: limit in: query required: false description: >- Maximale Anzahl an Ereignissen pro Seite. Standardmäßig 50. Ein Wert unter 1 oder ein nicht-numerischer Wert fällt auf 50 zurück; ein Wert über 1.000.000 gibt `400` zurück. schema: type: integer default: 50 minimum: 1 maximum: 1000000 example: 50 - name: offset in: query required: false description: >- Anzahl der vor dem ersten zurückgegebenen Ergebnis zu überspringenden Ergebnisse. Standardmäßig 0; ein negativer oder nicht-numerischer Wert fällt auf 0 zurück, ein Wert über 1.000.000 gibt `400` zurück. Folgen Sie vorzugsweise den `next`- und `previous`-URLs. schema: type: integer default: 0 minimum: 0 maximum: 1000000 example: 0 - name: ordering in: query required: false description: >- Optionale Überschreibung der Sortierung. Die Standardreihenfolge ist `-sent_at`. Übergeben Sie den Namen eines Ergebnisfelds (z. B. `sent_at`, `created_at`, `event_type`, `feature_step` oder `step`), um aufsteigend zu sortieren, stellen Sie ein `-` voran, um absteigend zu sortieren, und trennen Sie mehrere Felder durch Kommas. Unbekannte Felder werden ignoriert. schema: type: string example: sent_at responses: '200': description: Eine Seite mit den Ereignissen der Sitzung, neueste zuerst. content: application/json: schema: type: object required: - count - next - previous - results properties: count: type: integer description: Gesamtzahl der Ereignisse der Sitzung. next: type: string format: uri nullable: true description: URL der nächsten Seite oder `null` auf der letzten Seite. previous: type: string format: uri nullable: true description: URL der vorherigen Seite oder `null` auf der ersten Seite. 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` oder `offset` liegt über 1,000,000. Der Body ist ein JSON-Array mit einer Nachricht. 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: >- Der API-Schlüssel mit eingeschränktem Geltungsbereich ist abgelaufen. Dies ist der einzige Fall, der `401` zurückgibt: Ein fehlender, ungültiger oder widerrufener Schlüssel gibt `403` zurück. content: application/json: schema: type: object properties: detail: type: string description: Lesbare Fehlermeldung. examples: Expired key: summary: Das Ablaufdatum des Schlüssels ist überschritten value: detail: This API key has expired. '403': description: >- Authentifizierungs- oder Autorisierungsfehler. Ein fehlender Schlüssel gibt `403` zurück, ebenso wie der Schlüssel einer anderen Anwendung, ein berechtigungsbeschränkter Schlüssel ohne die für diesen Endpoint erforderliche Berechtigung sowie eine Anfrage von außerhalb der IP-Allowlist des Schlüssels; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Unterscheiden Sie diese anhand von `detail`. content: application/json: schema: type: object properties: detail: type: string description: Lesbare Fehlermeldung. examples: Missing or invalid credentials: summary: >- Kein x-api-key-Header vorhanden oder die Validierung des Schlüssels ist fehlgeschlagen value: detail: >- Authentication credentials were not provided or are invalid. Other application: summary: >- Ein gültiger Schlüssel, der zu einer anderen Anwendung als die Sitzung gehört value: detail: You do not have permission to perform this action. Scoped key without sessions read: summary: >- Dem Schlüssel mit eingeschränktem Berechtigungsumfang fehlt sessions: read value: detail: This API key has no read access to sessions. Scoped key without decisions read: summary: >- Dem Schlüssel mit eingeschränktem Berechtigungsumfang fehlt decisions: read value: detail: This API key has no read access to decisions. IP not allowed: summary: Anfrage von außerhalb der IP-Allowlist des Schlüssels value: detail: This API key can't be used from this IP address. '404': description: >- Die Sitzung existiert nicht, wurde gelöscht oder liegt außerhalb der Beschränkungen eines Scoped Keys hinsichtlich des Workflows oder der Beschränkung auf genehmigte Sitzungen. Die Sitzungssuche erfolgt vor der Prüfung der Anmeldedaten, sodass eine unbekannte `sessionId` auch ohne gültigen Schlüssel `404` zurückgibt. content: application/json: schema: type: object properties: detail: type: string description: Lesbare Fehlermeldung. examples: Unknown session: summary: >- Es existiert keine Sitzung mit dieser ID oder sie wurde gelöscht value: detail: Not found. Outside key limits: summary: >- Die Sitzung liegt außerhalb der Beschränkungen eines Scoped Keys hinsichtlich des Workflows oder der Beschränkung auf genehmigte Sitzungen value: detail: Session not found. '429': description: >- Rate-Limit überschritten: 600 GET-Anfragen pro Minute pro API-Schlüssel. Warten Sie `Retry-After` Sekunden vor einem Wiederholungsversuch; die `X-RateLimit-*`-Header zeigen das Kontingent an. content: application/json: schema: type: object properties: detail: type: string description: Lesbare Fehlermeldung. examples: Rate limited: summary: Budget für die aktuelle Minute erschöpft value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. headers: Retry-After: description: >- Sekunden, die vor einem Wiederholungsversuch gewartet werden müssen. 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: Ein Eintrag in der Ereignis-Timeline einer Verifizierungssitzung. 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: Ereigniskennung. 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: >- Was passiert ist. Vom Gerät während des gehosteten Flows oder SDKs gemeldet: `LINK_OPENED`, `STEP_RENDERED`, `BUTTON_CLICKED`, `FORM_SUBMITTED`, `FILE_UPLOADED`, `ATTEMPT_FAILED` und `LOG` (Debugging). Vom Server aufgezeichnet: `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` und `WORKFLOW_STATUS_NODE_REACHED` (der Workflow-Routing-Trace). `SESSION_COMPLETED`, `NOTE_ADDED` und `MANUAL_REVIEW_STARTED` können bei älteren Sitzungen vorkommen. created_at: type: string format: date-time description: >- Wann Didit das Ereignis gespeichert hat. Ereignisse werden asynchron gespeichert, einige Sekunden nach `sent_at`. component: type: string nullable: true description: UI-Komponente, die das Ereignis gemeldet hat (nur Geräteereignisse). 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: >- Verifizierungsfunktion, in der sich die Sitzung befand, als das Ereignis eintrat. step: type: string nullable: true description: >- Bildschirm innerhalb der Funktion, beispielsweise `DOCUMENT_CAPTURE_FRONT` oder `FACE_PASSIVE_LIVENESS`. details: type: object nullable: true additionalProperties: true description: Ereignisspezifische Daten. Die Schlüssel hängen von `event_type` ab. ip_address: type: string nullable: true description: >- Adresse, von der das Gerät das Ereignis gemeldet hat. `null` für serverseitig erfasste Ereignisse. user_agent: type: string nullable: true description: >- User-Agent des Geräts. `null` bei serverseitig erfassten Ereignissen. device_info: type: object nullable: true additionalProperties: true description: Gerätedetails, die das SDK oder der Browser gemeldet hat. file_url: type: string format: uri nullable: true description: >- Kurzlebiger vorsignierter Link zu einer an das Ereignis angehängten Datei (zum Beispiel ein aufgenommenes Bild). `null`, wenn keine vorhanden ist, und immer `null` für einen berechtigungseingeschränkten API-Schlüssel ohne `media: read`. sent_at: type: integer format: int64 description: >- Wann das Ereignis stattgefunden hat, als Unix-Zeitstempel in Millisekunden. Die Ergebnisse werden danach sortiert. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.