> ## Documentation Index > Fetch the complete documentation index at: https://docs.telemax.com.au/llms.txt > Use this file to discover all available pages before exploring further. # Safety score > Trip safety scores for a vehicle over a date range. ### Overview Returns trip-level safety scores for the specified vehicle. Supports explicit date ranges or preset time windows via `intervalType`. This endpoint is not yet deployed in the staging environment (`api-stage.telemax.com.au`). All requests to staging return `PATH_NOT_FOUND`. Test against production only. The V1 version of this endpoint is [Safety score](/v1/api-reference/post-get-safety-score). **Rate limit:** 10 req/s · 30/min · 6,000/hr · 144,000/day ### Endpoint `GET /v2/api/safety-score/{id}` ### Path parameters Vehicle ID. ### Query parameters Range start. Optional when `intervalType` is supplied. Range end. Optional when `intervalType` is supplied. Preset window, used only when `start` and `finish` are omitted: * `1` — instant range (uses `DateTime.UtcNow` as start) * `2` — relative to end of today in the user's timezone * `3` — three-day window * `4` — week window > ⚠️ The window arithmetic uses a double-negative (`-TimeSpan.FromDays(-N)`) which **adds** days to `finish` for types 2–4. Validate results in staging before using preset windows in production. ### Response **200 OK** — array of trip safety score objects. | Field | Type | Description | | --------- | --------------- | ---------------------------------- | | startTime | datetime | Trip start time | | endTime | datetime | Trip end time | | riskLevel | string | `"Low"`, `"Medium"`, or `"High"` | | riskScore | integer (0–100) | Numeric risk score; lower is safer | | duration | integer | Trip duration in **seconds** | | distance | number | Trip distance in **km** | ### Error responses | Status | Meaning | | ------ | ------------------------------------------------ | | 401 | Token does not have access to this vehicle | | 403 | Token scope does not include safety score access | | 404 | Vehicle not found | | 400 | Invalid date range | ```bash theme={null} curl "https://api.telemax.com.au/v2/api/safety-score/88421?start=2026-04-01T00:00:00Z&finish=2026-04-28T00:00:00Z" \ -H "Authorization: Bearer " ``` ## OpenAPI ````yaml openapi.yaml GET /v2/api/safety-score/{id} openapi: 3.1.0 info: title: Telemax External API (V2) version: '2026-04-14' description: > Telemax External API — fleet telemetry, vehicle commands, and integrations. **Base URL:** `https://api.telemax.com.au` **Authentication:** All routes require a `Bearer` JWT unless marked `[AllowAnonymous]`. Obtain tokens via `POST /v2/api/authentication/token/api-key`. **RESTful architecture:** V2 uses standard HTTP methods (GET, POST, PUT, DELETE) with resource-based routes and consistent pagination via `page` and `pageSize` query parameters. **API versioning:** All responses will include an `X-API-Version` header containing the date-based version string (e.g. `2026-04-28`). See the [Changelog](/v2/changelog) for the deprecation policy and version history. For full documentation including error handling, pagination, and known field quirks, see [docs.telemax.com.au](https://docs.telemax.com.au). servers: - url: https://api.telemax.com.au security: - BearerAuth: [] paths: /v2/api/safety-score/{id}: get: summary: Safety score (V2) description: Trip safety scores for a vehicle over a date range. parameters: - name: id in: path required: true schema: type: integer example: 88421 - name: start in: query schema: type: string format: date-time example: '2026-04-01T00:00:00Z' - name: finish in: query schema: type: string format: date-time example: '2026-04-28T00:00:00Z' - name: intervalType in: query schema: type: integer description: 'Preset window: 1=instant, 2=today, 3=3-day, 4=week.' responses: '200': description: Successful response content: application/json: example: - startTime: '2026-04-28T03:10:00Z' endTime: '2026-04-28T03:38:00Z' riskLevel: Low riskScore: 18 duration: 1694 distance: 23.6 '400': description: Invalid date range '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: responses: Unauthorized: description: > **401 Unauthorized** — JWT is missing, expired, or malformed. The JWT bearer middleware rejects the request before it reaches the controller. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: AUTHENTICATION code: INVALID_CREDENTIALS description: The provided API key is invalid or does not exist. requestId: 0HNLTALNU4DCO:00000004 docUrl: https://docs.telemax.com.au/errors/invalid-credentials Forbidden: description: > **403 Forbidden** — Token is valid but the caller does not have access to the requested company or vehicle. Tokens issued for one company cannot access resources scoped to a different company in the hierarchy. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: AUTHORIZATION code: INVALID_SCOPE description: >- The provided token does not have permission to access this resource. requestId: 50e5c5f7-ccae-4ab6-b070-56d6645ceb1e docUrl: https://docs.telemax.com.au/errors/invalid-scope NotFound: description: > **404 Not Found** — The requested vehicle ID, company ID, or IMEI does not exist or is not accessible. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: RESOURCE code: NOT_FOUND description: The requested resource could not be found. requestId: c9f09b2f-3999-4245-89f5-4556ad775dbb docUrl: https://docs.telemax.com.au/errors/not-found TooManyRequests: description: > **429 Too Many Requests** — Rate limit exceeded. Check the Retry-After header for the number of seconds to wait before retrying. Use exponential backoff: wait Retry-After seconds, then double the interval on each subsequent 429. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' Retry-After: $ref: '#/components/headers/Retry-After' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: RATE_LIMIT code: RATE_LIMIT_EXCEEDED description: Too many requests. Please slow down. requestId: req_6d2f8b4a docUrl: https://docs.telemax.com.au/errors/rate-limit-exceeded InternalServerError: description: > **500 Internal Server Error** — An unexpected error occurred. Include the requestId when contacting support. headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/ApiError' example: type: SERVER_ERROR code: INTERNAL_SERVER_ERROR description: An unexpected error occurred. Please try again later. requestId: req_1e5a3c7d docUrl: https://docs.telemax.com.au/errors/internal-server-error headers: X-RateLimit-Limit: description: >- Maximum number of requests allowed per minute for this token. **Not yet active** — this header will be added once the rate-limit middleware is deployed. See the [Changelog](/v2/changelog) for the rollout date. schema: type: integer example: 60 X-RateLimit-Remaining: description: >- Number of requests remaining in the current rate limit window. **Not yet active** — see `X-RateLimit-Limit`. schema: type: integer example: 47 X-RateLimit-Reset: description: >- Unix timestamp (seconds) at which the current rate limit window resets. **Not yet active** — see `X-RateLimit-Limit`. schema: type: integer example: 1746000060 Retry-After: description: Number of seconds to wait before retrying after a 429 response. schema: type: integer example: 30 schemas: ApiError: type: object description: Standard error response returned by all API endpoints. properties: type: type: string description: >- Error category (e.g. AUTHENTICATION, AUTHORIZATION, RESOURCE, VALIDATION_ERROR, RATE_LIMIT, SERVER_ERROR). example: AUTHENTICATION code: type: string description: Machine-readable error code within the category. example: INVALID_CREDENTIALS description: type: string description: Human-readable explanation of the error and how to resolve it. example: The provided API key is invalid or does not exist. requestId: type: string description: Unique request identifier for support correlation. example: req_7f3a2b1c docUrl: type: string format: uri description: Link to the relevant error documentation page. example: https://docs.telemax.com.au/errors/invalid-credentials required: - type - code - description securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: > JWT Bearer token obtained from `POST /v2/api/authentication/token/api-key`. **Lifetime:** ~24 hours (86,399 seconds). Cache the token and reuse it. Re-authenticate 5 minutes before expiry. **Scoping:** API key tokens are scoped to the company the key belongs to and may restrict access to a vehicle allowlist and/or action set (see token claims). **No refresh endpoint** — re-authenticate with your API key when the token expires. ````