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

# Snapshots Historical

> Delivers historical order book snapshots for specified Spot market trading pairs, including detailed bid and ask levels, volume, and order count per price level, along with timestamps to track market depth over time.

<Accordion title="BitMEX Volume Calculation Warning">
  <Warning>
    BitMEX’s `volume` field represents the **number of contracts traded**, not the volume in the base asset.

    To obtain the correct volume, users must adjust for **contract size** using the `underlyingToPositionMultiplier` from our [Reference endpoint](/http/md/spot-exchanges-reference).

    For details on this calculation and how to retrieve the correct values, see our [Changelog Update](/changelog/bitmex-volume-mapping).
  </Warning>
</Accordion>

<Warning>
  The maximum time range (difference between `startDate` and `endDate`) is **18 months**.
</Warning>

<Note>
  If the `startDate` and `endDate` query parameters are not provided, the API will return the data from the previous 24 hours.
</Note>


## OpenAPI

````yaml get /spot/order-book-snapshots/{instrument}
openapi: 3.1.0
info:
  title: market-api
  version: '2'
servers:
  - url: https://api.amberdata.com/markets
security:
  - ApiKeyAuth: []
paths:
  /spot/order-book-snapshots/{instrument}:
    get:
      summary: Snapshots Historical
      description: >-
        Delivers historical order book snapshots for specified Spot market
        trading pairs, including detailed bid and ask levels, volume, and order
        count per price level, along with timestamps to track market depth over
        time.
      operationId: spot-order-book-snapshots
      parameters:
        - name: instrument
          in: path
          description: The spot instrument for which data will be retrieved.
          schema:
            type: string
            default: eth_usd
          required: true
        - name: exchange
          in: query
          description: >-
            The exchange for which data should be retrieved. Only **1** exchange
            is allowed.
          required: true
          schema:
            type: string
            default: bitfinex
        - name: startDate
          in: query
          description: >-
            **[Optional]** Payload only includes data after this date
            (inclusive).  **[Formats]** `seconds | milliseconds | iso8601`
            **[Examples]** `1578531600 | 1578531600000 | 2020-09-01T01:00:00`
          schema:
            type: string
        - name: endDate
          in: query
          description: >-
            **[Optional]** Payload only includes data before this date
            (exclusive).  **[Formats]** `seconds | milliseconds | iso8601`
            **[Examples]** `1578531600 | 1578531600000 | 2020-09-01T01:00:00`
          schema:
            type: string
        - name: maxLevel
          in: query
          description: >-
            The number of order book levels that should be returned. By default,
            returns max available levels.
          schema:
            type: integer
            format: int32
        - name: timestamp
          in: query
          description: >-
            Filter for order book data that is less or equal to this specified
            timestamp.
          schema:
            type: string
        - name: timeFormat
          in: query
          description: '**[Optional]** Time format of the timestamps in the response.'
          schema:
            type: string
            enum:
              - milliseconds
              - ms*
              - iso
              - iso8601
              - hr
              - human_readable
            default: hr
        - name: sortDirection
          in: query
          description: >-
            **[Optional]** Specifies the direction in which the data is sorted
            (by timestamp).   **[Defaults]** asc (ascending order).   **[Usage
            Conditions]** This parameter can only be used if the `startDate` and
            `endDate` timeframe is within the most recent 24 hours, or if the
            `startDate` and `endDate` parameters are not used at all.  
            **[Examples]** ascending | descending | asc | desc
          schema:
            type: string
        - name: Accept-Encoding
          in: header
          required: true
          description: ''
          schema:
            type: string
            default: gzip, deflate, br
        - name: api-version
          in: header
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    status: 200
                    title: OK
                    description: Successful request
                    payload:
                      metadata:
                        requestedStartDate: 1717513062160
                        requestedEndDate: 1717599462160
                        returnedStartDate: 1717513080000
                        returnedEndDate: 1717515360000
                        next: >-
                          https://api.amberdata.com/markets/spot/order-book-snapshots/eth_usd?cursor=N4IgxgrgTgzg9lEAuAdhANugNCGAXAQyjwBEC8BTZARgHY6BWahgZgDYAGLjnClAEzKUa9WgwCc4gCxsATNU448ASwC2FAGIJV5ZCFXLMymBTBwBMEErUUAkikpQAbgXTJQKAur0BPCkUscGABHdAA5LyokED8iK1xQiPUABXRoV19-KHQfeP4KADMCDDxkAA42KW4uHB0AD2Q2FlkpKTLqnhB0ODgAawAjAjBe5IooZTh%2BZDRMAF8cAu1daIAreBR4ijqwAAsCFABzKJB%2B5TwC5RQt%2BJV1fC8AB2mMbH0COoAZCicKN1QXoIIPAAaQouWidEYzHY1QA%2BhxYadzpctvDYXgoBAKLCKHgdrCIDAprMgA
                        api-version: '2023-09-30'
                      data:
                        - exchange: bitfinex
                          instrument: eth_usd
                          timestamp: 1717513080000
                          sequence: null
                          ask:
                            - price: 3780.7
                              volume: 7.33
                              numOrders: 1
                            - price: 3780.8
                              volume: 11.60410568
                              numOrders: 1
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  title:
                    type: string
                  description:
                    type: string
                  payload:
                    type: object
                    properties:
                      metadata:
                        type: object
                        properties:
                          requestedStartDate:
                            type: integer
                          requestedEndDate:
                            type: integer
                          returnedStartDate:
                            type: integer
                          returnedEndDate:
                            type: integer
                          next:
                            type: string
                          api-version:
                            type: string
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            exchange:
                              type: string
                            instrument:
                              type: string
                            timestamp:
                              type: integer
                            sequence:
                              type: string
                            ask:
                              type: array
                              items:
                                type: object
                                properties:
                                  price:
                                    type: number
                                  volume:
                                    type: number
                                  numOrders:
                                    type: integer
      deprecated: false
      security:
        - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````