> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jitra.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Read Object Positions

> Returns historical positions for one Object within a required date or datetime range.



## OpenAPI

````yaml openapi.json GET /objects/{id}/positions
openapi: 3.0.3
info:
  title: Jitra Public API
  version: 1.0.0
  description: >-
    Read-only integration API for organization fleet data: tracked objects, live
    and historical positions, geofences, routes, and sites.


    ## Authentication

    All endpoints except the health ping require an organization API key. Send
    it with either:

    - `x-api-key: <api_key>`

    - `Authorization: Bearer <api_key>`


    Missing, invalid, or expired keys return HTTP `401`.


    ## Versioning

    URI versioning is enabled. The current version is `v1`. The global prefix is
    `public`, so every resource lives under `/public/v1`.


    ## Rate limits

    Requests are throttled per organization:

    - Window: 10 seconds

    - Limit: 10 requests per window


    Exceeding the throttle returns HTTP `429`.


    Position endpoints also enforce a daily per-object API usage quota from the
    organization subscription (`INTEGRATION_API_DAILY`). When the quota is
    exhausted the API returns HTTP `400` with `errorCode` `PUBLIC.400_005`.
    Inactive or suspended subscriptions return HTTP `403` with `errorCode`
    `SUBSCRIPTION.403_002`.


    ## Response envelope

    Successful JSON responses use:

    ```json

    { "statusCode": 200, "result": {} }

    ```

    `result` is an object or an array depending on the endpoint.


    Error responses use:

    ```json

    {
      "statusCode": 400,
      "errorCode": "PUBLIC.400_001",
      "message": "Validation error message",
      "timestamp": "2026-05-17T01:00:00.000Z"
    }

    ```


    Datetime values are ISO 8601 UTC timestamps.
  contact:
    name: Jitra
    url: https://jitra.app
servers:
  - url: https://api.jitra.app/public/v1
    description: Production
  - url: '{scheme}://{host}:{port}/public/v1'
    description: Local or custom environment
    variables:
      scheme:
        default: http
        enum:
          - http
          - https
      host:
        default: localhost
      port:
        default: '3000'
        description: Value of PUBLIC_APP_PORT
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Health
    description: Service availability check. Does not require an API key.
  - name: Objects
    description: >-
      Tracked vehicles/assets (objects) belonging to the authenticated
      organization, including catalog, detail snapshot, and historical
      positions.
  - name: Positions
    description: Latest realtime GPS positions for one or more objects.
  - name: Geofences
    description: Geographic zones defined as polygons for the authenticated organization.
  - name: Routes
    description: >-
      Planned routes with waypoints and geometry for the authenticated
      organization.
  - name: Sites
    description: Point-of-interest sites with radius for the authenticated organization.
paths:
  /objects/{id}/positions:
    get:
      tags:
        - Objects
      summary: Get object position history
      description: >-
        Returns historical GPS points for one object between `from` and `to`.


        Use this for trip playback, breadcrumb maps, and historical movement
        analytics. An empty `result` array means no points exist in that range.


        This endpoint checks subscription status and the daily per-object API
        usage quota before querying history.
      operationId: getObjectPositions
      parameters:
        - $ref: '#/components/parameters/ObjectId'
        - name: from
          in: query
          required: true
          description: >-
            Start of the history range (date or ISO 8601 datetime). Missing
            value returns `PUBLIC.400_001`.
          schema:
            type: string
            format: date-time
            example: '2026-05-16T00:00:00.000Z'
        - name: to
          in: query
          required: true
          description: >-
            End of the history range (date or ISO 8601 datetime). Missing value
            returns `PUBLIC.400_002`.
          schema:
            type: string
            format: date-time
            example: '2026-05-17T00:00:00.000Z'
        - name: limit
          in: query
          required: false
          description: Maximum number of position rows to return.
          schema:
            type: integer
            minimum: 1
            example: 100
      responses:
        '200':
          description: Historical positions for the object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectPositionListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/SubscriptionForbidden'
        '404':
          $ref: '#/components/responses/ObjectNotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    ObjectId:
      name: id
      in: path
      required: true
      description: Numeric object ID that belongs to the authenticated organization.
      schema:
        type: integer
        example: 101
  schemas:
    ObjectPositionListResponse:
      type: object
      required:
        - statusCode
        - result
      properties:
        statusCode:
          type: integer
          example: 200
        result:
          type: array
          items:
            $ref: '#/components/schemas/ObjectPublicPosition'
    ObjectPublicPosition:
      type: object
      description: >-
        GPS position snapshot for an object. Used by both latest-position and
        history endpoints.
      properties:
        id:
          type: integer
          description: Object ID.
          example: 101
        ident:
          type: string
          description: Unique object identifier.
          example: B-1234-XYZ
        name:
          type: string
          description: Object display name.
          example: Truck 01
        latitude:
          type: number
          description: Latitude at this point.
          example: -6.2
        longitude:
          type: number
          description: Longitude at this point.
          example: 106.8
        altitude:
          type: number
          description: Altitude in meters.
          example: 15
        angle:
          type: number
          description: Heading angle in degrees.
          example: 230
        speed:
          type: number
          description: Speed at this point.
          example: 42
        time_server:
          type: string
          format: date-time
          description: Server timestamp for this point.
        time_device:
          type: string
          format: date-time
          description: Device timestamp for this point.
        engine_hours:
          type: number
          description: Engine-hours value associated with the object.
        odometer:
          type: number
          description: Odometer value associated with the object.
        mileage:
          type: number
          description: Mileage value associated with the object.
        address:
          type: string
          description: >-
            Address at this point, falling back to the object's last known
            address.
    ErrorResponse:
      type: object
      description: Standard public API error envelope.
      required:
        - statusCode
        - errorCode
        - message
        - timestamp
      properties:
        statusCode:
          type: integer
          description: HTTP status code.
          example: 400
        errorCode:
          type: string
          description: >-
            Machine-readable error code. Public-specific codes use the
            `PUBLIC.*` prefix. Uncoded HTTP exceptions default to `ERR999`.
          example: PUBLIC.400_001
        message:
          type: string
          description: Localized human-readable message.
          example: Enter From Time, because is required.
        timestamp:
          type: string
          format: date-time
          description: Error time in ISO 8601 UTC.
  responses:
    BadRequest:
      description: >-
        Validation failed, request IDs are invalid, or the daily per-object API
        usage quota was reached. Refer to the endpoint parameter descriptions
        for PUBLIC.400_001 through PUBLIC.400_005.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 400
            errorCode: PUBLIC.400_001
            message: Validation error message
            timestamp: '2026-05-17T01:00:00.000Z'
    Unauthorized:
      description: API key is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 401
            errorCode: ERR999
            message: Unauthorized
            timestamp: '2026-05-17T01:00:00.000Z'
    SubscriptionForbidden:
      description: Organization subscription is inactive or suspended.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 403
            errorCode: SUBSCRIPTION.403_002
            message: Your subscription is suspended. Please contact your Admin.
            timestamp: '2026-05-17T01:00:00.000Z'
    ObjectNotFound:
      description: The object ID does not exist in the authenticated organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 404
            errorCode: PUBLIC.404_001
            message: Object not found.
            timestamp: '2026-05-17T01:00:00.000Z'
    TooManyRequests:
      description: Organization exceeded 10 requests in a 10-second window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 429
            errorCode: ERR999
            message: 'ThrottlerException: Too Many Requests'
            timestamp: '2026-05-17T01:00:00.000Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Organization API key issued from Jitra (Organization → API Key).
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Same organization API key sent as `Authorization: Bearer <api_key>`.'

````