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

# Trip replay

> Paginated trip replay for a vehicle within a date range.

### Overview

Returns a paginated list of trips for the vehicle between `from` and `to` (both UTC), ordered oldest first. Each trip includes route points, addresses, and a Google Polyline encoded path.

<Note>This endpoint is equivalent to V1 [Trip Replay (UTC)](/v1/api-reference/post-get-replay) and [Trip replay (user time)](/v1/api-reference/post-get-replay-user-time). V2 is paginated.</Note>

<Note>**Rate limit:** 4 req/s · 20/min · 600/hr · 14,400/day</Note>

### Endpoint

`GET /v2/api/replay/{id}`

### Path parameters

<ParamField path="id" type="integer" required>
  Vehicle ID.
</ParamField>

### Query parameters

<ParamField query="from" type="string (datetime)">
  Range start (UTC, ISO 8601).
</ParamField>

<ParamField query="to" type="string (datetime)">
  Range end (UTC, ISO 8601).
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField query="pageSize" type="integer" default="50">
  Records per page (max 500).
</ParamField>

### Response

**200 OK** — `PagedListResult<TripDto>`

| Field         | Type           | Description                                                                                            |
| ------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
| distance      | number \| null | Trip distance in km (odometer delta — see note below)                                                  |
| duration      | string         | Trip duration as .NET `TimeSpan` string: `"hh:mm:ss"` for \< 1 day, `"d.hh:mm:ss.fffffff"` for ≥ 1 day |
| startAddress  | string         | Reverse-geocoded start address                                                                         |
| endAddress    | string         | Reverse-geocoded end address                                                                           |
| startTimeUser | string         | Trip start in user's timezone (formatted string)                                                       |
| endTimeUser   | string         | Trip end in user's timezone (formatted string)                                                         |
| encoded       | string         | Google Polyline Algorithm encoded path — decode with any standard polyline library                     |
| url           | string         | Google Static Maps thumbnail URL (⚠ requires valid API key configured server-side)                     |
| points        | array          | Array of `PointDto` — see below                                                                        |

<Warning>
  **`distance` is in km, not metres.** It is calculated as `lastPoint.odometer − startPoint.odometer` where odometer is stored in km. A value of `11.34` means 11.34 km.

  **`duration`** is a .NET `TimeSpan` serialised without a custom converter — format is `"03:05:50"` (hh:mm:ss) or `"2.04:04:21.0100000"` (d.hh:mm:ss.fffffff) for multi-day trips. It is **not** ISO 8601.
</Warning>

`PointDto` fields (items in `points`). All field names are **camelCase** — no `[JsonPropertyName]` overrides.

| Field      | Type            | Description                                          |
| ---------- | --------------- | ---------------------------------------------------- |
| lat        | number          | Latitude                                             |
| lng        | number          | Longitude                                            |
| timeUtc    | datetime        | Point timestamp (UTC, no fractional seconds)         |
| speed      | number          | Speed at this point (km/h)                           |
| direction  | number          | Compass heading in degrees (N=0, E=90, S=180, W=270) |
| ignition   | boolean         | Ignition state at this point                         |
| timeUser   | datetime        | Point timestamp in the user's timezone               |
| odo        | number \| null  | Odometer reading at this point (km)                  |
| fuelLevel  | integer \| null | Fuel level at this point (%)                         |
| fuelVolume | number \| null  | Fuel volume at this point (litres)                   |

### Error responses

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| 401    | Token does not have access to this vehicle |
| 403    | Token scope does not include replay access |
| 404    | Vehicle not found                          |
| 422    | Invalid date range                         |

```bash theme={null}
curl "https://api.telemax.com.au/v2/api/replay/88421?from=2026-04-01T00:00:00Z&to=2026-04-02T00:00:00Z&page=1&pageSize=20" \
  -H "Authorization: Bearer <token>"
```


## OpenAPI

````yaml openapi.yaml GET /v2/api/replay/{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/replay/{id}:
    get:
      summary: Trip replay (V2)
      description: Paginated trip replay for a vehicle within a date range.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
          example: 88421
        - name: from
          in: query
          schema:
            type: string
            format: date-time
          example: '2026-04-01T00:00:00Z'
        - name: to
          in: query
          schema:
            type: string
            format: date-time
          example: '2026-04-02T00:00:00Z'
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              example:
                items:
                  - distance: 14
                    duration: '00:20:22'
                    startAddress: 31, Diamantina Cir, Karalee, Brisbane, Qld, AUS
                    endAddress: 5, Gordon St, Ipswich, Brisbane, Qld, AUS
                    startTimeUser: 05/12/2026 08:09:09
                    endTimeUser: 05/12/2026 08:29:31
                    encoded: _p~iF~ps|U_ulLnnqC_mqNvxq`@
                    url: https://maps.googleapis.com/maps/api/staticmap?...
                    points:
                      - lat: -27.536263
                        lng: 152.840733
                        timeUtc: '2026-05-12T01:09:09'
                        speed: 0
                        direction: 260
                        ignition: true
                        timeUser: '2026-05-12T08:09:09'
                        odo: 47465
                        fuelLevel: 92
                        fuelVolume: null
                totalResults: 31
                lastResultIndex: 1
                currentPage: 1
                numberOfPages: 31
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            **404 Not Found** — The requested vehicle does not exist or is not
            accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                type: RESOURCE
                code: NOT_FOUND
                description: Vehicle was not found.
                requestId: 0HNLTALNU4DDO:00000003
                docUrl: https://docs.telemax.com.au/errors/not-found
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '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
    UnprocessableEntity:
      description: >
        **422 Unprocessable Entity** — A parameter is present but has an invalid
        format (e.g. negative vehicle ID, malformed ISO 8601 date string).
      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: VALIDATION_ERROR
            code: INVALID_INPUT
            description: One or more route or query parameters could not be parsed.
            requestId: req_9f3e7c1b
            docUrl: https://docs.telemax.com.au/errors/invalid-input
    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
  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
  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
  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.

````