---
title: "List firearm alert events"
method: GET
path: "/v1/alerts/firearm/events"
tags: ["alerts"]
---

# List firearm alert events

`GET /v1/alerts/firearm/events`

## Request

- Base URL: `https://developer.coram.ai`
- URL: `https://developer.coram.ai/v1/alerts/firearm/events`
- Auth: API key in header `X-Auth-Token`

Returns the organization's firearm alert events raised in a time window,
newest first. Both `start_time` and `end_time` are required and the
window may span at most 7 days. Pagination uses the same `page` +
`limit` + `has_more` shape as every other developer-API list endpoint.

Each result has the shape `/alerts/{alert_event_id}/details` returns,
with the AI description and the clip. This list never starts a clip
download. Where `/details` would request one, the `clip` here reads
`pending` for 5 minutes after the alert and `failed` after that. The
list leaves out alert events waiting for or failing AI verification.

## Query parameters

- `start_time` string, date-time, required
- `end_time` string, date-time, required
- `page` integer
- `limit` integer

## Response `200`

Successful Response

- FirearmAlertEventList
  - `results` AlertDetailsResponse[], required
    - `alert_event_id` integer, required: ID of the alert event
    - `alert_time` string, date-time, required: When the alert was triggered (UTC)
    - `camera_mac_address` string, required: MAC address of the camera that captured the alert
    - `ai` AlertAIDescriptionInfo, required: AI-generated description of an alert, grouped the way `clip` is. Shared by the alert details endpoint and the `camera_alert_details` webhook so both carry the identical payload shape.
      - `status` 'ready' | 'pending' | 'failed', required: Status of the AI-generated alert description. The description is produced asynchronously by a vision language model after the alert is emitted, so consumers polling this endpoint right after a webhook may see `pending` for a few seconds before it transitions to `ready` or `failed`.
      - `short_description` string: Short AI-generated summary of what the camera observed. Omitted when `status` is `pending` or `failed`. May also be omitted when `status` is `ready` if only the long description was generated — consumers should treat the field's absence as equivalent to null and check both descriptions before using either.
      - `long_description` string: Long-form AI-generated description of what the camera observed. Omitted when `status` is `pending` or `failed`. May also be omitted when `status` is `ready` if only the short description was generated — consumers should treat the field's absence as equivalent to null and check both descriptions before using either.
    - `clip` AlertClipInfo: Video clip associated with an alert. Present only when a clip exists for the alert (today: firearm alerts with auto clip download enabled). The `mp4_url`/`expires_at` fields are populated only once `status` is `ready`.
      - `status` 'ready' | 'pending' | 'failed', required: Status of the video clip associated with an alert. Mirrors `AIDescriptionStatus`: the clip is produced asynchronously (the edge device uploads it after the alert fires), so consumers polling this endpoint right after a webhook may see `pending` before it becomes `ready`.
      - `mp4_url` string: Direct download URL for the MP4 video clip. No authentication required. Present only when `status` is `ready`; valid until `expires_at`.
      - `expires_at` string, date-time, nullable: When the `mp4_url` expires (UTC). Present only when `status` is `ready`.
  - `has_more` boolean, required: True if a further page beyond `page` exists.

## Other responses

- `400`: A time bound is missing or not RFC3339, the window is longer than 7 days, or a pagination value is invalid
- `401`: Missing or invalid API key
- `403`: API key lacks the required scope or role

## Changes

- **2026-10-19** `39dc74a9396b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coram/apis/coram-api/changes/v1/alerts/firearm/events/get.md)

---

[API](https://skmtc.dev/coram/apis/coram-api.md) - [All operations](https://skmtc.dev/coram/apis/coram-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coram/apis/coram-api/revisions/00df3cfc762f?raw)