Skip to main content

Events and clips

Argus stores two types of event:

  • detection: one per detection published by an edge node.
  • Rule events: one each time a workflow matches. Alerts, clips and captions belong to these events. Their type is the key of the event type set on the camera's detection profile, rule_trigger by default.

Every endpoint on this page works for operators and admins.

List events​

GET/events

Lists events, newest first. All filters are optional.

Query parameters​

camera_namestringoptional
Only events from this camera.
class_namestringoptional
Only events for this object class, for example person or car. vehicle matches car, truck, bus and motorcycle; bag matches backpack, handbag and suitcase; people and pedestrian match person.
event_typestringoptional
detection, or an event type key such as rule_trigger.
limitintegeroptional
The most events to return. Defaults to 50.

Response fields​

An array of events:

idintegeroptional
The event ID.
camera_namestringoptional
The camera.
typestringoptional
detection, or the event type key of a rule event.
tsstringoptional
When it happened.
metadataobjectoptional
Details. For a detection: class, confidence, bbox ([x1, y1, x2, y2] in pixels) and frame_idx. For a rule event: workflow, class, bbox, severity, trigger_type and the detection profile's profile_id, profile_key and profile_name. A Tag Event step adds tags.
captionstring or nulloptional
The clip caption, for rule events that have one.
clip_uristring or nulloptional
Where the clip is stored.
clip_urlstringoptional
The API path to play the clip. Only present when there is a clip.

Responses​

200
The events.
401
You are not signed in.

Get a clip​

GET/clips/{event_id}

Returns the event's clip as an H.264 MP4 video (video/mp4). The clip is streamed through the site node over the same HTTPS address as the dashboard, with your session, so the client never needs to reach the site's object storage.

Clips are about 10 seconds long: 5 seconds before to 5 seconds after the rule matched.

If your administrator has set a separate public HTTPS address for clip storage, the endpoint instead redirects to a signed link there, valid for 10 minutes. Follow redirects in your client to handle both cases.

Path parameters​

event_idintegerrequired
The rule event. Get it from an alert's event_id.

Responses​

200
The clip, as video/mp4. If there is no clip for the event, or the event doesn't exist, the body is JSON instead: {"error": "no clip for this event"}.
307
A redirect to the clip, only when a public clip address is set.
401
You are not signed in.
500
The clip couldn't be read from storage.
Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Argus for your site? We can help.Book a site assessment →