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

# 🧪 Get Load

> Get detailed information about a specific TMS load.

<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/telematics/openapi.json get /v2/telematics/tms-loads/{load_id}
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/tms-loads/{load_id}:
    get:
      tags:
        - TMS
      summary: Get Load
      description: Get detailed information about a specific TMS load.
      operationId: get_load
      parameters:
        - name: load_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: The unique identifier of the load.
            title: Load Id
          description: The unique identifier of the load.
        - name: include_source_data
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include the raw data from the telematics provider. *Useful for
              auditing or accessing fields not normalized by Catena*
            default: false
            title: Include Source Data
          description: >-
            Include the raw data from the telematics provider. *Useful for
            auditing or accessing fields not normalized by Catena*
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoadRead'
        '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:
            - tms:read
components:
  schemas:
    LoadRead:
      properties:
        tms_account_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Tms Account Id
          description: The TMS account that owns this record's tms_connection_id.
        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 datetime 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.
        tms_connection_id:
          type: string
          format: uuid
          title: Tms Connection Id
          description: >-
            Unique identifier of the connection at Catena Telematics through
            which this record was ingested. A TMS connection represents a
            TmsAccount/TMS pairing. No foreign key: TmsConnection lives in
            telematics-integrations-service's own database, so this is a logical
            reference only.
        tms_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Tms Id
          description: >-
            Unique identifier of the TMS at Catena Telematics from which this
            record was ingested.
        tms_slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Tms Slug
          description: >-
            Human readable slug of the TMS at Catena Telematics from which this
            record was ingested.
        source_name:
          $ref: '#/components/schemas/TmsEnum'
          description: >-
            The underlying TMS platform that provided this data (e.g.,
            `tms_simulator`).
        source_data:
          additionalProperties: true
          type: object
          title: Source Data
          description: >-
            Raw source payload as ingested from the TMS. **Note: use it for
            audit/debugging.**
        source_id:
          type: string
          title: Source Id
          description: >-
            Unique identifier of the record in the TMS. **Note: we generate a
            deterministic composite key based on available fields if the TMS
            does not provide a unique ID.**
        source_data_hash:
          type: string
          maxLength: 64
          title: Source Data Hash
          description: >-
            SHA-256 hash of the source data payload. **Note: we use it
            internally for idempotence and deduplication.**
        occurred_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Occurred At
          description: >-
            Datetime of when the underlying event/observation occurred, as
            reported by the TMS, or the moment it was ingested by us if not
            available in the source data.
        extras:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extras
          description: >-
            Additional data available in the TMS that doesn't fit into the model
            (this field captures those extra attributes in a flexible way).
        execution_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Execution Id
          description: >-
            Unique identifier for the execution that ingested this record into
            Catena Telematics. **Note: useful for tracing.** Stamped by
            upsert_data() onto every record regardless of resource domain
            (functions/upsert/src/upsert.py), so this is populated the same way
            it is for TSP tables even though there is no TMS Schedule/Execution
            pipeline yet.
        schedule_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Schedule Id
          description: >-
            Unique identifier for schedule that triggered this record's
            execution. **Note: useful for tracing.**
        load_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Load Number
          description: Load/shipment number as provided by the TMS.
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: >-
            TMS-provided load status (e.g., 'booked', 'in_transit',
            'delivered'). Not normalized across TMS providers.
        source_customer_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Customer Id
          description: External source system customer identifier (from the TMS).
        customer_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Customer Id
          description: >-
            Internal customer identifier (Catena), deterministically derived
            from source_customer_id. No foreign key: no standalone Customer
            resource table exists yet.
        customer_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Customer Name
          description: Customer name as provided by the TMS.
        source_carrier_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Carrier Id
          description: External source system carrier identifier (from the TMS).
        carrier_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Carrier Id
          description: >-
            Internal carrier identifier (Catena), deterministically derived from
            source_carrier_id. No foreign key: no standalone Carrier resource
            table exists yet.
        carrier_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Carrier Name
          description: Carrier name as provided by the TMS.
        stops:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Stops
          description: >-
            Ordered pickup/delivery stops within the load (see LoadStop for the
            expected shape). Stored as JSON-safe dicts rather than
            list[LoadStop]: SQLAlchemy's JSONB column serializes with the stdlib
            json encoder, which can't handle Pydantic model instances or
            datetimes, so callers must pass `stop.model_dump(mode='json')`
            rather than a LoadStop instance (mirrors why
            functions/upsert/src/upsert.py's _normalize_jsonb_columns exists for
            the ingestion path).
      type: object
      required:
        - id
        - created_at
        - updated_at
        - tms_connection_id
        - source_name
        - source_id
        - source_data_hash
      title: LoadRead
      description: Load model for API responses.
    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
    TmsEnum:
      type: string
      enum:
        - tms_simulator
      title: TmsEnum
      description: >-
        Enum for TMS (Transportation Management System) providers.


        Kept separate from TspEnum: TMS providers are not TSPs, and conflating

        them would corrupt registry/validation paths that assume TspEnum
        membership.
    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
  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

````