Skip to main content
GET
List Vehicles

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

fleet_ids
string<uuid>[] | null

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).

Maximum array length: 100
fleet_refs
string[] | null

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).

Maximum array length: 100
connection_id
string<uuid> | null

Limit results to a specific provider connection. This is the UUID assigned by Catena when your fleet connects to a TSP.

include_source_data
boolean
default:false

Include the raw data from the telematics provider. Useful for auditing or accessing fields not normalized by Catena

vehicle_ids
string<uuid>[] | null

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).

Maximum array length: 100
source_ids
string[] | null

Limit results to specific resources using the identifier provided by the TSP. Maximum: 100 IDs To specify multiple values, repeat the parameter for each value (e.g., ?source_ids=id1&source_ids=id2).

Maximum array length: 100
vins
string[] | null

Limit results to vehicles with these VINs (exact, case-sensitive match). Maximum: 100 values. To specify multiple values, repeat the parameter for each value (e.g., ?vins=vin1&vins=vin2).

Maximum array length: 100
license_plate_numbers
string[] | null

Limit results to vehicles with these license plate numbers (exact, case-sensitive match). The same plate number can be issued in different regions, so combine with license_plate_regions to narrow it. Maximum: 100 values. To specify multiple values, repeat the parameter for each value (e.g., ?license_plate_numbers=plate1&license_plate_numbers=plate2).

Maximum array length: 100
license_plate_regions
string[] | null

Limit results to vehicles with plates registered in these regions (exact, case-sensitive match on the state/province code, e.g. TX, ON). Maximum: 100 values. To specify multiple values, repeat the parameter for each value (e.g., ?license_plate_regions=TX&license_plate_regions=CA).

Maximum array length: 100
sort_by
string | null

The name of the field to sort results by. If not provided, results will be ordered by occurred_at.

sort_order
enum<string>
default:asc

The order of sorting, either asc for ascending or desc for descending. Defaults to asc if sort_by is provided without sort_order.

Available options:
asc,
desc
q
string | null

Return only records whose searchable fields start with this term (the default), or contain it when match=contains, matched case-insensitively. Matched fields: vehicles are matched on vehicle_name; trailers on trailer_name; users are matched on their first name, their last name, or their full name (first_name, a space, last_name). The full name is matched as one string: with match=prefix it must start with the term, so jo sm matches Jo Smalls but not Joanna Smith; with match=contains the term may appear anywhere in it, including across the space. A record matches if any one of its searchable fields matches. Prefix or substring: with the default match=prefix, abc matches ABC-1042 but not TRK-ABC; with match=contains, 645 matches A645 and Truck 6450. Literal characters: %, _ and \ are matched literally, so ABC_1 does not match ABC91. Ordering: results keep the endpoint's default order (occurred_at), which is not useful for a dropdown. Pass sort_by=vehicle_name (vehicles) or sort_by=last_name (users) for an alphabetical list. Rate limits: requests to /v2/telematics are throttled at 60 per second per source IP, so debounce type-ahead input by 300 ms or more. Surrounding whitespace is stripped; a term that is only whitespace is treated as if q were not supplied. Length: 1 to 100 characters.

Required string length: 1 - 100
match
enum<string>
default:prefix

How q is matched. prefix: the searchable field starts with q. contains: the searchable field contains q anywhere, so 645 finds A645. Has no effect when q is not supplied, but must still be one of the two values.

Available options:
prefix,
contains
cursor
string | null

Cursor for the next page

size
integer
default:300

Page size

Required range: 1 <= x <= 1000

Response

Successful Response

items
VehicleRead · object[]
required
total
integer
required
Required range: x >= 0
current_page
string | null

Cursor to refetch the current page

current_page_backwards
string | null

Cursor to refetch the current page starting from the last item

previous_page
string | null

Cursor for the previous page

next_page
string | null

Cursor for the next page