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

# 🧪 Stop Detection

> Retrieve detected stops for vehicles in your accessible fleets. Optionally filter to specific vehicles or a time window. A stop is included when it was active at any point during the requested window: it started before `active_to_datetime` and had not yet ended by `active_from_datetime`. (In the query-parameter schema, `started_at`/`ended_at` wording maps to this endpoint's `start_date`/`end_date`.)

<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/stops/vehicles
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/stops/vehicles:
    get:
      tags:
        - Stop Detection
      summary: List vehicle stop history
      description: >-
        Retrieve detected stops for vehicles in your accessible fleets.
        Optionally filter to specific vehicles or a time window. A stop is
        included when it was active at any point during the requested window: it
        started before `active_to_datetime` and had not yet ended by
        `active_from_datetime`. (In the query-parameter schema,
        `started_at`/`ended_at` wording maps to this endpoint's
        `start_date`/`end_date`.)
      operationId: list_vehicle_stops
      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: active_from_datetime
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: >-
              Return only records that were still active at or after this date
              and time. **Format:** ISO 8601 (UTC) **Applies filter:** `ended_at
              >= active_from_datetime`
            examples:
              - '2026-07-07T02:04:07.307993Z'
            title: Active From Datetime
          description: >-
            Return only records that were still active at or after this date and
            time. **Format:** ISO 8601 (UTC) **Applies filter:** `ended_at >=
            active_from_datetime`
        - name: active_to_datetime
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: >-
              Return only records that started before this date and time.
              **Format:** ISO 8601 (UTC) **Applies filter:** `started_at <
              active_to_datetime`
            examples:
              - '2026-07-08T02:04:07.308053Z'
            title: Active To Datetime
          description: >-
            Return only records that started before this date and time.
            **Format:** ISO 8601 (UTC) **Applies filter:** `started_at <
            active_to_datetime`
        - name: known_stops_only
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              When `true`, return only stops that have been matched to a known
              place (i.e. `place_id` is set). Orphan stops — those not yet
              attached to a place — are excluded.
            default: false
            title: Known Stops Only
          description: >-
            When `true`, return only stops that have been matched to a known
            place (i.e. `place_id` is set). Orphan stops — those not yet
            attached to a place — are excluded.
        - name: stop_categories
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                maxItems: 50
              - type: 'null'
            description: >-
              Limit results to stops with one of the specified categories. To
              specify multiple values, repeat the parameter (e.g.
              `?stop_categories=FUEL&stop_categories=REST`).
            title: Stop Categories
          description: >-
            Limit results to stops with one of the specified categories. To
            specify multiple values, repeat the parameter (e.g.
            `?stop_categories=FUEL&stop_categories=REST`).
        - name: min_stop_duration_seconds
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: >-
              Return only stops whose duration is at least this many seconds.
              Long stops (no confirmed end) always pass this filter.
            title: Min Stop Duration Seconds
          description: >-
            Return only stops whose duration is at least this many seconds. Long
            stops (no confirmed end) always pass this filter.
        - name: max_stop_duration_seconds
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            description: >-
              Return only stops whose duration is at most this many seconds.
              Long stops (no confirmed end) are excluded when this filter is
              active.
            title: Max Stop Duration Seconds
          description: >-
            Return only stops whose duration is at most this many seconds. Long
            stops (no confirmed end) are excluded when this filter is active.
        - 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_VehicleStopRead_'
        '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_VehicleStopRead_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/VehicleStopRead'
          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[VehicleStopRead]
    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
    VehicleStopRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        vehicle_id:
          type: string
          format: uuid
          title: Vehicle Id
        connection_id:
          type: string
          format: uuid
          title: Connection Id
        place_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Place Id
        start_date:
          type: string
          format: date-time
          title: Start Date
        end_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Date
        stop_definition:
          type: string
          title: Stop Definition
        stop_type:
          type: string
          title: Stop Type
        stop_category:
          type: string
          title: Stop Category
        is_long_stop:
          type: boolean
          title: Is Long Stop
        location:
          anyOf:
            - $ref: '#/components/schemas/Point'
            - additionalProperties: true
              type: object
            - {}
            - type: 'null'
          title: Location
        h3_index_11:
          anyOf:
            - type: integer
            - type: 'null'
          title: H3 Index 11
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        fleet_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Fleet Id
        fleet_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Fleet Ref
      type: object
      required:
        - id
        - vehicle_id
        - connection_id
        - start_date
        - stop_definition
        - stop_type
        - stop_category
        - is_long_stop
        - created_at
        - updated_at
      title: VehicleStopRead
      description: API read model for a detected vehicle stop.
    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
    Point:
      properties:
        bbox:
          anyOf:
            - prefixItems:
                - type: number
                - type: number
                - type: number
                - type: number
              type: array
              maxItems: 4
              minItems: 4
            - prefixItems:
                - type: number
                - type: number
                - type: number
                - type: number
                - type: number
                - type: number
              type: array
              maxItems: 6
              minItems: 6
            - type: 'null'
          title: Bbox
        type:
          type: string
          const: Point
          title: Type
        coordinates:
          anyOf:
            - $ref: '#/components/schemas/Position2D'
            - $ref: '#/components/schemas/Position3D'
          title: Coordinates
      type: object
      required:
        - type
        - coordinates
      title: Point
      description: Point Model
    Position2D:
      prefixItems:
        - type: number
          title: Longitude
        - type: number
          title: Latitude
      type: array
      maxItems: 2
      minItems: 2
    Position3D:
      prefixItems:
        - type: number
          title: Longitude
        - type: number
          title: Latitude
        - type: number
          title: Altitude
      type: array
      maxItems: 3
      minItems: 3
  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

````