Events

API in beta

This page describes /api/v3/events, part of the beta v3 API — see Overview. The contract is identical to Events (v2): same code, same filters, same responses. Even though the response still carries the X-API-Status: beta header (that applies to all of v3), “beta” here describes the v3 surface as a whole — mainly areas — not a risk of change for this endpoint: only the base URL differs, /api/v3 instead of /api/v2.

GET /api/v3/events

Fleet events for the key’s owner (entering/leaving an area, ignition, parking, alerts…). Permission: read_events.

Parameter	Default	Notes
type	—	filter by event type — see below for the geofence values
device	—	filter by IMEI
from / to	—	time window, ISO 8601
limit	50	1–200
offset	0

For geofence events, type accepts:

Value	What it filters
geofence	every geofence event (both entries and exits)
geofence_enter / geofence_entry	only entries
geofence_exit	only exits

geofence_enter/geofence_entry/geofence_exit are aliases that filter the same geofence event, distinguishing entry from exit.

cURL

curl -H "X-API-Key: $AITRACK_API_KEY" \
  "https://api.aitrack.it/api/v3/events?type=geofence_enter&limit=50"

Node.js

const url = new URL('https://api.aitrack.it/api/v3/events');
url.searchParams.set('type', 'geofence_enter');
url.searchParams.set('limit', '50');

const res = await fetch(url, { headers: { 'X-API-Key': process.env.AITRACK_API_KEY } });
const { data, meta } = await res.json();

Python

res = requests.get(
    "https://api.aitrack.it/api/v3/events",
    headers={"X-API-Key": api_key},
    params={"type": "geofence_enter", "limit": 50},
    timeout=10,
)
events = res.json()["data"]

{
  "data": [
    {
      "id": 5521,
      "type": "geofence",
      "message": "Van 1 entered Warehouse",
      "device_imei": "352093081452312",
      "data": { "areaId": 12, "event": "entry" },
      "read": false,
      "occurred_at": "2026-07-14T08:59:00.000Z"
    }
  ],
  "meta": { "pagination": { "limit": 50, "offset": 0, "count": 1 } }
}

Note

A geofence event’s type is always "geofence", even when filtering with type=geofence_enter or type=geofence_exit: the filter picks the row (entry or exit), but the returned type stays "geofence"; entry vs. exit is in data.event ("entry" | "exit").

Minimum dwell time on geofences

If the area involved has a minimum dwell time (dwell_seconds) set (via areas or the app’s editor), an entry event doesn’t show up here until the device has stayed inside the area for that long: a vehicle that only passed through generates no event at all, neither entry nor exit.

Prefer push over polling

Polling /events on a schedule works, but adds latency and wasted calls when nothing happened. To receive events in real time, the moment they happen, register a webhook: the same event types, delivered via POST and signed.

See also Errors & limits for the shared envelope and error codes (same as v2), and Areas for entry/exit events filtered to a single area (GET /api/v3/areas/{id}/events).