Alerts Report

Generated alerts with event details, location, and notification channel.

GET/apidev/v1/reports/gt/alerts

PermissionAPICLI_RPTGT_ALERTAS

Rate Limit10 req/min

Cache300s

Max Range31 days

---

Overview

Returns alerts generated over a date range, each with its event details (group and code), the moment it was generated and notified, the device and driver involved, the location (address plus coordinates), and the speed and temperature at the time. Filter by devices, event codes, or specific alert IDs.

---

Request

Request Headers

Every request to a protected endpoint requires these headers:

Header	Required	Description
Authorization	Yes	Bearer token obtained from the Login endpoint. Format: Bearer <token>
X-API-Key	Yes	Company integration key provided during onboarding. Format: gtk_xxx...
tenant	Yes	Your assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string	Yes	—	ISO 8601 start date-time (e.g. 2026-03-01T00:00:00).
enddate	string	Yes	—	ISO 8601 end date-time. Max range 31 days from startdate.
devices	string	No	—	Comma-separated device IDs. Max 500.
events	string	No	—	Event codes filter. Max 200 chars.
alert_ids	string	No	—	Alert IDs filter. Max 200 chars.
limit	integer	No	25	Number of records per page (1–100).
offset	integer	No	0	Number of records to skip for pagination.

---

Code Examples

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/reports/gt/alerts?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=25"

JavaScript

const res = await fetch(
  `https://${TENANT}/apidev/v1/reports/gt/alerts?startdate=2026-03-01T00:00:00&enddate=2026-03-15T23:59:59&limit=25`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);
const data = await res.json();

Python

import requests

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/gt/alerts",
    headers={"Authorization": f"Bearer {TOKEN}", "X-API-Key": APIKEY, "tenant": TENANT},
    params={"startdate": "2026-03-01T00:00:00", "enddate": "2026-03-15T23:59:59", "limit": 25},
)
data = response.json()

---

Response

Response Fields

Field	Type	Description
alert_name	string	Alert configuration name.
event_group	string	Event group/category.
event_code	string	Event code.
generated_at	string | null	Timestamp when alert was generated.
sent_at	string | null	Timestamp when notification was sent.
device_name	string	Vehicle name.
driver_name	string	Driver name.
address	string	Location address.
latitude	number | null	Latitude.
longitude	number | null	Longitude.
speed	number	Speed at event time (km/h).
temperature	number	Temperature at event time.
elapsed_time	string	Time spent inside the geofence that triggered the alert, already human-readable (e.g. 1h 05m). Empty when the event is not geofence-based.
geofences	string	Geofences involved in the event, comma-separated.
pois	string	Points of interest involved in the event, comma-separated.
sensor1_label	string	Sensor 1 reading label. Empty when the company does not use sensor 1.
sensor2_label	string	Sensor 2 reading label. Empty when the company does not use sensor 2.
channel	string	Notification channel (email, sms, etc.).

Example Response

{
  "success": true,
  "data": [
    {
      "alert_name": "Speed Limit",
      "event_group": "Velocity",
      "event_code": "117",
      "generated_at": "2026-03-05T14:22:15",
      "sent_at": "2026-03-05T14:22:18",
      "device_name": "Truck A-101",
      "driver_name": "Carlos Martinez",
      "address": "Ruta 1 km 45, San Jose",
      "latitude": -34.3426,
      "longitude": -56.7135,
      "speed": 118,
      "temperature": 22.5,
      "elapsed_time": "1h 05m",
      "geofences": "Deposito Central",
      "pois": "Estacion de servicio Ruta 1",
      "sensor1_label": "Puerta abierta",
      "sensor2_label": "",
      "channel": "email"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Invalid params: missing dates, range > 31 days, invalid enum values.
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks required permission.
RATE_LIMITED	429	Exceeded 10 req/min.
INTERNAL_ERROR	500	Unexpected server error.

---

Related

• Tasks General Report
• Pagination