Events/get_incremental_events

`get_incremental_events`token required

Streaming-style endpoint: returns events with an id strictly greater than `last_event_id`, from a rolling 24-hour window, optionally filtered.

Try in playground

POST/api— body field action.name = "get_incremental_events"

Parameters

Name	Type	Required	Description
`last_event_id`	string	optional	High-water-mark event id — only events with a strictly greater id are returned. Treated as a string to support 64-bit ids. Omitted, empty or '0' means a cold call, which does NOT mean 'from the beginning': it starts from an event id roughly 24 hours back. Poll at least once every 24 hours or the gap between your cursor and the window start is skipped.e.g. `98765432`
`license_number`	string	optional	License plate filter. Alias: `license_nmbr`.e.g. `AB-123-CD`
`severity_level`	number	optional	Exact severity match, not a threshold — `2` returns severity 2 only, not 2 and above. Non-numeric values return action_value '1'.e.g. `2`
`event_category_id`	string	optional	Comma-separated list of positive event category ids. Two legacy ids expand to several categories for legacy parity: `6` matches 3, 10 and 16, and `16` matches 10. Any other id is used as sent. A non-positive id returns action_value '1'.e.g. `1,2,3`

Pagination

This action is paginated. The two parameters below are accepted on every call (both optional); omitting them yields page 1 with 100 rows. The response carries a pagination envelope alongside data; iterate while has_more === true.

page, page_size and has_more are present on every paginated response. total_count and total_pages are returned only by some actions — treat them as optional and drive iteration from has_more rather than from a page count worked out in advance.

Name	Type	Required	Description
`page_number`	number	optional	1-based page index. Defaults to 1 if omitted. Page 1 pins a snapshot for stateful actions (events, telemetry) — subsequent pages reuse that snapshot until the session expires (~30 minutes).e.g. `1`
`page_size`	number	optional	Rows per page. Defaults to 2000, which is also the maximum — larger values are silently capped to 2000, and a response of exactly 2000 rows usually means there are more pages. For stateful actions (events, telemetry) only the value sent with page 1 is honored, because later pages reuse the size pinned by the snapshot; stateless actions read it on every request.e.g. `2000`

Iterate every page

curl

# Iterate every page until pagination.has_more is false.
# page_size "100" is a deliberate small page so the loop is visible — the
# default is 2000, which is also the maximum. Raise it to fetch fewer,
# larger pages; you still stop on has_more either way.
# Requires: jq (https://stedolan.github.io/jq/).
page=1
while :; do
  body=$(curl -s -X POST 'https://private.develop-1.questar.io/v2/private-questar-units/api' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_TOKEN' \
    -d '{"action":{"name":"get_incremental_events","parameters":[{"last_event_id":"98765432","license_number":"AB-123-CD","severity_level":2,"event_category_id":"1,2,3","page_number":"'$page'","page_size":"100"}]}}')
  echo "$body" | jq '.response.properties.data[]'
  has_more=$(echo "$body" | jq -r '.response.properties.pagination.has_more // false')
  [ "$has_more" = "true" ] || break
  page=$((page + 1))
done

Page 1 pins a snapshot for stateful actions (events, telemetry). If the session expires (~30 min) the API returns action_value="3" with description pagination_session_expired — restart from page_number=1.

Notes

Returns events from a rolling 24-hour window — on both cold and cursor calls. Events older than that are never returned, whatever cursor you send. A cold call (`last_event_id` omitted, empty or '0') starts from an event id about 24 hours back, so it is not a full history read. String fields are url-encoded for legacy compatibility: decode `time`, `end_time`, `event_type_description`, `event_category_description` and `driver_name` before use. Timestamps come back as `YYYY-MM-DDTHH:MM:SS.0000000+00:00` (seven fractional digits and an explicit offset), not as a `Z`-suffixed instant. Paging is stateless: `page_size` is read on every request, including page 2 and later, and the response carries `page`, `page_size` and `has_more` but no total row count — iterate until `has_more` is false. A full page is 2000 rows and about 140 KB gzipped; send `Accept-Encoding: gzip` or you will transfer roughly ten times that. `spn`, `fmi`, `fmi_description` and `source` are returned as empty strings on this platform today. Several other fields are empty on many rows — `severity`, `driver_id`, `driver_name`, `driver_code`, `worker_id` and the `end_*` trio — so treat every field except `event_id`, `vehicle_id` and `time` as optional. env_id is taken from the session only — no parameter override. `license_nmbr` accepted as alias for `license_number`. Invalid `severity_level` or any non-positive `event_category_id` returns action_value '1'.

Request

curl

curl -X POST 'https://private.develop-1.questar.io/v2/private-questar-units/api' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data '{"action":{"name":"get_incremental_events","parameters":[{"last_event_id":"98765432","license_number":"AB-123-CD","severity_level":2,"event_category_id":"1,2,3"}]}}'

Body

{
  "action": {
    "name": "get_incremental_events",
    "parameters": [
      {
        "last_event_id": "98765432",
        "license_number": "AB-123-CD",
        "severity_level": 2,
        "event_category_id": "1,2,3"
      }
    ]
  }
}

Response

Successful responses always wrap the action's payload in response.properties. The action_value field reports the handler outcome: "0" for success, "1" for invalid params, "2" for not allowed, "3" for limit-exceeded /pagination-session-expired, "999" for general error.

Authentication is checked before the action runs and fails the same way for every action. A token that is not valid returns HTTP 200 with action_value "2" and description invalid_session; an empty bearer returns "2" with session_token_required. Read the description to tell these apart from an action's own "2". With no Authorization header the gateway answers HTTP 401 {"message":"Unauthorized"}, and with a bearer that is not a token HTTP 403 {"message":"Forbidden"}.

200 OK