Skip to navigation
IntelligenceBenchmarks

Get vehicle utilization benchmarks

Retrieve a vehicle’s daily utilization (meters/day) and percentile rank across all cohorts the vehicle is assigned to. Each entry in the response corresponds to one cohort. Percentile and cohort statistics are suppressed when a cohort is too small to meet the k-anonymity floor.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

vehicle_idstringRequiredformat: "uuid"

Query parameters

from_datedate or nullOptional

Inclusive start of the benchmark window. Format: YYYY-MM-DD Default: 30 days before yesterday (trailing-30d hot window). Restriction: to_date - from_date cannot exceed 90 days.

to_datedate or nullOptional

Inclusive end of the benchmark window. Format: YYYY-MM-DD Default: yesterday (most recent completed day in the utilization pipeline). Restriction: to_date - from_date cannot exceed 90 days.

Response

Successful Response
vehicle_idstringformat: "uuid"
Catena vehicle identifier.
cohort_idstringformat: "uuid"
Cohort the vehicle was benchmarked against.
windowobject
Date range used for the benchmark.
vehicle_valueinteger or null

Vehicle’s average meters/day over the window. Null if the vehicle has no utilization data.

percentileinteger or null

Vehicle’s percentile rank (0-100) within the cohort daily distribution. Null if suppressed by k-anonymity or data unavailable.

cohortobject or null

Cohort size metrics. Null if suppressed by k-anonymity or data unavailable.

cachedboolean

True when the response was served from the pre-computed percentile cache; False when computed live from daily sketches.

metric"meters_driven"OptionalDefaults to meters_driven

Metric being benchmarked (v1: always ‘meters_driven’).

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
405
Method Not Allowed Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
501
Not Implemented Error