> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ๐งช List Engine Statuses
> Get a paginated list of engine statuses accessible to your organization.
Provisional endpoint
This endpoint is available for early access. The core schema is stable, but minor details โ such as field names or added fields โ may change before it becomes generally available. Backward compatibility is not guaranteed.
See API Stability & Versioning for details on provisional endpoints.
When only\_latest=true, the from\_datetime and to\_datetime query parameters are not applied. Only the most recent status per vehicle is returned regardless of the date range specified.
When only\_latest=false, exactly one vehicle\_ids value or one driver\_ids value must be specified. To retrieve history for multiple vehicles or drivers, make separate requests for each.
## OpenAPI
````yaml https://api.catenatelematics.com/v2/telematics/openapi.json get /v2/telematics/engine-statuses
openapi: 3.1.0
info:
title: Telematics Data Service - REST API
description: Telematics Data Service REST API.
version: 0.1.0
servers:
- url: https://api.catenatelematics.com
description: Catena Telematics API
security: []
tags:
- name: Fleet Operations & Tracking
description: >-
Endpoints for tracking vehicles, trailers, assets, and trip activity โ
including locations, movements, and operational telemetry. Useful for
monitoring utilization and real-time operational status.
- name: Safety & Driver Behavior
description: >-
Endpoints that provide safety-related insights such as harsh braking,
speeding, and other driver behavior events. Supports risk analysis and
safety program automation.
- name: Compliance & Regulation
description: >-
Endpoints covering regulated requirements including DVIR inspections,
Hours of Service (HOS), violations, and IFTA fuel tax reporting. Helps
organizations meet DOT/FMCSA and interstate regulatory obligations.
- name: Maintenance & Vehicle Health
description: >-
Endpoints providing data for vehicle condition monitoring and maintenance
workflows, such as DVIR defects and diagnostic sensor events. Enables
early issue detection and reduced downtime.
- name: Drivers & Users
description: >-
Endpoints related to driver and user identities, assignments, and
operational context. Supports linking operational and safety data to
specific individuals.
- name: Reference Data (Supporting Tables)
description: >-
Lookup tables and enumerations that supply standardized codes, metadata,
and classifications used across the API.
- name: Analytics (deprecated)
description: >-
Endpoints providing analytical insights and aggregated data for vehicles,
fleets, drivers, and trailers.
paths:
/v2/telematics/engine-statuses:
get:
tags:
- Fleet Operations & Tracking
summary: List Engine Statuses
description: Get a paginated list of engine statuses accessible to your organization.
operationId: list_engine_statuses
parameters:
- name: only_latest
in: query
required: false
schema:
type: boolean
description: >-
If true, only the latest known engine status per vehicle is
returned.
default: true
title: Only Latest
description: >-
If true, only the latest known engine status per vehicle is
returned.
- name: fleet_ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
format: uuid
maxItems: 100
- type: 'null'
description: >-
Limit results to specific fleets using Catena's fleet IDs. *For
your own fleet identifiers, use `fleet_refs` instead* To specify
multiple values, repeat the parameter for each value (e.g.,
`?fleet_ids=id1&fleet_ids=id2`).
title: Fleet Ids
description: >-
Limit results to specific fleets using Catena's fleet IDs. *For your
own fleet identifiers, use `fleet_refs` instead* To specify multiple
values, repeat the parameter for each value (e.g.,
`?fleet_ids=id1&fleet_ids=id2`).
- name: fleet_refs
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
maxItems: 100
- type: 'null'
description: >-
Limit results to specific fleets using your organization's fleet
reference identifiers. To specify multiple values, repeat the
parameter for each value (e.g.,
`?fleet_refs=ref1&fleet_refs=ref2`).
title: Fleet Refs
description: >-
Limit results to specific fleets using your organization's fleet
reference identifiers. To specify multiple values, repeat the
parameter for each value (e.g., `?fleet_refs=ref1&fleet_refs=ref2`).
- name: connection_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
description: >-
Limit results to a specific provider connection. This is the UUID
assigned by Catena when your fleet connects to a TSP.
title: Connection Id
description: >-
Limit results to a specific provider connection. This is the UUID
assigned by Catena when your fleet connects to a TSP.
- name: from_datetime
in: query
required: false
schema:
type: string
format: date-time
description: >-
Return only records that occurred on or after this date and time.
**Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at >=
from_datetime` **Default value:** `now() - 1 day` **Restriction:**
`to_datetime - from_datetime` cannot exceed 45 days
examples:
- '2026-06-25T15:05:51.529365Z'
title: From Datetime
description: >-
Return only records that occurred on or after this date and time.
**Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at >=
from_datetime` **Default value:** `now() - 1 day` **Restriction:**
`to_datetime - from_datetime` cannot exceed 45 days
- name: to_datetime
in: query
required: false
schema:
type: string
format: date-time
description: >-
Return only records that occurred before this date and time.
**Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at <
to_datetime` **Default value:** `now()` **Restriction:**
`to_datetime - from_datetime` cannot exceed 45 days
examples:
- '2026-06-26T15:05:51.529502Z'
title: To Datetime
description: >-
Return only records that occurred before this date and time.
**Format:** ISO 8601 (UTC) **Applies filter:** `occurred_at <
to_datetime` **Default value:** `now()` **Restriction:**
`to_datetime - from_datetime` cannot exceed 45 days
- name: driver_ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
format: uuid
maxItems: 100
- type: 'null'
description: >-
Limit results to specific drivers. **Maximum:** 100 IDs To specify
multiple values, repeat the parameter for each value (e.g.,
`?driver_ids=id1&driver_ids=id2`).
title: Driver Ids
description: >-
Limit results to specific drivers. **Maximum:** 100 IDs To specify
multiple values, repeat the parameter for each value (e.g.,
`?driver_ids=id1&driver_ids=id2`).
- name: vehicle_ids
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
format: uuid
maxItems: 100
- type: 'null'
description: >-
Limit results to specific vehicles. **Maximum:** 100 IDs To
specify multiple values, repeat the parameter for each value
(e.g., `?vehicle_ids=id1&vehicle_ids=id2`).
title: Vehicle Ids
description: >-
Limit results to specific vehicles. **Maximum:** 100 IDs To specify
multiple values, repeat the parameter for each value (e.g.,
`?vehicle_ids=id1&vehicle_ids=id2`).
- name: include_source_data
in: query
required: false
schema:
type: boolean
description: >-
Include the raw data from the telematics provider. *Useful for
auditing or accessing fields not normalized by Catena*
default: false
title: Include Source Data
description: >-
Include the raw data from the telematics provider. *Useful for
auditing or accessing fields not normalized by Catena*
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor for the next page
title: Cursor
description: Cursor for the next page
- name: size
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Page size
default: 300
title: Size
description: Page size
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/_CursorPage_EngineStatusRead_'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Unauthorized'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Forbidden'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
description: Not Found
'405':
content:
application/json:
schema:
$ref: '#/components/schemas/MethodNotAllowed'
description: Method Not Allowed
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict'
description: Conflict
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntity'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequests'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: Internal Server Error
'501':
content:
application/json:
schema:
$ref: '#/components/schemas/NotImplementedResponse'
description: Not Implemented
security:
- Bearer:
- telematics:read
components:
schemas:
_CursorPage_EngineStatusRead_:
properties:
items:
items:
$ref: '#/components/schemas/EngineStatusRead'
type: array
title: Items
total:
type: integer
minimum: 0
title: Total
current_page:
anyOf:
- type: string
- type: 'null'
title: Current Page
description: Cursor to refetch the current page
current_page_backwards:
anyOf:
- type: string
- type: 'null'
title: Current Page Backwards
description: Cursor to refetch the current page starting from the last item
previous_page:
anyOf:
- type: string
- type: 'null'
title: Previous Page
description: Cursor for the previous page
next_page:
anyOf:
- type: string
- type: 'null'
title: Next Page
description: Cursor for the next page
type: object
required:
- items
- total
title: _CursorPage[EngineStatusRead]
BadRequest:
properties:
code:
type: integer
title: Code
default: 400
message:
type: string
title: Message
default: Bad Request
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: BadRequest
Unauthorized:
properties:
code:
type: integer
title: Code
default: 401
message:
type: string
title: Message
default: Unauthorized
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: Unauthorized
Forbidden:
properties:
code:
type: integer
title: Code
default: 403
message:
type: string
title: Message
default: Forbidden
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: Forbidden
NotFound:
properties:
code:
type: integer
title: Code
default: 404
message:
type: string
title: Message
default: Not Found
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: NotFound
MethodNotAllowed:
properties:
code:
type: integer
title: Code
default: 405
message:
type: string
title: Message
default: Method Not Allowed
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: MethodNotAllowed
Conflict:
properties:
code:
type: integer
title: Code
default: 409
message:
type: string
title: Message
default: Conflict
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: Conflict
UnprocessableEntity:
properties:
code:
type: integer
title: Code
default: 422
message:
type: string
title: Message
default: Invalid Request Body
detail:
anyOf:
- items:
$ref: '#/components/schemas/ValidationErrorDetail'
type: array
- type: 'null'
title: Detail
type: object
title: UnprocessableEntity
TooManyRequests:
properties:
code:
type: integer
title: Code
default: 429
message:
type: string
title: Message
default: Too Many Requests
detail:
anyOf:
- $ref: '#/components/schemas/RetryAfterDetail'
- type: 'null'
type: object
title: TooManyRequests
InternalServerError:
properties:
message:
type: string
title: Message
default: Internal Server Error
type: object
title: InternalServerError
NotImplementedResponse:
properties:
code:
type: integer
title: Code
default: 501
message:
type: string
title: Message
default: Not Implemented
detail:
anyOf:
- type: string
- type: 'null'
title: Detail
type: object
title: NotImplementedResponse
EngineStatusRead:
properties:
fleet_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Fleet Id
description: Internal fleet identifier.
fleet_ref:
anyOf:
- type: string
- type: 'null'
title: Fleet Ref
description: External fleet reference in the partner system.
id:
type: string
format: uuid
title: Id
description: Unique identifier of the record at Catena Telematics.
created_at:
type: string
format: date-time
title: Created At
description: >-
Immutable: The datetime the record was ingested into Catena
Telematics.
updated_at:
type: string
format: date-time
title: Updated At
description: The dateime the record was last modified in Catena Telematics.
deleted_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Deleted At
description: >-
The datetime the record was logically deleted from Catena
Telematics.
connection_id:
type: string
format: uuid
title: Connection Id
description: >-
Unique identifier of the connection at Catena Telematics through
which this record was ingested. A connection represents a Fleet/TSP
pairing.
tsp_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Tsp Id
description: >-
Unique identifier of the TSP at Catena Telematics from which this
record was ingested.
tsp_slug:
anyOf:
- type: string
- type: 'null'
title: Tsp Slug
description: >-
Human readable slug of the TSP at Catena Telematics from which this
record was ingested.
source_name:
$ref: '#/components/schemas/TspEnum'
description: >-
The underlying telematics platform that provided this data (e.g.,
`samsara`, `motive`, `hos247`). Note: Some platforms like `hos247`
offer white-labeling, so multiple TSPs may share the same
source_name โ use `tsp_id` or `tsp_slug` to identify the specific
ELD provider.
source_data:
additionalProperties: true
type: object
title: Source Data
description: >-
Raw source payload as ingested from the TSP. **Note: use it for
audit/debugging.**
source_id:
type: string
title: Source Id
description: >-
Unique identifier of the record in the TSP. **Note: we generate a
unique composite key based on available fields if the TSP does not
provide an unique ID.**
source_data_hash:
type: string
maxLength: 64
title: Source Data Hash
description: >-
SHA-256 hash of the source data payload. **Note: we use it
internally for idempotence and deduplication.**
occurred_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Occurred At
description: >-
Datetime of when the underlying event/observation occurred, as
reported by the TSP, or the moment it was ingested by us if not
available in the source data.
execution_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Execution Id
description: >-
Unique identifier for the execution that ingested this record into
Catena Telematics. **Note: useful for tracing.**
schedule_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Schedule Id
description: >-
Unique identifier for schedule that triggered this record's
execution. **Note: useful for tracing.**
extras:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Extras
description: >-
Additional data available in the TSP (e.g., we may have
`external_id`, `provider_resource_id`, etc. โ this field captures
all those extra attributes in a flexible way).
vehicle_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Vehicle Id
description: Internal vehicle identifier (Catena FK).
driver_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Driver Id
description: Internal driver identifier (Catena FK).
co_driver_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Co Driver Id
description: Internal co-driver identifier (Catena FK).
source_vehicle_id:
anyOf:
- type: string
- type: 'null'
title: Source Vehicle Id
description: External source system vehicle identifier (from the TSP).
source_driver_id:
anyOf:
- type: string
- type: 'null'
title: Source Driver Id
description: External source system driver identifier (from the TSP).
source_co_driver_id:
anyOf:
- type: string
- type: 'null'
title: Source Co Driver Id
description: External source system co-driver identifier (from the TSP).
location:
anyOf:
- $ref: '#/components/schemas/Point'
- additionalProperties: true
type: object
- {}
- type: 'null'
title: Location
description: Location encoded as GeoJSON Point
h3_index_11:
anyOf:
- type: integer
- type: 'null'
title: H3 Index 11
description: H3 geospatial index (resolution 11) derived from the location.
inferred_address:
anyOf:
- $ref: '#/components/schemas/InferredAddress'
- type: 'null'
description: Inferred city level address from latitude and longitude.
engine_status:
anyOf:
- $ref: '#/components/schemas/EngineStatusEnum'
- type: 'null'
description: Status of the engine (e.g., ON, OFF).
type: object
required:
- fleet_id
- id
- created_at
- updated_at
- connection_id
- source_name
- source_id
- source_data_hash
title: EngineStatusRead
description: Engine status API model with fleet fields.
ValidationErrorDetail:
properties:
path:
type: string
title: Path
input:
type: string
title: Input
message:
type: string
title: Message
error_type:
type: string
title: Error Type
type: object
required:
- path
- input
- message
- error_type
title: ValidationErrorDetail
RetryAfterDetail:
properties:
retry_after_seconds:
type: integer
title: Retry After Seconds
message:
type: string
title: Message
type: object
required:
- retry_after_seconds
- message
title: RetryAfterDetail
TspEnum:
type: string
enum:
- ada
- ai_eld
- air_eld
- alfa_eld
- alpha_eld
- als
- anytrek_pro
- anytrek_classic
- apex_eld
- apollo
- apollocloud
- ascend
- att
- awaregps
- azuga
- bigroad
- bluehorse_eld
- blueinktech
- bouncie
- budgetgps
- catena_simulator
- captain_eld
- carrier_lynx
- club_eld
- counting_trucks_eld
- cyntrx
- digital_eld
- dragon_eld
- drive_hos
- drive_hos_v2
- driver_tech
- dsg_elogs
- dynamic_eld
- eighteighteight_eld
- eld_88
- eld_books
- eld_mandate
- eld_mandate_prime
- eroad
- eva_eld
- evo_eld
- expressway_eld
- extreme_eld
- ezlogz
- ez_lynk
- factor_eld
- firstgate
- fleetcomplete
- fleetcompletehub
- fleethunt
- fleetpulse
- fleetsharp
- fleetup
- fm
- forwardthinking
- forza_eld
- geotab
- gpsinsight
- gpstab
- gpstrackit
- grand_eld
- greenlight
- groundhog
- hcss
- hos247
- hutch
- intellishift
- ironman_eld
- isaac
- jjkeller
- kinexaiot
- knight_eld
- konexial
- lioneight
- linxup
- loop_eld
- lucid_eld
- luna_eld
- lytx
- lytxv3
- mapon
- matrack
- maven
- mdm_eld
- mobilefleet
- moonlight_eld
- motion_eld
- motive
- my_drivebook
- my_logs_eld
- nero
- netradyne
- new_eld_world
- nextgen_eld
- nextraq
- omnitracs
- onestep
- ontime_eld
- optima
- orbcomm
- orient_eld
- panda_eld
- payd
- peak_eld
- peoplenet
- phillips_connect
- phoenix
- pop_eld
- prologs
- proride_eld
- qualitylogs_eld
- randmcnally
- rastrac
- raven
- redfox
- regulog_eld
- ridehub
- roadeazy
- rock_eld
- rollingtrans
- routemate
- royal_eld
- safelane
- samsara
- selectivedrive
- simba_eld
- skybitz
- smart_elds
- sparkle_eld
- spireon
- sun_eld
- surfsight
- swift
- switchboard
- synergy_eld
- teletracnavman
- teletracnavman_director
- telogis
- tenna
- thermo_king
- think
- tive
- topcompliance_eld
- traccar
- trackease_eld
- trackpro
- traclog
- transflo
- trimble
- truckford
- truckspy
- truckx
- trueroad_eld
- tt
- txt_eld
- us_fast_eld
- verizon_connect
- vista_eld
- vistracks
- vlog_eld
- vulcansols_eld
- wialon
- webfleet
- xplore_eld
- zigzag_eld
- zms_eld
- zonar
- zubie
title: TspEnum
description: Enum for TSPs
Point:
properties:
bbox:
anyOf:
- prefixItems:
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 4
minItems: 4
- prefixItems:
- type: number
- type: number
- type: number
- type: number
- type: number
- type: number
type: array
maxItems: 6
minItems: 6
- type: 'null'
title: Bbox
type:
type: string
const: Point
title: Type
coordinates:
anyOf:
- $ref: '#/components/schemas/Position2D'
- $ref: '#/components/schemas/Position3D'
title: Coordinates
type: object
required:
- type
- coordinates
title: Point
description: Point Model
InferredAddress:
properties:
city:
anyOf:
- type: string
- type: 'null'
title: City
province:
anyOf:
- type: string
- type: 'null'
title: Province
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
type: object
title: InferredAddress
description: Inferred location, reverse-geocoded from lat/long
EngineStatusEnum:
type: string
enum:
- 'OFF'
- 'ON'
- IDLE
- TOWING
- UNKNOWN
title: EngineStatusEnum
description: Normalized engine states across telematics providers
Position2D:
prefixItems:
- type: number
title: Longitude
- type: number
title: Latitude
type: array
maxItems: 2
minItems: 2
Position3D:
prefixItems:
- type: number
title: Longitude
- type: number
title: Latitude
- type: number
title: Altitude
type: array
maxItems: 3
minItems: 3
securitySchemes:
Bearer:
type: oauth2
flows:
clientCredentials:
refreshUrl: >-
https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
scopes: {}
tokenUrl: >-
https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
authorizationCode:
refreshUrl: >-
https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
scopes: {}
authorizationUrl: >-
https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/auth
tokenUrl: >-
https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
````