Composite Events API Overview

Composite Event in Deeply AI System

Composite Event Object#

The Composite Event object represents an aggregated event record created by applying a composite event rule to multiple base events. It is used when several related detections should be interpreted and returned as a single higher-level result.

How It Works#

A composite event is formed when:

• base events are collected within a rule-defined window
• the rule groups those events using its own grouping strategy
• the API returns the grouped events together with the related microphones and labels

Unlike the public Event Object documented in the Events section, the events field inside a composite event uses a richer event payload. That nested event payload includes threshold values, audio file information, read status, and a full microphone object.

Attributes#

id#

• Type: string
• Description: Unique identifier of the composite event.

---

group_key#

• Type: string
• Description: Grouping key assigned to the composite event according to the rule configuration.

---

rule#

• Type: object
• Description: Rule definition that produced this composite event.

rule.id#

• Type: string
• Description: Unique identifier of the composite event rule.

rule.name#

• Type: string
• Description: Display name of the rule.

rule.description#

• Type: string | null
• Description: Optional description for the rule.

rule.window_seconds#

• Type: number
• Description: Time window used by the rule when grouping base events.

rule.min_events#

• Type: integer
• Description: Minimum number of base events required to form a composite event.

rule.enabled#

• Type: boolean
• Description: Whether the rule is currently enabled.

rule.group_by#

• Type: string
• Description: Grouping strategy used to derive the composite event's group_key.

rule.include_label_ids#

• Type: string[] | null
• Description: Label IDs configured on the rule, when present.

rule.include_mic_ids#

• Type: string[] | null
• Description: Microphone IDs configured on the rule, when present.

---

events#

• Type: array
• Description: Detailed base events that were grouped into this composite event.
• Reference: Related to the Events API Overview, but the nested objects here are more detailed than the simplified OpenAPI event object shown there.

---

mics#

• Type: array
• Description: Microphone devices associated with the grouped events.
• Reference: See the Mic Device API Overview for the related device model.
• Shape: Each item has the same shape as the Get A Mic Device (GET /api/v1/mics/{mic_id}) response.

---

labels#

• Type: array
• Description: Labels associated with the grouped events.

labels[].id#

• Type: string
• Description: Unique identifier of the label.

labels[].name#

• Type: object
• Description: Localized label name.
  • ko (string): Korean label name.
  • en (string): English label name.

labels[].active#

• Type: boolean
• Description: Whether the label is active.

---

started_at#

• Type: string, ISO 8601 format
• Description: Timestamp representing when the grouped composite event window started.
• Note: The value may include fractional seconds (up to 6 digits), e.g. "2026-03-26T09:00:05.123456Z". Parse it with an ISO 8601 parser that accepts both forms.

---

Refer to the List Composite Events API page for paginated retrieval, the Get A Composite Event API page for a single composite event response, and the Listen Live Composite Events page for real-time streaming.