> ## 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.
# Events/Updates Historical
> Provides historical event updates for futures order books, including bid and ask price levels, volumes, and sequence information for each update 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-events/{instrument}
openapi: 3.1.0
info:
title: market-api
version: '2'
servers:
- url: https://api.amberdata.com/markets
security:
- ApiKeyAuth: []
paths:
/futures/order-book-events/{instrument}:
get:
summary: Events/Updates Historical
description: >-
Provides historical event updates for futures order books, including bid
and ask price levels, volumes, and sequence information for each update
across exchanges.
operationId: futures-order-books-events-historical
parameters:
- name: instrument
in: path
description: The futures instrument for which data will be retrieved.
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). **[Formats]** `seconds | milliseconds | iso8601`
**[Examples]** `1578531600 | 1578531600000 | 2020-09-01T01:00:00`
schema:
type: string
format: date-time
- 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
format: date-time
- 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: 2024-06-04 16:22:24 224
requestedEndDate: 2024-06-05 16:22:24 224
returnedStartDate: 2024-06-04 16:22:24 231
returnedEndDate: 2024-06-04 16:23:12 414
next: >-
https://api.amberdata.com/markets/futures/order-book-events/BTCUSD_PERP?cursor=N4IgxgrgTgzg9lEAuAdhANugNCGAXAQyjwBEC8BTZARgHY6BWagDmoE4AmAFmq5wpQATMpRr1aANgAMXBly4duOPAEsAthQBiCNeWQgAFhF0oAShQKCCAI3RVl6igEkUlKADcC6ZKBQEN%2BgCeFrAgODAAjugAcv5USCDBRGG4UbEaAAro0F5BIeiBKYIUAGYEGHjIzBJcUnV1OLoAHsgSAMzcXMz1DSDocHAA1tYEYIMZFFAqcILIaJgAvjglOnoJAFbwKCkUTWAGBCgA5vEg1ip%2BKGD2IBdg2cUAqigwEAAObwiUggCiewfHCgwZBldAwCjhL4AaQohQSdEYLHY3F4AH0pKjzpdrqi2NIOExmN02gw2Ki8FAIBRUQAhAAqAGFHgBlEiojI-UwZEALIA
api-version: '2023-09-30'
data:
- instrument: BTCUSD_PERP
exchange: binance
exchangeTimestamp: 2024-06-04 16:23:12 414
exchangeTimestampNanoseconds: 0
sequence: '960251880359'
ask:
- price: 70960.6
volume: 75
numOrders: null
- price: 70973.5
volume: 137
numOrders: null
- price: 70975.4
volume: 7914
numOrders: null
- price: 70976
volume: 0
numOrders: null
- price: 70976.6
volume: 20
numOrders: null
bid:
- price: 70907
volume: 51
numOrders: null
- price: 70914
volume: 50
numOrders: null
- price: 70928.5
volume: 25
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: string
requestedEndDate:
type: string
returnedStartDate:
type: string
returnedEndDate:
type: string
next:
type: string
api-version:
type: string
data:
type: array
items:
type: object
properties:
instrument:
type: string
exchange:
type: string
exchangeTimestamp:
type: string
exchangeTimestampNanoseconds:
type: integer
sequence:
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: integer
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
````