API Reference: Events
Endpoint REST untuk membaca arsip event per kategori dengan cursor-based pagination, opsi filter, detail event, ekspor asinkron, serta WebSocket channel untuk feed event real-time.
← Kembali ke Events
Panduan operator: kategori, filter, panel detail, ekspor, Smart Search, dan protokol WebSocket.
Otentikasi
API key untuk integrasi, Bearer token untuk sesi pengguna, dan otentikasi WebSocket.
Semua endpoint memerlukan otentikasi. Untuk integrasi, kirim header X-Api-Key: <key> di setiap request tanpa header Authorization. Bearer token (Authorization: Bearer <access_token>, berlaku 30 menit) hanya untuk aplikasi yang menampilkan login Lenz ke penggunanya sendiri dan wajib menyertakan X-Integration-Signature. Basis URL mengikuti variabel lingkungan VITE_API_URL yang dikonfigurasi pada instalasi Lenz. Lihat Otentikasi untuk memilih jalur yang tepat.
Arsip Event
Endpoint yang dipakai halaman Event History untuk membaca event per kategori (fra, mpaa, mvaa, ce, lpr, ppe, general). Pagination berbasis cursor: kirim cursor=<data.pagination.next_cursor> dari respons sebelumnya untuk halaman berikutnya, dan include_total=true bila Anda perlu jumlah total. Filter dikirim sebagai filter[<nama>] (pencocokan persis, beberapa nilai dipisah koma) dan pencarian sebagai search[<nama>] (pencocokan sebagian). Hasil selalu dibatasi ke stream yang boleh diakses oleh pengguna atau API key yang dipakai.
Daftar Event
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik: fra, mpaa, mvaa, ce, lpr, ppe, atau general.
"fra" | "mpaa" | "mvaa" | "ce" | "lpr" | "ppe" | "general"Query Parameters
Jumlah event per halaman. Default 20, maksimum 100 (nilai lebih besar dipotong ke 100).
20value <= 100Cursor halaman berikutnya, diperoleh dari data.pagination.next_cursor pada respons sebelumnya. Cursor tidak valid menghasilkan 400.
true untuk menyertakan data.pagination.total. Berguna untuk menampilkan jumlah total, tetapi memperlambat query pada dataset besar.
falseFormat field:direction. Field yang diizinkan bergantung kategori: FRA event_time|keyword|status|created_at; MPAA/PPE event_time|area|direction|dwelling_duration|created_at; MVAA event_time|area|direction|dwelling_duration|vehicle_type|created_at; CE event_time|estimation|area|created_at; LPR event_time|plate_number|vehicle_type|created_at. Field lain dikembalikan ke default event_time:desc.
Zona waktu IANA untuk mem-parsing filter[timestamp_*] berformat tanggal saja dan untuk memformat event_time pada respons. Default UTC.
Mode Federation: ID instance target. Beberapa instance dipisah koma (instance=a,b) dan otomatis diperlakukan sebagai agregasi.
Mode Federation: true tanpa instance untuk fan-out ke semua instance. Federation Module menggabungkan hasil, mengurutkan ulang berdasarkan (event_time, event_id), dan membangun ulang next_cursor.
Batas awal waktu event. RFC 3339, atau YYYY-MM-DD (diselaraskan ke awal hari pada timezone).
Batas akhir waktu event. RFC 3339, atau YYYY-MM-DD (diselaraskan ke akhir hari pada timezone).
ID stream, pisahkan koma untuk beberapa stream. Selalu diiris dengan stream yang boleh diakses pengguna/API key.
ID analitik engine, pisahkan koma.
Daftar Event ID persis, pisahkan koma. Dipakai ekspor Halaman Saat Ini.
Status deteksi. FRA: KNOWN,UNKNOWN; LPR: status pendaftaran plat. Pisahkan koma untuk beberapa nilai.
Jenis kelamin (FRA/MPAA). Nilai mengikuti opsi /filters, mis. Male,Female.
Kelompok usia (FRA/MPAA), mis. Adult,Child,Elderly.
Masker (FRA/MPAA). Nilai mengikuti opsi /filters.
Kacamata (FRA/MPAA).
Penutup kepala (FRA/MPAA).
Ekspresi wajah (FRA/MPAA).
Warna pakaian atas (FRA/MPAA).
Warna pakaian bawah (FRA/MPAA).
Tipe tubuh (MPAA, pipeline MPA2).
Sarung tangan (MPAA, PPE).
Jenis pakaian atas (MPAA).
Jenis pakaian bawah (MPAA).
Warna alas kaki (MPAA).
Nama area/garis (MPAA/MVAA/CE/PPE). Pisahkan koma untuk beberapa area.
Arah pergerakan in atau out (MPAA/MVAA/LPR/PPE).
Logic type (MPAA/MVAA/PPE): counting, dwelling, density, dan speed (khusus MVAA).
Garis asal pada logic line-crossing (MPAA/PPE).
Garis tujuan pada logic line-crossing (MPAA/PPE).
Tipe kendaraan (MVAA/LPR), mis. car,motorcycle,bus,truck.
Merek kendaraan (MVAA), pencocokan persis. Untuk pencocokan sebagian gunakan search[brand].
Warna kendaraan (MVAA).
Atribut Vehicle Advance (MVAA).
Tipe plat (LPR).
Kacamata pengaman (PPE).
Pelindung wajah (PPE).
Tali pengaman (PPE).
Pelindung kepala (PPE).
Warna helm (PPE).
Masker wajah (PPE).
Pakaian pelindung (PPE).
Warna pakaian pelindung (PPE).
Jenis alas kaki (PPE).
Konteks kerja (PPE).
Label deteksi (General), pisahkan koma.
Pencocokan sebagian (case-insensitive) pada Event ID; berlaku untuk semua kategori kecuali general.
Pencocokan sebagian pada keyword/label hasil pengenalan (FRA).
Pencocokan sebagian pada face_id (FRA).
Pencocokan sebagian pada merek kendaraan (MVAA).
Pencocokan sebagian pada nomor plat (LPR).
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://lenz.example.com/api/event-history/fra?limit=20&sort=event_time%3Adesc&timezone=Asia%2FJakarta&instance=remote-jakarta&filter%5Btimestamp_from%5D=2026-04-30T00%3A00%3A00%2B07%3A00&filter%5Btimestamp_to%5D=2026-04-30T23%3A59%3A59%2B07%3A00&filter%5Bstream_ids%5D=eb7022a64d9173a6%2Cc1105b1c6e6b4f3a&filter%5Banalytic_ids%5D=NFV4-FR%2CNFV4-FRA&filter%5Bstatus%5D=KNOWN&filter%5Blogic_type%5D=counting%2Cdwelling&search%5Bevent_id%5D=a6d87102&search%5Bplate_number%5D=B+1234"{ "ok": true, "data": { "analytics_type": "fra", "events": [ { "id": "01HXYZ1234567890ABCDEF", "event_id": "1780473522-a6d87102", "analytic_id": "NFV4-FR", "stream_id": "eb7022a64d9173a6", "stream_name": "Kamera Lobby Utama", "primary_image_url": "/api/attachments?owner_type=primary&owner_id=1780473522-a6d87102", "secondary_image_url": "/api/attachments?owner_type=secondary&owner_id=1780473522-a6d87102", "label": "UNKNOWN", "location": "Lobby Utama", "event_time": "2026-04-30T08:23:45+07:00", "created_at": "2026-04-30T08:23:46+07:00", "status": "UNKNOWN", "face_id": "118747588341006337", "similarity": 0.4894, "gender": "Male", "age": "Adult", "mask": "No Mask", "glasses": "No Glasses", "head_covering": "None", "upper_color": "Black", "face_expression": "neutral", "stream_latitude": -6.2088, "stream_longitude": 106.8456, "metadata": { "enrolled_face_metadata": null } } ], "pagination": { "limit": 20, "has_next": true, "has_prev": false, "next_cursor": "eyJpZCI6IjE2MzQ1NiJ9", "prev_cursor": null, "total": 1240 } }}{ "ok": false, "code": "bad-request", "errors": [], "message": "unsupported category: xyz"}{ "ok": false, "message": "unauthorized"}{ "ok": false, "code": "forbidden", "message": "forbidden"}Detail Event
Respons daftar sudah berisi seluruh atribut yang ditampilkan tabel. Untuk data lengkap satu event (gambar base64, pipeline_data mentah, koordinat stream), panel detail memanggil endpoint di bawah dengan event_id dari respons daftar. Tidak ada endpoint detail per kategori di bawah /api/event-history.
Authorization
bearerAuth In: header
Path Parameters
Pipeline event ID yang ada di dalam pipeline_data.event_id
Query Parameters
ID instance sumber pada mode Federation (opsional)
Response Body
application/json
curl -X GET "https://lenz.example.com/api/events/pipeline/evt-uuid-001"{ "ok": true, "message": "successfully fetch event data", "data": { "id": 4821, "analytic_id": "NFV4-FR", "stream_id": "stream-abc123", "pipeline_data": { "event_id": "evt-uuid-001" } }}Opsi Filter
Nilai yang tersedia untuk setiap dimensi filter pada satu kategori, misalnya daftar status, warna, area, atau label yang sudah pernah terdeteksi, digabung dengan pool nilai yang dideklarasikan konfigurasi rules pipeline. UI memakainya untuk mengisi checkbox dan chip warna di panel Filter; integrasi dapat memakainya untuk memvalidasi nilai filter[...] sebelum mengirim query.
Opsi Filter Event
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik: fra, mpaa, mvaa, ce, lpr, ppe, atau general.
"fra" | "mpaa" | "mvaa" | "ce" | "lpr" | "ppe" | "general"Query Parameters
Batasi opsi ke satu logic type: counting, dwelling, atau density. Nilai lain menghasilkan 400.
"counting" | "dwelling" | "density"Awal rentang yang sedang dilihat (RFC 3339 atau YYYY-MM-DD). Opsi area milik stream yang dihapus sebelum waktu ini disembunyikan.
Zona waktu untuk mem-parsing timestamp_from berformat tanggal saja. Default UTC.
Mode Federation: ID instance target.
Mode Federation: true untuk menggabungkan opsi dari semua instance (federer melakukan union pada data.filters dan data.filter_contexts).
Response Body
application/json
application/json
curl -X GET "https://lenz.example.com/api/event-history/fra/filters?timestamp_from=2026-04-30T00%3A00%3A00%2B07%3A00&timezone=Asia%2FJakarta&instance=remote-jakarta"{ "ok": true, "data": { "category": "fra", "logic_type": null, "filters": { "status": [ "KNOWN", "UNKNOWN" ], "gender": [ "Male", "Female" ], "age": [ "Adult", "Child", "Elderly", "Unknown" ], "mask": [ "Mask", "No Mask" ], "glasses": [ "Glasses", "No Glasses" ], "head_covering": [ "None", "Hat", "Hijab" ], "face_expression": [ "neutral", "happy" ], "upper_color": [ "Black", "Blue", "White" ], "lower_color": [ "Black", "Blue" ] }, "last_updated": "2026-04-30T08:00:00Z", "filter_contexts": null }}{ "ok": false, "code": "bad-request", "message": "invalid category: must be fra, mpaa, mvaa, ce, lpr, ppe, or general"}Ekspor
Ekspor berjalan sebagai job asinkron di server. Alurnya: buat job dengan POST .../export (lingkup current_page dengan daftar event_ids, atau all dengan objek filters yang sama dengan query daftar), poll statusnya, lalu unduh file PDF, XLSX, atau ZIP ketika status completed. File yang sudah diunduh tidak dapat diunduh ulang. Di mode Federation, kirim instance=<id> pada keempat request agar job dijalankan pada instance pemilik data; UI membuat satu job per instance.
Mulai Job Ekspor
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik yang diekspor. Nilai yang valid: FRA (Face Recognition Attributes), MPAA (Multi People Attribute Analytics), MVAA (Multi Vehicle Attribute Analytics), CE (Crowd Estimation), LPR (License Plate Recognition).
"FRA" | "MPAA" | "MVAA" | "CE" | "LPR"Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://lenz.example.com/api/event-history/FRA/export" \ -H "Content-Type: application/json" \ -d '{ "format": "pdf", "scope": "all", "timezone": "Asia/Jakarta", "include_images": true, "filters": { "timestamp_from": "2024-01-15T00:00:00+07:00", "timestamp_to": "2024-01-15T23:59:59+07:00", "stream_ids": [ "stream-abc123" ], "analytic_ids": [ "NFV4-FRA" ] } }'{ "ok": true, "message": "Export job initiated", "data": { "job_id": "export-job-uuid-001", "status": "pending", "estimated_records": 1420, "message": "Export job queued successfully" }}Status Job Ekspor
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik (sama dengan yang digunakan saat inisiasi job)
"FRA" | "MPAA" | "MVAA" | "CE" | "LPR"ID job export yang diperoleh dari respons inisiasi
Response Body
application/json
curl -X GET "https://lenz.example.com/api/event-history/FRA/export/status/export-job-uuid-001"{ "ok": true, "data": { "job_id": "export-job-uuid-001", "status": "running", "progress": { "processed": 712, "total": 1420, "percent": 50 }, "files_ready": 0, "total_files": 1, "error_message": null, "created_at": "2024-01-15T10:00:00Z", "updated_at": "2024-01-15T10:00:30Z" }}Unduh Hasil Ekspor
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik (sama dengan yang digunakan saat inisiasi job)
"FRA" | "MPAA" | "MVAA" | "CE" | "LPR"ID job export yang sudah berstatus completed
Response Body
curl -X GET "https://lenz.example.com/api/event-history/FRA/export/download/export-job-uuid-001""string"Batalkan Job Ekspor
Authorization
bearerAuth In: header
Path Parameters
Kategori analitik (sama dengan yang digunakan saat inisiasi job)
"FRA" | "MPAA" | "MVAA" | "CE" | "LPR"ID job export yang akan dibatalkan
Response Body
application/json
curl -X DELETE "https://lenz.example.com/api/event-history/FRA/export/export-job-uuid-001"{ "ok": true, "message": "Export job cancelled"}Pencarian
Mode Smart Search pada halaman Event History memanggil GET /api/smart-search dengan parameter search, limit, timezone, last_score (cursor berbasis skor), serta filter[timestamp_from] dan filter[timestamp_to]. Endpoint ini dan endpoint gambar pendampingnya didokumentasikan di API Reference: Search.
Webhook & Streaming
Dua WebSocket channel tersedia untuk menerima event secara real-time tanpa polling. /api/event_channel mengirim setiap deteksi yang lewat pipeline dan bersifat publik; /api/alert_channel hanya mengirim event yang lolos Alert Rule aktif, memerlukan authorization=<access_token> atau x-api-key=<key> sebagai query parameter, dan dibatasi ke stream yang boleh diakses.
Kedua endpoint menggunakan protokol WebSocket, bukan HTTP biasa. Gunakan ws:// atau wss:// sebagai skema URL dan kirim kredensial sebagai query parameter karena browser tidak dapat mengatur header saat handshake. Lihat Otentikasi: WebSocket untuk detail masa berlaku token, dan bagian WebSocket Protocol untuk Integrator untuk struktur payload dan pola reconnect.
WebSocket Event Channel
Authorization
bearerAuth In: header
Query Parameters
ID stream yang ingin dimonitor, pisahkan koma. Kosong berarti semua stream.
Bentuk tunggal dari stream_ids; dipertahankan untuk kompatibilitas.
ID analitik yang ingin diterima, pisahkan koma.
Nomor node Visionaire (default 0).
0Hanya event dengan logic type tertentu.
true untuk tidak menyertakan gambar base64. primary_image_url/secondary_image_url tetap dikirim. Sangat disarankan pada volume tinggi.
falseMode Federation: ID instance sumber (ditangani federer).
Mode Federation: true untuk menerima event dari semua instance (ditangani federer).
Response Body
curl -X GET "https://lenz.example.com/api/event_channel?stream_ids=eb7022a64d9173a6%2Cc1105b1c6e6b4f3a&analytic_id=NFV4-FR%2CNFV4-LPR&logic=counting&instance=remote-jakarta"WebSocket Alert Channel
Query Parameters
API key untuk integrasi. Wajib salah satu dari x-api-key atau authorization.
Access token sesi pengguna (berlaku 30 menit), dengan atau tanpa awalan Bearer . Alternatif dari x-api-key.
Set true agar primary_image/secondary_image tidak disertakan; ambil gambar lewat primary_image_url saat dibutuhkan. Sangat disarankan pada volume tinggi.
falseMode Federation: set true untuk menerima alert dari instance lokal dan semua remote instance. Lenz mengaktifkan ini otomatis saat berjalan dalam mode Federation.
falseMode Federation: berlangganan hanya ke satu remote instance tertentu. Kosongkan atau isi core untuk instance lokal.
Response Body
application/json
application/json
curl -X GET "https://lenz.example.com/api/alert_channel?x-api-key=%3Ckey%3E&authorization=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."{ "event_id": "3f1a9c2e-7b4d-4e0a-9c1b-2d5f6a7b8c9d", "alert_type_id": 2, "analytic_id": "NFV4-FR", "stream_id": "eb7022a64d9173a6", "node_num": 0, "label": "UNKNOWN", "location": "Lobby Utama", "result": "UNKNOWN", "status": "UNKNOWN", "logic": "face_recognition", "timestamp": "2026-04-30T08:23:45+07:00", "instance": "cabang-bandung", "primary_image": "string", "secondary_image": "string", "primary_image_url": "event_id=3f1a9c2e-7b4d-4e0a-9c1b-2d5f6a7b8c9d&type=primary", "secondary_image_url": "event_id=3f1a9c2e-7b4d-4e0a-9c1b-2d5f6a7b8c9d&type=secondary", "pipeline_data": { "face_id": "118747588341006337", "similarity": 0.4894, "status": "UNKNOWN", "confidence_detection": 0.9988 }}{ "ok": false, "code": "forbidden", "message": "you don't have access to any streams"}Events
Telusuri arsip event hasil deteksi AI per kategori analitik (FRA, MPAA, MVAA, CE, LPR, PPE, General) dengan filter atribut, infinite scroll, panel detail, ekspor asinkron, Smart Search, dan feed WebSocket untuk integrator.
Alert Rules
Konfigurasi aturan alert untuk memicu notifikasi secara otomatis berdasarkan event AI Visionaire — tentukan kondisi, stream target, dan channel pengiriman dalam satu rule.