Reports

11 operations at https://api.zaitrack.app. Request and response bodies are JSON with camelCase keys; ids are UUIDs; times are RFC 3339 in UTC.

Every operation needs an API key, a personal access token or an OAuth access token unless it says otherwise. An Idempotency-Key is replayed for 24 hours; see Idempotency. Errors are application/problem+json; see Errors.

Report kinds and their parameters

GET /v1/reports/catalog

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Query parameter	Type	Notes
`all`	boolean

Request

No body.

Response

200: fields the handler writes, taken from its source.

Keys: items. Their types are not described.

Example

curl "https://api.zaitrack.app/v1/reports/catalog" \
  -H "Authorization: Bearer zk_test_…"

Run a report (asynchronous)

POST /v1/reports/runs

Runs are asynchronous: poll GET /v1/reports/runs/{id} until the run completes, then download GET /v1/reports/runs/{id}/file.

Scope: reports:run or reports:*
Rate class: report (1,000 per day)
Idempotency-Key: optional
Audited: medium risk
Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`kind`	string: `trips`, `vehicle-utilization`, `alerts`, `geofence-visits`, `fuel-purchases`, `driver-performance`, `violation-summary`, `event-history`, `location-stays`, `secure-trips`, `vehicle-mode`, `seal-batteries`
`format`	string: `pdf`, `csv`, `xlsx`
`from`	string (date-time)
`to`	string (date-time)
`timezone`	string	optional
`vehicleIds`	array of string (UUID)	optional
`geofenceId`	string (UUID)	optional
`minSeverity`	string	optional
`point`	object	optional
`point.lat`	number
`point.lon`	number
`radiusKm`	number	optional
`groupBy`	Literal['vehicle', 'driver']	optional

Response

202: fields the handler writes, taken from its source.

Keys: id, kind, format, status, params, requestedBy, requestedAt, scheduleId, attempts, error, rowCount, sizeBytes, startedAt, completedAt, fileName, fileUrl, delivery. Their types are not described.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/reports/runs" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind": "trips", "format": "pdf", "from": "2026-10-28T06:00:00Z", "to": "2026-10-28T06:00:00Z", "timezone": "…", "vehicleIds": [], "geofenceId": "00000000-0000-0000-0000-000000000000", "minSeverity": "…", "point": {"lat": 0, "lon": 0}, "radiusKm": 0, "groupBy": null}'

List report runs

GET /v1/reports/runs

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Query parameter	Type	Notes
`status`	string: `queued`, `running`, `completed`, `failed` or null
`kind`	string: `trips`, `vehicle-utilization`, `alerts`, `geofence-visits`, `fuel-purchases`, `driver-performance`, `violation-summary`, `event-history`, `location-stays`, `secure-trips`, `vehicle-mode`, `seal-batteries` or null
`scheduleId`	string (uuid) or null
`pageSize`	integer
`cursor`	string

Request

No body.

Response

200: fields the handler writes, taken from its source.

Keys: items, nextCursor. Their types are not described.

Example

curl "https://api.zaitrack.app/v1/reports/runs" \
  -H "Authorization: Bearer zk_test_…"

A run's status

GET /v1/reports/runs/{id}

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Run a report (asynchronous).

Example

curl "https://api.zaitrack.app/v1/reports/runs/$ID" \
  -H "Authorization: Bearer zk_test_…"

Download a completed run

GET /v1/reports/runs/{id}/file

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: the file itself, with its content type and a Content-Disposition file name.

Example

curl "https://api.zaitrack.app/v1/reports/runs/$ID/file" \
  -H "Authorization: Bearer zk_test_…"

List report schedules

GET /v1/reports/schedules

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Request

No body.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Report kinds and their parameters.

Example

curl "https://api.zaitrack.app/v1/reports/schedules" \
  -H "Authorization: Bearer zk_test_…"

Schedule a report

POST /v1/reports/schedules

Scope: reports:write or reports:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: optional
Audited: low risk
Step-up MFA: no

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`name`	string
`kind`	string: `trips`, `vehicle-utilization`, `alerts`, `geofence-visits`, `fuel-purchases`, `driver-performance`, `violation-summary`, `event-history`, `location-stays`, `secure-trips`, `vehicle-mode`, `seal-batteries`
`format`	string: `pdf`, `csv`, `xlsx`
`cron`	string
`timezone`	string	optional
`window`	string: `previous-day`, `previous-week`, `previous-month`
`recipients`	array of string
`vehicleIds`	array of string (UUID)	optional
`geofenceId`	string (UUID)	optional
`minSeverity`	string	optional
`enabled`	boolean	optional
`language`	string	optional

Response

201: fields the handler writes, taken from its source.

Keys: id, name, kind, format, cron, timezone, window, recipients, vehicleIds, geofenceId, minSeverity, enabled, language, nextRunAt, createdBy, createdAt, updatedAt, version. Their types are not described.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X POST "https://api.zaitrack.app/v1/reports/schedules" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "kind": "trips", "format": "pdf", "cron": "…", "timezone": "…", "window": "previous-day", "recipients": [], "vehicleIds": [], "geofenceId": "00000000-0000-0000-0000-000000000000", "minSeverity": "…", "enabled": false, "language": "…"}'

Get a schedule

GET /v1/reports/schedules/{id}

Scope: reports:read or reports:*
Rate class: read (100 per second and 360,000 per hour)
Idempotency-Key: not used
Audited: no
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Schedule a report.

Example

curl "https://api.zaitrack.app/v1/reports/schedules/$ID" \
  -H "Authorization: Bearer zk_test_…"

Update a schedule

PATCH /v1/reports/schedules/{id}

Scope: reports:write or reports:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: not used
Audited: low risk
Step-up MFA: no
If-Match: the version you read; a stale one is refused (412 or 409)

Path parameters: id.

Request

Fields the handler reads, taken from its source.

Field	Type	Notes
`name`	string	optional
`format`	string: `pdf`, `csv`, `xlsx`	optional
`cron`	string	optional
`timezone`	string	optional
`window`	string: `previous-day`, `previous-week`, `previous-month`	optional
`recipients`	array of string	optional
`vehicleIds`	array of string (UUID)	optional
`geofenceId`	string (UUID)	optional
`minSeverity`	string	optional
`enabled`	boolean	optional
`language`	string	optional

Response

200: fields the handler writes, taken from its source.

The same fields as the response of Schedule a report.

Example

Every field is sent with a placeholder value: replace them with yours.

curl -X PATCH "https://api.zaitrack.app/v1/reports/schedules/$ID" \
  -H "Authorization: Bearer zk_test_…" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{"name": "…", "format": "pdf"}'

Delete a schedule

DELETE /v1/reports/schedules/{id}

Scope: reports:write or reports:*
Rate class: write (50 per second and 36,000 per hour)
Idempotency-Key: not used
Audited: low risk
Step-up MFA: no

Path parameters: id.

Request

No body.

Response

204: no body.

Example

curl -X DELETE "https://api.zaitrack.app/v1/reports/schedules/$ID" \
  -H "Authorization: Bearer zk_test_…"

Run a schedule now

POST /v1/reports/schedules/{id}/run

Scope: reports:run or reports:*
Rate class: report (1,000 per day)
Idempotency-Key: optional
Audited: medium risk
Step-up MFA: no

Path parameters: id.

Request

No body: the handler reads none.

Response

202: fields the handler writes, taken from its source.

The same fields as the response of Run a report (asynchronous).

Example

curl -X POST "https://api.zaitrack.app/v1/reports/schedules/$ID/run" \
  -H "Authorization: Bearer zk_test_…" \
  -H "Idempotency-Key: $(uuidgen)"

Report kinds and their parameters​

Request​

Response​

Example​

Run a report (asynchronous)​

Request​

Response​

Example​

List report runs​

Request​

Response​

Example​

A run's status​

Request​

Response​

Example​

Download a completed run​

Request​

Response​

Example​

List report schedules​

Request​

Response​

Example​

Schedule a report​

Request​

Response​

Example​

Get a schedule​

Request​

Response​

Example​

Update a schedule​

Request​

Response​

Example​

Delete a schedule​

Request​

Response​

Example​

Run a schedule now​

Request​

Response​

Example​

Report kinds and their parameters

Request

Response

Example

Run a report (asynchronous)

Request

Response

Example

List report runs

Request

Response

Example

A run's status

Request

Response

Example

Download a completed run

Request

Response

Example

List report schedules

Request

Response

Example

Schedule a report

Request

Response

Example

Get a schedule

Request

Response

Example

Update a schedule

Request

Response

Example

Delete a schedule

Request

Response

Example

Run a schedule now

Request

Response

Example