Skip to main content

Run and schedule a report

Scopes: reports:read, reports:run, reports:write.

1. See what can be run​

curl -s "https://api.zaitrack.app/v1/reports/catalog" -H "Authorization: Bearer $KEY" | jq '.items'

The catalogue gives each report kind with the parameters it takes. Formats are pdf, csv and xlsx.

2. Run one​

A run is asynchronous: the request is accepted (202) and the report is built in the background.

RUN_ID=$(curl -s -X POST "https://api.zaitrack.app/v1/reports/runs" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind": "trips", "format": "xlsx", "from": "2026-10-01T00:00:00Z", "to": "2026-11-01T00:00:00Z",
       "timezone": "Asia/Riyadh"}' | jq -r '.id')

Leave vehicleIds out for the whole fleet, or list up to 500. A location-stays report also needs point (lat, lon) and radiusKm.

3. Wait and download​

while :; do
  STATUS=$(curl -s "https://api.zaitrack.app/v1/reports/runs/$RUN_ID" -H "Authorization: Bearer $KEY" | jq -r '.status')
  case "$STATUS" in completed|failed) break;; esac
  sleep 5
done
curl -s -OJ "https://api.zaitrack.app/v1/reports/runs/$RUN_ID/file" -H "Authorization: Bearer $KEY"

A run is queued, running, completed or failed (with its error). The file is there only once it is completed; before that the download is refused with 409. Runs are in the report rate class: 1,000 a day.

4. Schedule it​

curl -s -X POST "https://api.zaitrack.app/v1/reports/schedules" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Monthly trips", "kind": "trips", "format": "xlsx", "cron": "0 6 1 * *",
       "timezone": "Asia/Riyadh", "window": "previous-month", "recipients": ["[email protected]"]}' | jq '{id, nextRunAt}'

window is previous-day, previous-week or previous-month. Each run is e-mailed to recipients and listed under GET /v1/reports/runs?scheduleId=…. POST /v1/reports/schedules/{id}/run runs a schedule now.