> ## 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
> Provides historical snapshots of futures order books, capturing bid and ask price levels, volumes, and sequence details at specific timestamps across exchanges.
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/futures-exchanges-reference).
For details on this calculation and how to retrieve the correct values, see our [Changelog Update](/changelog/bitmex-volume-mapping).
The maximum time range (difference between `startDate` and `endDate`) is **18 months**.
If the `startDate` and `endDate` query parameters are not provided, the API will return the data from the previous 24 hours.
## OpenAPI
````yaml get /futures/order-book-snapshots/{instrument}
openapi: 3.1.0
info:
title: market-api
version: '2'
servers:
- url: https://api.amberdata.com/markets
security:
- ApiKeyAuth: []
paths:
/futures/order-book-snapshots/{instrument}:
get:
summary: Snapshots Historical
description: >-
Provides historical snapshots of futures order books, capturing bid and
ask price levels, volumes, and sequence details at specific timestamps
across exchanges.
operationId: futures-order-book-snapshots-historical
parameters:
- name: instrument
in: path
description: The instrument for which to retrieve the requested data.
schema:
type: string
default: BTCUSD_PERP
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: binance
- name: startDate
in: query
description: >-
**[Optional]** Payload only includes data after this date
(inclusive). **[Defaults]** Beginning of the current minute (max
time range is 10 minutes).
schema:
type: string
format: date-time
- name: endDate
in: query
description: >-
**[Optional]** Payload only includes data before this date
(exclusive). **[Defaults]** Ten minutes after the beginning of the
current hour (max time range is 10 minutes).
schema:
type: string
format: date-time
- name: timestamp
in: query
description: >-
**[Optional]** The timestamp at which to return the order book
information (closest match, lower or equal to the timestamp
specified).
schema:
type: string
- name: timeFormat
in: query
description: >-
**[Optional]** Time format of the timestamps in the return payload.
**[Defaults]** `milliseconds | ms* | iso | iso8601 | hr |
human_readable`
schema:
type: string
- 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: maxLevel
in: query
description: The number of order book levels that should be returned.
schema:
type: integer
format: int32
- 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: 1717518243690
requestedEndDate: 1717604643690
returnedStartDate: 1717518300000
returnedEndDate: 1717521900000
next: >-
https://api.amberdata.com/markets/futures/order-book-snapshots/BTCUSD_PERP?cursor=N4IgpgHgxgFghgOwOZhALhAIwJYMVVAGhCgFcAnAZwHtz0FSAbR4ygFznLYBE43U0ARgDsIgKwAmQQE4ADPPnEwCACa9%2B6ESIBssgCza9AZm1zibbAFswAMVqW%2B6EJezNslMFGqrKIc1bAASQR%2BcgA3OEZ0UDxrJwBPME5fVgBHRgA5ODiMRM4-EEp0rOsABUYKSISk8kZ4gpUwADM4JjZ0AA5DBUVnOAh0bSMJPT0OntliRmpqAGtMOChZ0rBybGoVeiZGAF9iJvtHDAArGgQCi2t2bIAHLeZiBwgAGTAwsCi0BgeQXCgKxoAVQQlFINxutH4KgAotB4MgwL40C1GB5WJCANJgeoYLTCSQyCYAfVkRJweAQBCJ0l0RlkUiM0mE2jERLY5FIYCJACEACoAYUBAGVuETStCAEqlEA7IA
api-version: '2023-09-30'
data:
- exchange: binance
instrument: BTCUSD_PERP
timestamp: 1717518300000
exchangeTimestamp: 1717518300711
exchangeTimestampNanoseconds: 0
sequence: '960253327911'
currentFunding: null
ask:
- price: 70895.9
volume: 7086
numOrders: null
- price: 70896
volume: 48
numOrders: null
bid:
- price: 70895.8
volume: 2097
numOrders: null
- price: 70895
volume: 1
numOrders: null
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
exchangeTimestamp:
type: integer
exchangeTimestampNanoseconds:
type: integer
sequence:
type: string
currentFunding:
type: string
ask:
type: array
items:
type: object
properties:
price:
type: number
volume:
type: integer
numOrders:
type: string
bid:
type: array
items:
type: object
properties:
price:
type: number
volume:
type: integer
numOrders:
type: string
'400':
description: '400'
content:
application/json:
examples:
Result:
value: '{}'
schema:
type: object
properties: {}
deprecated: false
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````