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

# Lookup rate history

> Look up the rate history for a lane. This is considered a mutation because it is a
metered operation and calls are recorded for possible billing purposes.

See [the usage guide](/rates/rate-lookup).



## OpenAPI

````yaml /openapi.yml post /rates/history
openapi: 3.1.0
info:
  title: Cargado API
  version: 1.0.0
  description: Cargado's API
  termsOfService: https://cargado.com/terms/
  contact:
    email: dev-support@cargado.com
servers:
  - url: https://api.cargado.com
    description: The production Cargado API server
security: []
tags:
  - name: Border Crossings
  - name: Loads
  - name: Rates
  - name: CarrierRelationship
  - name: User
  - name: Team
  - name: Webhooks
  - name: Bids
paths:
  /rates/history:
    post:
      tags:
        - Rates
      summary: Lookup rate history
      description: >-
        Look up the rate history for a lane. This is considered a mutation
        because it is a

        metered operation and calls are recorded for possible billing purposes.


        See [the usage guide](/rates/rate-lookup).
      operationId: RateHistory
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateHistoryInput'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateHistoryOutput'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody'
              examples:
                Example 1:
                  value:
                    message: Unauthorized
      security:
        - apiKey: []
components:
  schemas:
    RateHistoryInput:
      description: See [the Rate Lookup guide](/rates/rate-lookup) for more information.
      properties:
        requests:
          items:
            $ref: '#/components/schemas/RateHistoryRequest'
          type: array
          description: A list of load descriptions to get rate history for.
          minItems: 1
          maxItems: 16
      required:
        - requests
      type: object
      additionalProperties: true
    RateHistoryOutput:
      properties:
        results:
          items:
            anyOf:
              - $ref: '#/components/schemas/RateHistoryLookup'
              - $ref: '#/components/schemas/RateHistoryError'
          type: array
          description: >-
            The result for each input request; the request and result arrays are
            the same size and their elements map 1:1.

            Each result is either a successful lookup or an error; each request
            succeeds or fails independently.


            See [the Rate Lookup guide](/rates/rate-lookup) for more
            information.
      required:
        - results
      type: object
      additionalProperties: true
    ErrorResponseBody:
      properties:
        code:
          type: string
        name:
          type: string
        message:
          type: string
        userReadableMessage:
          type: string
        details: {}
        fingerprint:
          type: string
      type: object
      additionalProperties: true
    RateHistoryRequest:
      properties:
        stops:
          items:
            $ref: '#/components/schemas/StopInput'
          type: array
          description: >-
            The list of stops for the load. The first stop is the origin and the
            last stop is the destination.

            The first stop must be a pickup and the last must be a delivery.

            For loads crossing the United States-Mexico border, you may include
            a border crossing stop to specify the port.

            If omitted (or if the border crossing stop has no
            `usMxBorderCrossing` value), Cargado will automatically select the
            recommended crossing.

            For loads that do not cross the border, a border crossing stop must
            not be included.
          minItems: 2
          maxItems: 64
        trailerRequirements:
          properties:
            allowedTypes:
              items:
                $ref: '#/components/schemas/TrailerType'
              type: array
              description: |-
                Which types of trailers are allowed for the load.
                Examples: ["DRY_VAN"], ["DRY_VAN", "REEFER"]
              examples:
                - - DRY_VAN
          required:
            - allowedTypes
          type: object
          description: The trailer requirements for the load.
        routeMiles:
          type: number
          format: double
      required:
        - stops
        - trailerRequirements
      type: object
      additionalProperties: true
    RateHistoryLookup:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DATA
        id:
          type: string
        rateHistory:
          $ref: '#/components/schemas/RateHistory'
          description: The Rate History suggested by Cargado.
        alternateRateHistories:
          items:
            $ref: '#/components/schemas/RateHistory'
          type: array
          description: >-
            Alternate Rate Histories also calculated by Cargado, using different
            methodology. May be empty.
      required:
        - type
        - id
        - rateHistory
        - alternateRateHistories
      type: object
      additionalProperties: true
    RateHistoryError:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - ERROR
        code:
          $ref: '#/components/schemas/RateHistoryErrorCode'
        message:
          type: string
      required:
        - type
        - code
        - message
      type: object
      additionalProperties: true
    StopInput:
      anyOf:
        - $ref: '#/components/schemas/PickupStopInput'
        - $ref: '#/components/schemas/DeliveryStopInput'
        - $ref: '#/components/schemas/BorderCrossingStopInput'
    TrailerType:
      type: string
      enum:
        - DRY_VAN
        - DRY_VAN_DOUBLE
        - DRY_VAN_TRIPLE
        - DRY_VAN_MULTI_AXLE
        - REEFER
        - REEFER_DOUBLE
        - REEFER_MULTI_AXLE
        - HEATED
        - HEATED_MULTI_AXLE
        - FLATBED
        - FLATBED_DOUBLE
        - FLATBED_MULTI_AXLE
        - STEPDECK
        - DOUBLE_DROP
        - RGN
        - CONESTOGA
        - STEPDECK_CONESTOGA
        - DOUBLE_DROP_CONESTOGA
        - STRAIGHT_TRUCK_DRY
        - STRAIGHT_TRUCK_REEFER
        - TORTON
        - RABON
        - HALF_TON
        - ONE_TON
        - ONE_AND_HALF_TON
        - THREE_AND_HALF_TON
        - FOUR_AND_HALF_TON
    RateHistory:
      description: The history of rates for a specific market to market lane.
      properties:
        dayRange:
          $ref: '#/components/schemas/DayRange'
          description: The date range that this Rate History covers.
        pricingLane:
          $ref: '#/components/schemas/PricingLane'
        currencyCode:
          $ref: '#/components/schemas/CurrencyCode'
        latestSuggestedRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description: >-
            Most recent rate, calculated using the suggested formula: either
            per-mile (multiplied by distance) or all-in, depending on our
            analysis.
        suggestedRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of suggested rates, in ascending order by date.
        latestPerMileRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description: Most recent rate, charged per mile.
        perMileRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of per-mile rates, in ascending order by date.
        latestAllInRate:
          $ref: '#/components/schemas/RateHistoryTimeframe'
          description: >-
            Most recent rate, calculated from all-in rates between the origin
            and destination pricing areas, ignoring route mileage.
        allInRates:
          items:
            $ref: '#/components/schemas/RateHistoryTimeframe'
          type: array
          description: History of all-in rates, in ascending order by date.
        routeMiles:
          type: number
          format: double
          description: >-
            Distance in miles between the specified pickup and delivery.


            If `routeMiles` was specified in the input, this field has the same
            value. Otherwise, we calculate it.
        routeMilesWithDeadhead:
          type: number
          format: double
          description: >-
            The route mileage, plus estimated deadhead from the origin Market
            centroid to the pickup, and from the delivery to the destination
            Market centroid.


            If `routeMiles` was specified in the input, this field has the same
            value. Otherwise, we calculate it.
      required:
        - dayRange
        - pricingLane
        - currencyCode
        - latestSuggestedRate
        - suggestedRates
        - perMileRates
        - latestAllInRate
        - allInRates
        - routeMiles
        - routeMilesWithDeadhead
      type: object
      additionalProperties: true
    RateHistoryErrorCode:
      type: string
      enum:
        - USER_INPUT_ERROR
        - SERVER_ERROR
        - RATE_HISTORY_NOT_FOUND
        - GEOCODING_FAILED
        - CALCULATING_ROUTE_DISTANCE_FAILED
        - USAGE_EXHAUSTED
    PickupStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - PICKUP
        placeDetails:
          $ref: '#/components/schemas/PlaceDetailsInput'
          description: The location of the stop.
      required:
        - type
        - placeDetails
      type: object
      additionalProperties: true
    DeliveryStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - DELIVERY
        placeDetails:
          $ref: '#/components/schemas/PlaceDetailsInput'
          description: The location of the stop.
      required:
        - type
        - placeDetails
      type: object
      additionalProperties: true
    BorderCrossingStopInput:
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - BORDER_CROSSING
        usMxBorderCrossing:
          $ref: '#/components/schemas/UsMxBorderCrossing'
          description: >-
            The border crossing port between the United States and Mexico.

            If omitted, Cargado will automatically select the recommended
            crossing for the route.
      required:
        - type
      type: object
      additionalProperties: true
    DayRange:
      description: Range between two dates.
      properties:
        start:
          $ref: '#/components/schemas/Day'
          description: Start date in ISO 8601 format.
        end:
          $ref: '#/components/schemas/Day'
          description: End date in ISO 8601 format.
      required:
        - start
        - end
      type: object
      additionalProperties: true
    PricingLane:
      description: >-
        A description of the unique features used to aggregate prices
        internally.
      properties:
        origin:
          $ref: '#/components/schemas/PricingArea'
        destination:
          $ref: '#/components/schemas/PricingArea'
        trailerCategory:
          $ref: '#/components/schemas/TrailerCategory'
        usMxBorderCrossing:
          $ref: '#/components/schemas/UsMxBorderCrossing'
      required:
        - origin
        - destination
        - trailerCategory
      type: object
      additionalProperties: true
    CurrencyCode:
      type: string
      enum:
        - USD
        - MXN
        - CAD
      description: Supported currency codes for monetary values.
    RateHistoryTimeframe:
      description: The distribution of rates, including fuel, for a given timeframe.
      properties:
        dayRange:
          $ref: '#/components/schemas/DayRange'
          description: The date range that this data point covers.
        amountDistribution:
          $ref: '#/components/schemas/Distribution'
          description: >-
            The distribution in "amounts" (integers of the base unit of the
            chosen currency).


            - CAD: cents

            - USD: cents

            - MXN: centavos
        marginOfError:
          type: number
          format: double
          description: >-
            The margin of error is the maximum expected difference between the
            true population median and our observed median.

            It is calculated, per lane, based on the number of bids and their
            variability, from at least 5 unique carriers.


            Its unit is "amount" (integers of the base unit of the chosen
            currency); see the `amountDistribution` field.
        relativeMarginOfError:
          type: number
          format: double
          description: >-
            The margin of error divided by the rate p50 to yield a percentage
            rate deviation.
        confidenceScore:
          type: number
          format: double
          description: >-
            A score indicating overall confidence in the rates, derived from the
            relative margin of error. This is expressed as an

            integer between 1 and 100, where 1 is the lowest confidence and 100
            is the highest.
        confidence:
          $ref: '#/components/schemas/Confidence'
          description: |-
            The simplest confidence metric. Values:

            - `LOWER`: confidence score 1-33
            - `MEDIUM`: confidence score 34-66
            - `STRONG`: confidence score 67-100
      required:
        - dayRange
        - amountDistribution
      type: object
      additionalProperties: true
    PlaceDetailsInput:
      properties:
        place:
          $ref: '#/components/schemas/Place'
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          description: >-
            The GPS coordinates of the location. If omitted, Cargado will
            determine the coordinates to use via geocoding.
      type: object
      additionalProperties: true
    UsMxBorderCrossing:
      type: string
      enum:
        - LAREDO_INTL_BRIDGE
        - LAREDO_COLUMBIA
        - BROWNSVILLE
        - CALEXICO_EAST
        - DEL_RIO
        - DOUGLAS
        - EAGLE_PASS
        - EL_PASO
        - HIDALGO
        - NOGALES
        - OTAY_MESA
        - SAN_LUIS
        - TECATE
    Day:
      type: string
      format: date
      description: A date in ISO 8601 format (YYYY-MM-DD).
      examples:
        - '2025-01-01T00:00:00.000Z'
    PricingArea:
      anyOf:
        - $ref: '#/components/schemas/MarketPricingArea'
        - $ref: '#/components/schemas/ExtendedMarketPricingArea'
      description: >-
        An area in which freight prices are aggregated for analysis at both
        origin and destination.

        Extended Market-based Pricing Areas are larger and are used when
        insufficient data is available at the Market level.
    TrailerCategory:
      type: string
      enum:
        - DRY_VAN
        - OPEN_DECK
        - REEFER
        - STRAIGHT_TRUCK
    Distribution:
      properties:
        p25:
          type: number
          format: double
          description: The 25th percentile of the distribution.
        p50:
          type: number
          format: double
          description: The 50th percentile of the distribution.
        p75:
          type: number
          format: double
          description: The 75th percentile of the distribution.
      required:
        - p25
        - p50
        - p75
      type: object
      additionalProperties: true
    Confidence:
      type: string
      enum:
        - STRONG
        - MEDIUM
        - LOWER
      description: Level of statistical confidence in a piece of data.
    Place:
      anyOf:
        - $ref: '#/components/schemas/AddressString'
        - $ref: '#/components/schemas/Address'
        - $ref: '#/components/schemas/PostalCode'
        - $ref: '#/components/schemas/City'
    Coordinates:
      description: GPS coordinates for a geographic location.
      properties:
        latitude:
          type: number
          format: double
          description: The latitude of the place.
          minimum: -90
          maximum: 90
          examples:
            - 49.280455
        longitude:
          type: number
          format: double
          description: The longitude of the place.
          minimum: -180
          maximum: 180
          examples:
            - -123.118842
      required:
        - latitude
        - longitude
      type: object
      additionalProperties: true
    MarketPricingArea:
      description: A Pricing Area covering a single Market.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - MARKET
        market:
          $ref: '#/components/schemas/Market'
      required:
        - type
        - market
      type: object
      additionalProperties: true
    ExtendedMarketPricingArea:
      description: >-
        A Pricing Area covering a single Extended Market, which is composed of
        contiguous Markets.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - EXTENDED_MARKET
        extendedMarket:
          $ref: '#/components/schemas/ExtendedMarket'
      required:
        - type
        - extendedMarket
      type: object
      additionalProperties: true
    AddressString:
      properties:
        address:
          type: string
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS_STRING
      required:
        - address
        - type
      type: object
      description: >-
        The place as a formatted string. Should be at the level of an address,
        postal code, city, or neighborhood.
    Address:
      properties:
        country:
          $ref: '#/components/schemas/CountryCode'
        state:
          $ref: '#/components/schemas/StateCode'
        city:
          type: string
        postalCode:
          type: string
        streetTwo:
          type: string
        street:
          type: string
        type:
          type:
            - string
            - 'null'
          enum:
            - ADDRESS
      required:
        - country
        - state
        - city
        - postalCode
        - street
        - type
      type: object
      description: The full address of the place as structured data.
    PostalCode:
      description: >-
        A postal code in country-specific format (called a ZIP code in the
        United States).
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - POSTAL_CODE
        postalCode:
          type: string
        country:
          $ref: '#/components/schemas/CountryCode'
      required:
        - type
        - postalCode
        - country
      type: object
      additionalProperties: true
    City:
      description: >-
        A city or neighborhood. You may use the name of the neighborhood as the
        value of the `city` field.
      properties:
        type:
          type:
            - string
            - 'null'
          enum:
            - CITY
        city:
          type: string
        state:
          $ref: '#/components/schemas/StateCode'
        country:
          $ref: '#/components/schemas/CountryCode'
      required:
        - type
        - city
        - state
        - country
      type: object
      additionalProperties: true
    Market:
      description: A geographic area that Cargado has chosen to aggregate prices.
      properties:
        id:
          type: string
        name:
          type: string
          description: The display name of the market
        code:
          type: string
          description: >-
            The two letter country code and three letter market code of the
            market (e.g. US_SEA, MX_MTY).

            Based on the UN/LOCODE list.
        countryCode:
          $ref: '#/components/schemas/CountryCode'
          description: The country code of the market
        centroid:
          $ref: '#/components/schemas/Coordinates'
          description: |-
            The coordinates of the major city defining the market.
            Deadhead is calculated to/from here.
      required:
        - id
        - name
        - code
        - countryCode
        - centroid
      type: object
      additionalProperties: true
    ExtendedMarket:
      description: >-
        A set of contiguous Markets that Cargado has chosen to aggregate prices
        over a larger area.
      properties:
        id:
          type: string
        markets:
          items:
            $ref: '#/components/schemas/Market'
          type: array
          description: The set of constituent Markets that make up this ExtendedMarket.
        primaryMarket:
          $ref: '#/components/schemas/Market'
          description: >-
            The "primary" Market among the set of Markets, used for naming
            purposes.
      required:
        - id
        - markets
        - primaryMarket
      type: object
      additionalProperties: true
    CountryCode:
      type: string
      enum:
        - US
        - MX
        - CA
      description: The ISO 3166-1 alpha-2 country code of the place.
    StateCode:
      anyOf:
        - $ref: '#/components/schemas/StateCodeCA'
        - $ref: '#/components/schemas/StateCodeMX'
        - $ref: '#/components/schemas/StateCodeUS'
    StateCodeCA:
      type: string
      enum:
        - CA_AB
        - CA_BC
        - CA_MB
        - CA_NB
        - CA_NL
        - CA_NT
        - CA_NS
        - CA_NU
        - CA_ON
        - CA_PE
        - CA_QC
        - CA_SK
        - CA_YT
    StateCodeMX:
      type: string
      enum:
        - MX_AGU
        - MX_BCN
        - MX_BCS
        - MX_CAM
        - MX_CMX
        - MX_COA
        - MX_COL
        - MX_CHP
        - MX_CHH
        - MX_DUR
        - MX_GUA
        - MX_GRO
        - MX_HID
        - MX_JAL
        - MX_MEX
        - MX_MIC
        - MX_MOR
        - MX_NAY
        - MX_NLE
        - MX_OAX
        - MX_PUE
        - MX_QUE
        - MX_ROO
        - MX_SLP
        - MX_SIN
        - MX_SON
        - MX_TAB
        - MX_TAM
        - MX_TLA
        - MX_VER
        - MX_YUC
        - MX_ZAC
    StateCodeUS:
      type: string
      enum:
        - US_AK
        - US_AL
        - US_AZ
        - US_AR
        - US_CA
        - US_CO
        - US_CT
        - US_DE
        - US_FL
        - US_GA
        - US_HI
        - US_ID
        - US_IL
        - US_IN
        - US_IA
        - US_KS
        - US_KY
        - US_LA
        - US_ME
        - US_MD
        - US_MA
        - US_MI
        - US_MN
        - US_MS
        - US_MO
        - US_MT
        - US_NE
        - US_NV
        - US_NH
        - US_NJ
        - US_NM
        - US_NY
        - US_NC
        - US_ND
        - US_OH
        - US_OK
        - US_OR
        - US_PA
        - US_RI
        - US_SC
        - US_SD
        - US_TN
        - US_TX
        - US_UT
        - US_VT
        - US_VA
        - US_WA
        - US_WV
        - US_WI
        - US_WY
        - US_DC
        - US_AS
        - US_GU
        - US_MP
        - US_PR
        - US_UM
        - US_VI
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: api-key

````