> ## 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 Region Segments

> List region segment aggregates visible to the authenticated organization.

<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, response fields, or query parameters 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/telematics/openapi.json get /v2/telematics/vehicle-region-segments
openapi: 3.1.0
info:
  title: Telematics Data Service - REST API
  description: Telematics Data Service REST API.
  version: 0.1.0
servers:
  - url: https://api.catenatelematics.com
    description: Catena Telematics API
security: []
tags:
  - name: Fleet Operations & Tracking
    description: >-
      Endpoints for tracking vehicles, trailers, assets, and trip activity —
      including locations, movements, and operational telemetry. Useful for
      monitoring utilization and real-time operational status.
  - name: Safety & Driver Behavior
    description: >-
      Endpoints that provide safety-related insights such as harsh braking,
      speeding, and other driver behavior events. Supports risk analysis and
      safety program automation.
  - name: Compliance & Regulation
    description: >-
      Endpoints covering regulated requirements including DVIR inspections,
      Hours of Service (HOS), violations, and IFTA fuel tax reporting. Helps
      organizations meet DOT/FMCSA and interstate regulatory obligations.
  - name: Maintenance & Vehicle Health
    description: >-
      Endpoints providing data for vehicle condition monitoring and maintenance
      workflows, such as DVIR defects and diagnostic sensor events. Enables
      early issue detection and reduced downtime.
  - name: Drivers & Users
    description: >-
      Endpoints related to driver and user identities, assignments, and
      operational context. Supports linking operational and safety data to
      specific individuals.
  - name: Reference Data (Supporting Tables)
    description: >-
      Lookup tables and enumerations that supply standardized codes, metadata,
      and classifications used across the API.
  - name: Analytics (deprecated)
    description: >-
      Endpoints providing analytical insights and aggregated data for vehicles,
      fleets, drivers, and trailers.
paths:
  /v2/telematics/vehicle-region-segments:
    get:
      tags:
        - Fleet Operations & Tracking
      summary: List Vehicle Region Segments
      description: >-
        List region segment aggregates visible to the authenticated
        organization.
      operationId: list_vehicle_region_segments
      parameters:
        - name: group_by
          in: query
          required: false
          schema:
            anyOf:
              - const: segment
                type: string
              - type: 'null'
            description: >-
              Optional grouping mode. Use `segment` to collapse repeated visits
              to the same region for a vehicle within the filtered window, using
              the min start time and max end time.
            title: Group By
          description: >-
            Optional grouping mode. Use `segment` to collapse repeated visits to
            the same region for a vehicle within the filtered window, using the
            min start time and max end time.
        - name: include_vehicle
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              If true, each segment will include a `vehicle` object with basic
              vehicle information. Segments without a matching vehicle will have
              `vehicle` set to null.
            default: false
            title: Include Vehicle
          description: >-
            If true, each segment will include a `vehicle` object with basic
            vehicle information. Segments without a matching vehicle will have
            `vehicle` set to null.
        - 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: from_date
          in: query
          required: false
          schema:
            type: string
            format: date
            description: >-
              Return only records with a processing date on or after this date.
              **Format:** YYYY-MM-DD **Applies filter:** `processing_date >=
              from_date` **Default value:** yesterday **Restriction:** `to_date
              - from_date` cannot exceed 45 days
            examples:
              - '2026-06-25'
            title: From Date
          description: >-
            Return only records with a processing date on or after this date.
            **Format:** YYYY-MM-DD **Applies filter:** `processing_date >=
            from_date` **Default value:** yesterday **Restriction:** `to_date -
            from_date` cannot exceed 45 days
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date
            description: >-
              Return only records with a processing date on or before this date.
              **Format:** YYYY-MM-DD **Applies filter:** `processing_date <=
              to_date` **Default value:** today **Restriction:** `to_date -
              from_date` cannot exceed 45 days
            examples:
              - '2026-06-26'
            title: To Date
          description: >-
            Return only records with a processing date on or before this date.
            **Format:** YYYY-MM-DD **Applies filter:** `processing_date <=
            to_date` **Default value:** today **Restriction:** `to_date -
            from_date` cannot exceed 45 days
        - 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: country_code
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Limit results to a specific country using its ISO 3166-1 alpha-3
              code (e.g., `USA`, `CAN`).
            title: Country Code
          description: >-
            Limit results to a specific country using its ISO 3166-1 alpha-3
            code (e.g., `USA`, `CAN`).
        - name: region
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Limit results to a specific region or state within the country
              (e.g., `TX`, `ON`).
            title: Region
          description: >-
            Limit results to a specific region or state within the country
            (e.g., `TX`, `ON`).
        - 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_VehicleRegionSegmentRead_'
        '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_VehicleRegionSegmentRead_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/VehicleRegionSegmentRead'
          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[VehicleRegionSegmentRead]
    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
    VehicleRegionSegmentRead:
      properties:
        fleet_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Fleet Id
          description: Internal fleet identifier.
        fleet_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Fleet Ref
          description: External fleet reference in the partner system.
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier of the record at Catena Telematics.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: >-
            Immutable: The datetime the record was ingested into Catena
            Telematics.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: The dateime the record was last modified in Catena Telematics.
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deleted At
          description: >-
            The datetime the record was logically deleted from Catena
            Telematics.
        connection_id:
          type: string
          format: uuid
          title: Connection Id
          description: >-
            Unique identifier of the connection at Catena Telematics through
            which this record was ingested. A connection represents a Fleet/TSP
            pairing.
        processing_date:
          type: string
          format: date
          title: Processing Date
          description: >-
            UTC day for which the region segments are listed, bounded from 00:00
            to 00:00 UTC.
        vehicle_id:
          type: string
          format: uuid
          title: Vehicle Id
          description: Internal vehicle identifier (Catena FK).
        driver_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Driver Id
          description: >-
            Internal driver identifier associated with the segment, if
            available.
        country_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Country Code
          description: ISO-3166-1 alpha-3 country code inferred for the segment.
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: >-
            Region code inferred for the segment, typically a state or province
            in IFTA contexts.
        segment_start_time:
          type: string
          format: date-time
          title: Segment Start Time
          description: UTC timestamp of the first location sample in the segment.
        segment_end_time:
          type: string
          format: date-time
          title: Segment End Time
          description: UTC timestamp of the last location sample in the segment.
        odometer_start:
          anyOf:
            - type: number
            - type: 'null'
          title: Odometer Start
          description: >-
            Odometer reading at the start of the segment (SI units from source
            system).
        odometer_end:
          anyOf:
            - type: number
            - type: 'null'
          title: Odometer End
          description: >-
            Odometer reading at the end of the segment (SI units from source
            system).
        distance:
          anyOf:
            - type: number
            - type: 'null'
          title: Distance
          description: >-
            Distance traveled during the segment, derived from odometer delta
            (SI units).
        location_count:
          type: integer
          title: Location Count
          description: Number of location samples that belong to the segment.
        odometer_start_unit:
          $ref: '#/components/schemas/DistanceUnit'
          description: Unit for odometer_start.
          default: m
        odometer_end_unit:
          $ref: '#/components/schemas/DistanceUnit'
          description: Unit for odometer_end.
          default: m
        distance_unit:
          $ref: '#/components/schemas/DistanceUnit'
          description: Unit for distance.
          default: m
        vehicle:
          anyOf:
            - $ref: '#/components/schemas/VehicleEmbeddedRead'
            - type: 'null'
          description: >-
            Basic vehicle information. Only populated when
            `include_vehicle=true` is requested.
      type: object
      required:
        - fleet_id
        - id
        - created_at
        - updated_at
        - connection_id
        - processing_date
        - vehicle_id
        - segment_start_time
        - segment_end_time
        - location_count
      title: VehicleRegionSegmentRead
      description: >-
        API/read model for IFTA region segments a vehicle entered during a
        specific UTC day (00:00 to 00:00 UTC).
    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
    DistanceUnit:
      type: string
      enum:
        - m
        - km
        - mi
        - ft
        - nmi
      title: DistanceUnit
      description: Units for normalized distance and odometer fields.
    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.
        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').
        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

````