> ## 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 Vehicle Insurance Signals

> Retrieve underwriting signals per vehicle for your accessible fleets over a requested time window. Each row carries safety event counts (speeding, harsh cornering, harsh braking) and the distance the vehicle traveled in the window. All signals are measured over the same window, so counts and distance can be combined into per-distance rates directly. The window cannot exceed 90 days.

<Callout icon="vial" color="#FFC107" iconType="solid"><strong>Provisional endpoint</strong><br />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.<br /><br /><em>See <a href="/api-reference/stability-versioning">API Stability & Versioning</a> for details on provisional endpoints.</em></Callout>


## OpenAPI

````yaml https://api.catenatelematics.com/v2/intelligence/openapi.json get /v2/intelligence/insurance/vehicle-signals
openapi: 3.1.0
info:
  title: Telematics Intelligence Service - REST API
  description: Telematics Intelligence Service REST API.
  version: 0.1.0
servers:
  - url: https://api.catenatelematics.com
    description: Catena Intelligence API
security: []
tags:
  - name: Analytics
    description: >-
      Endpoints providing analytical insights and aggregated data for vehicles,
      fleets, drivers, and trailers.
  - name: Benchmarks
    description: >-
      Endpoints providing cross-fleet benchmark data. A vehicle's metrics are
      ranked against a cohort of peer vehicles drawn from the full Catena fleet
      population. Cohort statistics are k-anonymised: percentile and cohort
      counts are suppressed when the cohort covers too few distinct fleets to
      protect individual fleet privacy.
paths:
  /v2/intelligence/insurance/vehicle-signals:
    get:
      tags:
        - Insurance Signals
      summary: List vehicle insurance signals
      description: >-
        Retrieve underwriting signals per vehicle for your accessible fleets
        over a requested time window. Each row carries safety event counts
        (speeding, harsh cornering, harsh braking) and the distance the vehicle
        traveled in the window. All signals are measured over the same window,
        so counts and distance can be combined into per-distance rates directly.
        The window cannot exceed 90 days.
      operationId: list_vehicle_insurance_signals
      parameters:
        - 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: 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: 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 90 days
            examples:
              - '2026-08-07T00:17:24.765188Z'
            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 90 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 90 days
            examples:
              - '2026-08-08T00:17:24.765238Z'
            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 90 days
        - 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_VehicleInsuranceSignalsRead_'
        '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_VehicleInsuranceSignalsRead_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/VehicleInsuranceSignalsRead'
          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[VehicleInsuranceSignalsRead]
    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
    VehicleInsuranceSignalsRead:
      properties:
        vehicle:
          $ref: '#/components/schemas/VehicleEmbeddedRead'
          description: Identifying details for the vehicle that this row describes.
        fleet_refs:
          items:
            type: string
          type: array
          title: Fleet Refs
          description: >-
            Your assigned reference IDs for the fleets this vehicle is visible
            through. Almost always one. Empty when no reference has been
            assigned to any of them. The signals below describe the vehicle
            itself and do not vary by fleet.
        fleet_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Fleet Ids
          description: >-
            Catena fleet identifiers for the same fleets. Several identifiers
            can share a single `fleet_refs` entry, so this list is usually the
            longer of the two and the two are not positionally paired. Prefer
            `fleet_refs` for grouping and reporting.
        speeding_event_count:
          type: integer
          title: Speeding Event Count
          description: Number of speeding events reported for this vehicle in the window.
        harsh_turn_count:
          type: integer
          title: Harsh Turn Count
          description: >-
            Number of harsh cornering events recorded for this vehicle in the
            window.
        harsh_brake_count:
          type: integer
          title: Harsh Brake Count
          description: >-
            Number of harsh braking events recorded for this vehicle in the
            window.
        distance_traveled_meters:
          anyOf:
            - type: integer
            - type: 'null'
          title: Distance Traveled Meters
          description: >-
            Distance traveled in meters over the window, measured as the
            difference between the first and last odometer readings inside it. 
      type: object
      required:
        - vehicle
        - fleet_refs
        - fleet_ids
        - speeding_event_count
        - harsh_turn_count
        - harsh_brake_count
      title: VehicleInsuranceSignalsRead
      description: >-
        Underwriting signals for a single vehicle over the requested time
        window.
    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
    VehicleEmbeddedRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier of the record at Catena Telematics.
        vehicle_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Vehicle Name
          description: Display name or unit number for the vehicle.
        oem:
          anyOf:
            - type: string
            - type: 'null'
          title: Oem
          description: Manufacturer (OEM) of the vehicle.
        model_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Type
          description: >-
            Manufacturer model or type designation (e.g., 'Class 8 Tractor',
            'Pickup').
        model_year:
          anyOf:
            - type: integer
            - type: 'null'
          title: Model Year
          description: Model year (four-digit, e.g., 2022).
        vin:
          anyOf:
            - type: string
            - type: 'null'
          title: Vin
          description: >-
            Vehicle Identification Number (VIN), typically 17 characters; if
            available.
        license_plate_region:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Region
          description: Plate region/subdivision (state/province code, e.g., 'CA', 'ON').
        license_plate_country:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Country
          description: Plate country code (ISO-3166-1 alpha-3, e.g., 'USA', 'CAN').
        license_plate_number:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Number
          description: License plate number (e.g., 'HMT-3570').
        is_active:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Active
          description: Indicates whether the vehicle is currently active/in service.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: >-
            Operational status label (e.g., 'IN_SERVICE', 'OUT_OF_SERVICE',
            'MAINTENANCE').
        eld_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Eld Id
          description: >-
            Telematics/ELD device identifier associated with this vehicle, if
            any.
        eld_serial_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Eld Serial Number
          description: Telematics/ELD device serial number, if any.
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
          description: Unique identifier of the record in the TSP.
        external_id:
          anyOf:
            - type: string
            - type: 'null'
          title: External Id
          description: >-
            External vehicle identifier as known in the TSP or customer's
            system.
      type: object
      required:
        - id
      title: VehicleEmbeddedRead
      description: Lightweight vehicle snapshot embedded in other API responses.
  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

````