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

# Get IFTA Summary

> Get distance driven per IFTA jurisdiction for the requested months.

*Note:* data may change for a few days after the month. We will continue to update those reports to ensure you get accurate results.


## OpenAPI

````yaml GET /ifta/summary
openapi: 3.1.0
info:
  title: Terminal Telematics API
  description: >-
    Terminal is a unified API that makes it easy to integrate with the leading
    telematics service providers.
  version: '0.0'
  contact:
    name: Terminal
    email: connect@withterminal.com
    url: https://www.withterminal.com
servers:
  - url: https://api.withterminal.com/tsp/v1
    description: Production
  - url: https://api.sandbox.withterminal.com/tsp/v1
    description: Sandbox
security:
  - Authorization: []
tags:
  - name: Authentication
  - name: Connections
  - name: Data Management
  - name: Drivers
  - name: Groups
  - name: Hours of Service
  - name: IFTA
  - name: Issues
  - name: Link
  - name: Providers
  - name: Safety
  - name: Trailers
  - name: Vehicles
  - name: Vehicle Utilization
  - name: Webhook Events
paths:
  /ifta/summary:
    parameters: []
    get:
      tags:
        - IFTA
      summary: Get IFTA Summary
      description: >-
        Get distance driven per IFTA jurisdiction for the requested months.


        _Note:_ data may change for a few days after the month. We will continue
        to update those reports to ensure you get accurate results.
      operationId: getIFTASummary
      parameters:
        - $ref: '#/components/parameters/Cursor'
        - schema:
            type: string
            enum:
              - vehicle
          in: query
          name: expand
          description: Expand resources in the returned response
        - $ref: '#/components/parameters/ConnectionToken'
        - $ref: '#/components/parameters/Raw'
        - schema:
            $ref: '#/components/schemas/ISOMonth'
          in: query
          name: startMonth
          description: First month to include, inclusive.
          required: true
        - schema:
            $ref: '#/components/schemas/ISOMonth'
          in: query
          name: endMonth
          description: Last month to include, inclusive.
          required: true
        - schema:
            type: string
            enum:
              - jurisdiction
              - vehicle
              - vehicle,jurisdiction
              - vehicle,jurisdiction,month
            default: vehicle,jurisdiction
          in: query
          name: groupBy
          description: >-
            How to total distance across the requested months. The default,
            `vehicle,jurisdiction`, returns one row per vehicle and
            jurisdiction, summed across every month from `startMonth` to
            `endMonth`. Use `vehicle,jurisdiction,month` to get one row per
            month.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/IFTASummary'
                  next:
                    $ref: '#/components/schemas/PaginationCursor'
                required:
                  - results
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '410':
          $ref: '#/components/responses/GoneError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '504':
          $ref: '#/components/responses/GatewayTimeoutError'
components:
  parameters:
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        format: cursor
        pattern: ^[A-Za-z0-9+/=_-]+$
        example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
      description: Pagination cursor to start requests from
    ConnectionToken:
      name: Connection-Token
      in: header
      required: true
      schema:
        type: string
        example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4
        pattern: ^con_tkn_\S+$
      description: >-
        The token returned when a user authenticated their account. This
        authorizes access to a specific account.
    Raw:
      name: raw
      in: query
      required: false
      schema:
        type: boolean
      description: >-
        Include raw responses used to normalize model. Used for debugging or
        accessing unique properties that are not unified.
  schemas:
    ISOMonth:
      title: ISOMonth
      type: string
      pattern: ^(\d{4})-(0[1-9]|1[0-2])$
      example: 2021-01
      description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) month'
    IFTASummary:
      title: IFTA Summary
      x-model-category: time-series
      x-read-permission: ifta:read
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderCode'
        vehicle:
          $ref: '#/components/schemas/ExpandableVehicle'
          description: >-
            The vehicle this IFTA summary is for. Only returned when `groupBy`
            includes `vehicle`.
        jurisdiction:
          description: >-
            The IFTA jurisdiction: a US state, US territory, DC, or Canadian
            province or territory. `null` when the provider reports a
            jurisdiction outside this list, such as Mexico, or reports no
            recognizable jurisdiction. Only returned when `groupBy` includes
            `jurisdiction`.
          example: TN
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/State'
        distance:
          $ref: '#/components/schemas/DistanceInKilometers'
          description: Total distance driven for this group.
        month:
          $ref: '#/components/schemas/ISOMonth'
          description: >-
            The calendar month of the report, as defined by the provider's IFTA
            report. Only returned when `groupBy` includes `month`.
        raw:
          $ref: '#/components/schemas/RawDataList'
      required:
        - provider
        - distance
      x-description: >-
        Distance driven, totaled by vehicle, jurisdiction, and month according
        to the `groupBy` you request. Covers full calendar months only.
    PaginationCursor:
      title: Pagination Cursor
      type: string
      example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
      description: Cursor used for pagination.
      format: cursor
      pattern: ^[A-Za-z0-9+/=_-]+$
    ProviderCode:
      type: string
      example: geotab
      description: >-
        Every provider has a unique code to identify it across Terminal's
        system. You can find each provider's code under [provider
        details](/providers).
    ExpandableVehicle:
      example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
      oneOf:
        - $ref: '#/components/schemas/VehicleId'
        - $ref: '#/components/schemas/ExpandedVehicle'
    State:
      title: State
      type: string
      enum:
        - AL
        - AK
        - AS
        - AZ
        - AR
        - CA
        - CO
        - CT
        - DE
        - FL
        - GA
        - GU
        - HI
        - ID
        - IL
        - IN
        - IA
        - KS
        - KY
        - LA
        - ME
        - MD
        - MA
        - MI
        - MN
        - MP
        - MS
        - MO
        - MT
        - NE
        - NV
        - NH
        - NJ
        - NM
        - NY
        - NC
        - ND
        - OH
        - OK
        - OR
        - PA
        - PR
        - RI
        - SC
        - SD
        - TN
        - TX
        - UT
        - VT
        - VA
        - WA
        - WV
        - WI
        - WY
        - VI
        - AB
        - BC
        - MB
        - NB
        - NL
        - NS
        - 'ON'
        - PE
        - QC
        - SK
        - NT
        - NU
        - UM
        - YT
        - DC
      example: TN
      description: US State or Canadian Province
    DistanceInKilometers:
      title: Distance In Kilometers
      type: number
      format: double
      description: Distance in kilometers
      example: 100.25
    RawDataList:
      title: RawDataList
      type: array
      example: []
      items:
        $ref: '#/components/schemas/RawData'
    ErrorPathDetail:
      title: ErrorPathDetail
      type: object
      properties:
        message:
          type: string
          example: '''vehicleId'' property must be a valid ulid'
        path:
          type: string
          example: '{requestQuery}.vehicleId'
        suggestion:
          type: string
          example: Please ensure you submit a valid 'vehicleId' property
        context:
          type: object
      required:
        - message
        - path
    VehicleId:
      title: VehicleId
      description: Unique identifier for the vehicle in Terminal.
      type: string
      format: ulid
      pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$
      example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
    ExpandedVehicle:
      title: Expanded Vehicle
      type: object
      additionalProperties: false
      properties:
        id:
          $ref: '#/components/schemas/VehicleId'
        sourceId:
          $ref: '#/components/schemas/SourceId'
        provider:
          $ref: '#/components/schemas/ProviderCode'
        status:
          type: string
          enum:
            - active
            - inactive
          example: active
          description: The status in the providers system
        vin:
          title: VIN
          type: string
          example: 1HGCM82633A004352
        name:
          type: string
          example: Big Red
        make:
          type: string
          example: Peterbilt
        model:
          type: string
          example: Model 579
        year:
          type: integer
          example: 2016
        groups:
          type: array
          description: The groups the vehicle belongs to.
          items:
            $ref: '#/components/schemas/GroupId'
        devices:
          type: array
          description: The devices installed in the vehicle.
          items:
            $ref: '#/components/schemas/DeviceId'
        licensePlate:
          type: object
          properties:
            state:
              $ref: '#/components/schemas/State'
            number:
              type: string
              example: ABC-1234
        fuelType:
          enum:
            - gasoline
            - diesel
            - propane
            - electric
            - hybrid_gasoline
            - hybrid_diesel
            - biodiesel
            - compressed_natural_gas
            - liquefied_natural_gas
            - ethanol
            - hydrogen
            - plug_in_hybrid
          example: diesel
        fuelEfficiency:
          type: number
          deprecated: true
          description: >-
            This field will be removed in the future as is not commonly
            available from providers.
          example: 27.4
        fuelTankCapacity:
          description: Maximum amount of fuel vehicle can hold in liters.
          title: Volume In Liters
          type: number
          example: 95.33
        createdAt:
          $ref: '#/components/schemas/SourceCreatedAt'
        updatedAt:
          $ref: '#/components/schemas/SourceUpdatedAt'
        metadata:
          $ref: '#/components/schemas/CoreEntityMetadata'
        raw:
          $ref: '#/components/schemas/RawDataList'
      required:
        - id
        - sourceId
        - provider
        - status
        - metadata
      x-description: The model representing a vehicle in Terminal.
    RawData:
      title: RawData
      type: object
      properties:
        provider:
          type: string
        schema:
          type: string
        extractedAt:
          type: string
        data:
          type: object
      required:
        - provider
        - schema
        - extractedAt
        - data
    SourceId:
      title: SourceId
      type: string
      example: '123456789'
      description: The ID used to represent the entity in the source system.
    GroupId:
      title: GroupId
      type: string
      format: ulid
      example: group_01D8ZQFGHVJ858NBF2Q7DV9MNC
    DeviceId:
      title: DeviceId
      type: string
      format: ulid
      example: dvc_61D9ZWFGHVJ858NBF2Q7DV9MNC
    SourceCreatedAt:
      title: SourceCreatedAt
      type: string
      format: date-time
      description: >-
        The date and time the record was created in the provider's system. This
        timestamp comes directly from the source system and represents when the
        data was originally created there. Note: not all providers expose this.
    SourceUpdatedAt:
      title: SourceUpdatedAt
      type: string
      format: date-time
      description: >-
        The date and time the record was updated in the provider's system. This
        timestamp comes directly from the source system and represents when the
        data was last updated there. Note: not all providers expose this.
    CoreEntityMetadata:
      title: CoreEntityMetadata
      type: object
      description: Internal metadata about the record.
      required:
        - addedAt
        - modifiedAt
      properties:
        addedAt:
          $ref: '#/components/schemas/AddedAt'
        modifiedAt:
          $ref: '#/components/schemas/ModifiedAt'
        deletedAt:
          $ref: '#/components/schemas/DeletedAt'
        visibility:
          type: string
          enum:
            - visible
            - hidden_by_exclude_list
            - hidden_by_include_list
            - hidden_by_status
            - deleted
          example: visible
          description: >-
            Visibility status of a resource. Read more about hidden records
            [here](https://docs.withterminal.com/guides/vehicle-driver-filtering).
    AddedAt:
      title: AddedAt
      type: string
      format: date-time
      description: >-
        The date and time the record was ingested into Terminal. Note: this is
        not the date and time the record was created in the provider's system.
    ModifiedAt:
      title: ModifiedAt
      type: string
      format: date-time
      description: >-
        The date and time the record was last updated in Terminal. Note: this is
        not the date and time the record was updated in the provider's system.
    DeletedAt:
      title: DeletedAt
      type: string
      format: date-time
      description: >-
        The date and time the record was deleted from Terminal. Note: this is
        not the date and time the record was deleted in the provider's system.
  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - bad_request
              message:
                type: string
                example: Invalid request body
              detail:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorPathDetail'
            required:
              - code
              - message
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - unauthorized
              message:
                type: string
                example: Unauthorized Request
              detail:
                type: string
                example: Please ensure you have a valid API key
            required:
              - code
              - message
    ForbiddenError:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - forbidden
              message:
                type: string
                example: Forbidden Request
              detail:
                type: string
                example: >-
                  Please ensure the connection token matches the resource you
                  are attempting to access.
            required:
              - code
              - message
    GoneError:
      description: Gone
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - gone
                  - connection_deleted
                example: connection_deleted
              message:
                type: string
                example: Connection has been deleted and cannot be used
            required:
              - code
              - message
    TooManyRequestsError:
      description: Too Many Requests
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
            properties:
              code:
                enum:
                  - too_many_requests
              retryAfter:
                description: The number of seconds to wait before retrying the request
                type: integer
                example: 60
              message:
                type: string
                example: Too Many Requests
              detail:
                type: string
                example: You have exceeded your rate limit. Please try again later.
            required:
              - code
              - message
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - internal_server_error
              message:
                type: string
                example: Internal Server Error
              detail:
                type: string
                example: Something went wrong
            required:
              - code
              - message
    GatewayTimeoutError:
      description: Gateway Timeout Error
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                enum:
                  - gateway_timeout
                  - provider_timeout
                description: >-
                  `provider_timeout` means the telematics provider did not
                  respond in time, or responded too slowly to finish the request
                  (for example, while paginating). Retry later or narrow the
                  request, for example with a shorter time range or smaller
                  `limit`. `gateway_timeout` means Terminal could not finish the
                  request in time for another reason.
              message:
                type: string
                example: Gateway Timeout
            required:
              - code
              - message
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.