> ## 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: خطوات الجهاز وتغييرات الحالة وتوجيه سير العمل، من الأحدث إلى الأقدم مع ترقيم الصفحات. موجّه واجهة برمجة التطبيقات لعرض أحداث الجلسة نسخ الموجّه إلى الحافظة 
  \`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/ar/sessions-api/retrieve-session.md)، والذي يمكنه أيضاً إرجاع الجدول الزمني لجلسة التحقق من المستخدمين (KYC) ضمن قرارها باستخدام `?include=events`. ## OpenAPI ````yaml ar/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). يتم تخزين الأحداث بشكل غير متزامن، لذا قد يستغرق ظهور الحدث الجديد بضع ثوانٍ. النتائج مقسمة إلى صفحات باستخدام `limit` و `offset`؛ اتبع `next` حتى تصبح `null`. يحتاج مفتاح API ذو النطاق المحدود إلى `sessions: read` و `decisions: read`، ودون `media: read` يتلقى `file_url` كـ `null`. أحداث التوجيه موصوفة في [استرداد الجلسة](https://docs.didit.me/ar/sessions-api/retrieve-session). operationId: get_v3_session_events parameters: - name: sessionId in: path required: true description: >- معرّف UUID لجلسة التحقق (`session_id` الذي تم إرجاعه بواسطة `POST /v3/session/`). يقبل معرّفات جلسات التحقق من المستخدمين (KYC) والتحقق من الشركات (KYB): يطابق الخادم المعرّف عبر كلا نوعي الجلسات. يجب أن يكون UUID صالح البنية؛ تؤدي القيمة غير صالحة البنية إلى عدم مطابقة المسار وإرجاع `404` بتنسيق HTML. 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`. يُفضّل تتبّع عناوين URL في `next` و`previous`. 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: >- فشل في المصادقة أو التفويض. يؤدي المفتاح المفقود إلى إرجاع `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: لا توجد جلسة بهذا المعرّف، أو أنها حُذفت value: detail: Not found. Outside key limits: summary: >- الجلسة خارج سير العمل أو حدود المقبولة فقط الخاصة بمفتاح ذي نطاق محدد value: detail: Session not found. '429': description: >- تم تجاوز حد المعدل: 600 طلب GET في الدقيقة لكل مفتاح API. انتظر لعدد الثواني المحدد في `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: مكوّن واجهة المستخدم الذي أبلغ عن الحدث (أحداث الجهاز فقط). 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: وكيل المستخدم للجهاز. `null` للأحداث المسجلة عبر الخادم. device_info: type: object nullable: true additionalProperties: true description: تفاصيل الجهاز التي أبلغ عنها الـ SDK أو المتصفح. file_url: type: string format: uri nullable: true description: >- رابط موقع مسبقاً قصير الأجل لملف مرفق بالحدث (على سبيل المثال صورة ملتقطة). يكون `null` عندما لا يوجد ملف، ودائماً `null` لمفتاح API ذي نطاق محدد بدون إذن `media: read`. sent_at: type: integer format: int64 description: >- وقت وقوع الحدث، كطابع زمني Unix بالمللي ثانية. يتم ترتيب النتائج بناءً عليه. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- مفتاح API الخاص بتطبيقك، من Developers -> API keys في Business Console. يمتلك المفتاح الأساسي وصولاً كاملاً. يمكن تحديد نطاق المفتاح المسمى: لا شيء، أو قراءة، أو كتابة لكل مورد، ومحدوداً ببعض مسارات العمل أو بالجلسات المقبولة، وبقائمة من عناوين IP، وبتاريخ انتهاء الصلاحية. يشير 401 إلى أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية؛ ويشير 403 إلى أنه لم يتم إرسال أي مفتاح، أو أن المفتاح ليس لديه حق الوصول إلى هذا المورد أو الإجراء، أو أن الطلب جاء من عنوان خارج قائمة عناوين IP الخاصة به؛ ويشير 404 في مسار جلسة إلى أن الجلسة خارج مسارات العمل أو الحالات الخاصة بالمفتاح. يتلقى المفتاح الذي لا يمتلك حق الوصول إلى الوسائط عناوين URL للصور ومقاطع الفيديو وملفات PDF كـ 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.