docs
Core concepts
API Reference
Resources
Menu
API key Support
Support

API reference - Historical

Databento's historical data service can be accessed programmatically over its HTTP API. To make it easier to integrate the API, we also provide official client libraries that simplify the code you need to write.

Our HTTP API is designed as a collection of RPC-style methods, which can be called using URLs in the form https://hist.databento.com/v0/METHOD_FAMILY.METHOD.

Our client libraries wrap these HTTP RPC-style methods with more idiomatic interfaces in their respective languages.

You can use our API to stream or load data directly into your application. You can also use our API to make batch download requests, which instruct our service to prepare the data as flat files that can downloaded from the Download center.

HISTORICAL DATA
Client libraries
Python
Python
C++
C++
Rust
Rust
APIs
HTTP
HTTP

Basics

Overview

Our historical API has the following structure:

  • Metadata provides information about the datasets themselves.
  • Time series provides all types of time series data. This includes subsampled data (second, minute, hour, daily aggregates), trades, top-of-book, order book deltas, order book snapshots, summary statistics, static data and macro indicators. We also provide properties of products such as expirations, tick sizes and symbols as time series data.
  • Symbology provides methods that help find and resolve symbols across different symbology systems.
  • Batch provides a means of submitting and querying for details of batch download requests.

Authentication

Databento uses API keys to authenticate requests. You can view and manage your keys on the API keys page of our web platform.

Each API key is a 32-character string starting with db-.

Info
Info

Our HTTP API authenticates requests using the HTTP basic auth scheme, which takes a username and password. Use your API key as the username and leave the password blank.

Appending a colon (:) after YOUR_API_KEY prevents curl from asking for a password.

Related: Securing your API keys.

Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_datasets' \
 -u YOUR_API_KEY:

Schemas and conventions

A schema is a data record format represented as a collection of different data fields. Our datasets support multiple schemas, such as order book, tick data, bar aggregates, and so on. You can get a dictionary describing the fields of each schema from our List of market data schemas.

You can get a list of all supported schemas for any given dataset using the list_schemas method. The same information can also be found on each dataset's detail page found through the Explore feature.

The following table provides details about the data types and conventions used for various fields that you will commonly encounter in the data.

Name Field Description
Dataset dataset A unique string name assigned to each dataset by Databento. Full list of datasets can be found from the metadata.
Publisher ID publisher_id A unique 16-bit unsigned integer assigned to each publisher by Databento. Full list of publisher IDs can be found from the metadata.
Instrument ID instrument_id A unique 32-bit unsigned integer assigned to each instrument by the venue. Information about instrument IDs for any given dataset can be found in the symbology.
Order ID order_id A unique 64-bit unsigned integer assigned to each order by the venue.
Timestamp (event) ts_event The matching-engine-received timestamp expressed as the number of nanoseconds since the UNIX epoch.
Timestamp (receive) ts_recv The capture-server-received timestamp expressed as the number of nanoseconds since the UNIX epoch.
Timestamp delta (in) ts_in_delta The matching-engine-sending timestamp expressed as the number of nanoseconds before ts_recv. See timestamping guide.
Timestamp out ts_out The Databento gateway-sending timestamp expressed as the number of nanoseconds since the UNIX epoch. See timestamping guide.
Price price The price expressed as signed integer where every 1 unit corresponds to 1e-9, i.e. 1/1,000,000,000 or 0.000000001.
Book side side The side that initiates the event. Can be Ask for a sell order (or sell aggressor in a trade), Bid for a buy order (or buy aggressor in a trade), or None where no side is specified by the original source.
Size size The order quantity.
Flag flag A bit field indicating event end, message characteristics, and data quality.
Action action The event type or order book operation. Can be Add, Cancel, Modify, cleaR book, Trade, Fill, or None.
Sequence number sequence The original message sequence number from the venue.

Datasets

Databento provides time series datasets for a variety of markets, sourced from different publishers. Our available datasets can be browsed through the search feature on our site.

Each dataset is assigned a unique string identifier (dataset ID) in the form PUBLISHER.DATASET, such as GLBX.MDP3. For publishers that are also markets, we use standard four-character ISO 10383 Market Identifier Codes (MIC). Otherwise, Databento arbitrarily assigns a four-character identifier for the publisher.

These dataset IDs are also found on the Data catalog and Download request features of the Databento user portal.

When a publisher provides multiple data products with different levels of granularity, Databento subscribes to the most-granular product. We then provide this dataset with alternate schemas to make it easy to work with the level of detail most appropriate for your application.

More information about different types of venues and publishers is available in our Knowledge base.

Symbology

Databento's historical API supports several ways to select an instrument in a dataset. An instrument is specified using a symbol and a symbology type, also referred to as an stype. The supported symbology types are:

  • Raw symbology (raw_symbol) original string symbols used by the publisher in the source data.
  • Instrument ID symbology (instrument_id) unique numeric ID assigned to each instrument by the publisher.
  • Parent symbology (parent) groups instruments related to the market for the same underlying.
  • Continuous contract symbology (continuous) proprietary symbology that specifies instruments based on certain systematic rules.

When requesting data from our timeseries.get_range or batch.submit_job endpoints, an input and output symbology type can be specified. By default, our client libraries will use raw symbology for the input type and instrument ID symbology for the output type. Not all symbology types are supported for every dataset.

The process of converting between one symbology type to another is called symbology resolution. This conversion can be done, for no cost, with the symbology.resolve endpoint.

For more about symbology at Databento, see our Knowledge base.

Encodings

DBN

Databento Binary Encoding (DBN) is an extremely fast message encoding and highly-compressible storage format for normalized market data. It includes a self-describing metadata header and adopts a binary format with zero-copy serialization.

We recommend using our Python, C++, or Rust client libraries to read DBN files locally. A CLI tool is also available for converting DBN files to CSV or JSON.

CSV

Comma-separated values (CSV) is a simple text file format for tabular data, CSVs can be easily opened with Excel, loaded into pandas data frames, or parsed in C++.

Our CSVs have one header line, followed by one record per line. Lines use UNIX-style \n separators.

JSON

JavaScript Object Notation (JSON) is a flexible text file format with broad language support and wide adoption across web apps.

Our JSON files follow the JSON lines specification, where each line of the file is a JSON record. Lines use UNIX-style \n separators.

Compression

Databento provides options for compressing files from our API. Available compression formats depend on the encoding you select.

zstd

The zstd compression option uses the Zstandard format.

This option is available for all encodings, and is recommended for faster transfer speeds and smaller files.

Read more about working with Zstandard-compressed files.

none

The none compression option disables compression entirely, resulting in significantly larger files. However, this can be useful for loading small CSV files directly into Excel.

Dates and times

Our API exposes several parameters that expect a timestamp. Databento supports several formats based on ISO 8601.

Timestamps can be specified as ISO 8601 string or UNIX nanoseconds.

  • yyyy-mm-dd, e.g. 2022-02-28 (midnight UTC)
  • yyyy-mm-ddTHH:MM, e.g. 2022-02-28T23:50
  • yyyy-mm-ddTHH:MM:SS, e.g. 2022-02-28T23:50:59
  • yyyy-mm-ddTHH:MM:SS.NNNNNNNNN, e.g. 2022-02-28T23:50:59.123456789
  • UNIX nanoseconds, e.g. 1646110259123456789

Timezone specification is also supported.

  • yyyy-mm-ddTHH:MMZ
  • yyyy-mm-ddTHH:MMĀ±hh
  • yyyy-mm-ddTHH:MMĀ±hhmm
  • yyyy-mm-ddTHH:MMĀ±hh:mm

In our market data, we always use UNIX nanoseconds to encode timestamps as a single number. Our client libraries can help convert this into a human-readable format.

Bare dates

Some parameters require a bare date, without a time. In these cases, the date must be specified in yyyy-mm-dd format, e.g. 2022-02-28.

Errors

Our historical API uses HTTP response codes to indicate the success or failure of an API request. On error, the HTTP body will also contain a JSON object with a human-readable error message in the detail field.

  • 2xx indicates success.
  • 4xx indicates an error with the client's request.
  • 5xx indicates an error with Databento's servers.

The full list of the response codes and associated causes is as follows:

Code Message Cause
200 OK Successful request.
206 Partial Content Successful request, with partially resolved symbols.
400 Bad Request Invalid request. Usually due to a missing, malformed or unsupported parameter.
401 Unauthorized Invalid username or API key.
402 Payment Required Issue with your account payment information.
403 Forbidden The API key has insufficient permissions to perform the request.
404 Not Found A resource is not found, or a requested symbol does not exist.
409 Conflict A resource already exists.
422 Unprocessable Entity The request is well formed, but we cannot or will not process the contained instructions.
429 Too Many Requests API rate limit exceeded.
500 Internal Server Error Unexpected condition encountered in our system.
503 Service Unavailable Data gateway is offline or overloaded.
504 Gateway Timeout Data gateway is available but other parts of our system are offline or overloaded.
Example usage
PythonC++RustHTTP
curl -i 'https://hist.databento.com/v0/metadata.list_datasets'
Example response
PythonC++RustHTTP
HTTP/2 401
date: Wed, 30 Nov 2022 17:59:08 GMT
server: uvicorn
www-authenticate: Basic
content-length: 30
content-type: application/json

{"detail":"Not authenticated"}

Rate limits

Our historical API allows each IP address up to:

When a request exceeds a rate limit, a BentoClientError exception is raised with a 429 error code.

Retry-After

The Retry-After response header indicates how long the user should wait before retrying.

If you find that your application has been rate-limited, you can retry after waiting for the time specified in the Retry-After header.

If you are using our HTTP API's through cURL, you may want to use the sleep 1 command to wait 1 second before your next request.

This code snippet works best for our current APIs with their rate limits. Future APIs may have different rate limits, and might require a different default time delay.

Size limits

There is no size limit for either stream or batch download requests. Batch download is more manageable for large datasets, so we recommend using batch download for requests over 5 GB.

You can also manage the size of your request by splitting it into multiple, smaller requests. The historical API allows you to make stream and batch download requests with time ranges specified up to nanosecond resolution. You can also use the limit parameter in any request to limit the number of data records returned from the service.

Batch download supports different delivery methods which can be specified using the delivery parameter.

Example usage
PythonC++RustHTTP
curl -X POST -G 'https://hist.databento.com/v0/batch.submit_job' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d schema=trades \
 -d start='2022-06-06T00:00' \
 -d end='2022-06-10T00:10' \
 -d limit=10000

Metered pricing

Databento only charges for the data that you use. You can find rates (per MB) for the various datasets and estimate pricing on our Data catalog. We meter the data by its uncompressed size in binary encoding.

When you stream the data, you are billed incrementally for each outbound byte of data sent from our historical gateway. If your connection is interrupted while streaming our data and our historical gateway detects connection timeout over 5 seconds, it will immediately stop sending data and you will not be billed for the remainder of your request.

Duplicate streaming requests will incur repeated charges. If you intend to access the same data multiple times, we recommend using our batch download feature. When you make a batch download request, you are only billed once for the request and, subsequently, you can download the data from the Download center multiple times over 30 days for no additional charge.

You will only be billed for usage of time series data. Access to metadata, symbology, and account management is free. The Historical.metadata.get_cost method can be used to determine cost before you request any data.

Related: Billing management.

Versioning

Our historical API and its client libraries adopt MAJOR.MINOR.PATCH format for version numbers. These version numbers conform to semantic versioning. We are using major version 0 for initial development where our API is not considered stable.

Once we release major version 1, our public API will be stable. This means that you will be able to upgrade minor or patch versions to pick up new functionality, without breaking your integration.

Starting with major versions after 1, we will provide support for previous versions for one year after the date of the subsequent major release. For example, if version 2.0.0 is released on January 1, 2024, then all versions 1.x.y of the API and client libraries will be deprecated. However, they will remain supported until January 1, 2025.

We may introduce backwards-compatible changes between minor versions in the form of:

Our Release notes will contain information about both breaking and backwards-compatible changes in each release.

Related: Release notes.

Metadata

/metadata.list_publishers

List all publisher ID mappings.

Use this method to list the details of publishers, including their dataset and venue mappings.

Returns

array

A list of publisher details objects.

publisher_id
number
The publisher ID assigned by Databento.
dataset
string
The dataset ID for the publisher.
venue
string
The venue for the publisher.
description
string
The publisher description.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.list_publishers
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_publishers' \
 -u YOUR_API_KEY:
Example response
PythonC++RustHTTP
[
  {
    "publisher_id": 1,
    "dataset": "GLBX.MDP3",
    "venue": "GLBX",
    "description": "CME Globex MDP 3.0"
  },
  {
    "publisher_id": 2,
    "dataset": "XNAS.ITCH",
    "venue": "XNAS",
    "description": "Nasdaq TotalView-ITCH"
  },
  {
    "publisher_id": 3,
    "dataset": "XBOS.ITCH",
    "venue": "XBOS",
    "description": "Nasdaq BX TotalView-ITCH"
  },
  {
    "publisher_id": 4,
    "dataset": "XPSX.ITCH",
    "venue": "XPSX",
    "description": "Nasdaq PSX TotalView-ITCH"
  },
  {
    "publisher_id": 5,
    "dataset": "BATS.PITCH",
    "venue": "BATS",
    "description": "Cboe BZX Depth"
  },
  {
    "publisher_id": 6,
    "dataset": "BATY.PITCH",
    "venue": "BATY",
    "description": "Cboe BYX Depth"
  },
  {
    "publisher_id": 7,
    "dataset": "EDGA.PITCH",
    "venue": "EDGA",
    "description": "Cboe EDGA Depth"
  },
  {
    "publisher_id": 8,
    "dataset": "EDGX.PITCH",
    "venue": "EDGX",
    "description": "Cboe EDGX Depth"
  },
  {
    "publisher_id": 9,
    "dataset": "XNYS.PILLAR",
    "venue": "XNYS",
    "description": "NYSE Integrated"
  },
  {
    "publisher_id": 10,
    "dataset": "XCIS.PILLAR",
    "venue": "XCIS",
    "description": "NYSE National Integrated"
  },
  {
    "publisher_id": 11,
    "dataset": "XASE.PILLAR",
    "venue": "XASE",
    "description": "NYSE American Integrated"
  },
  {
    "publisher_id": 12,
    "dataset": "XCHI.PILLAR",
    "venue": "XCHI",
    "description": "NYSE Texas Integrated"
  },
  {
    "publisher_id": 13,
    "dataset": "XCIS.BBO",
    "venue": "XCIS",
    "description": "NYSE National BBO"
  },
  {
    "publisher_id": 14,
    "dataset": "XCIS.TRADES",
    "venue": "XCIS",
    "description": "NYSE National Trades"
  },
  {
    "publisher_id": 15,
    "dataset": "MEMX.MEMOIR",
    "venue": "MEMX",
    "description": "MEMX Memoir Depth"
  },
  {
    "publisher_id": 16,
    "dataset": "EPRL.DOM",
    "venue": "EPRL",
    "description": "MIAX Pearl Depth"
  },
  {
    "publisher_id": 17,
    "dataset": "XNAS.NLS",
    "venue": "FINN",
    "description": "FINRA/Nasdaq TRF Carteret"
  },
  {
    "publisher_id": 18,
    "dataset": "XNAS.NLS",
    "venue": "FINC",
    "description": "FINRA/Nasdaq TRF Chicago"
  },
  {
    "publisher_id": 19,
    "dataset": "XNYS.TRADES",
    "venue": "FINY",
    "description": "FINRA/NYSE TRF"
  },
  {
    "publisher_id": 20,
    "dataset": "OPRA.PILLAR",
    "venue": "AMXO",
    "description": "OPRA - NYSE American Options"
  },
  {
    "publisher_id": 21,
    "dataset": "OPRA.PILLAR",
    "venue": "XBOX",
    "description": "OPRA - BOX Options"
  },
  {
    "publisher_id": 22,
    "dataset": "OPRA.PILLAR",
    "venue": "XCBO",
    "description": "OPRA - Cboe Options"
  },
  {
    "publisher_id": 23,
    "dataset": "OPRA.PILLAR",
    "venue": "EMLD",
    "description": "OPRA - MIAX Emerald"
  },
  {
    "publisher_id": 24,
    "dataset": "OPRA.PILLAR",
    "venue": "EDGO",
    "description": "OPRA - Cboe EDGX Options"
  },
  {
    "publisher_id": 25,
    "dataset": "OPRA.PILLAR",
    "venue": "GMNI",
    "description": "OPRA - Nasdaq GEMX"
  },
  {
    "publisher_id": 26,
    "dataset": "OPRA.PILLAR",
    "venue": "XISX",
    "description": "OPRA - Nasdaq ISE"
  },
  {
    "publisher_id": 27,
    "dataset": "OPRA.PILLAR",
    "venue": "MCRY",
    "description": "OPRA - Nasdaq MRX"
  },
  {
    "publisher_id": 28,
    "dataset": "OPRA.PILLAR",
    "venue": "XMIO",
    "description": "OPRA - MIAX Options"
  },
  {
    "publisher_id": 29,
    "dataset": "OPRA.PILLAR",
    "venue": "ARCO",
    "description": "OPRA - NYSE Arca Options"
  },
  {
    "publisher_id": 30,
    "dataset": "OPRA.PILLAR",
    "venue": "OPRA",
    "description": "OPRA - Options Price Reporting Authority"
  },
  {
    "publisher_id": 31,
    "dataset": "OPRA.PILLAR",
    "venue": "MPRL",
    "description": "OPRA - MIAX Pearl"
  },
  {
    "publisher_id": 32,
    "dataset": "OPRA.PILLAR",
    "venue": "XNDQ",
    "description": "OPRA - Nasdaq Options"
  },
  {
    "publisher_id": 33,
    "dataset": "OPRA.PILLAR",
    "venue": "XBXO",
    "description": "OPRA - Nasdaq BX Options"
  },
  {
    "publisher_id": 34,
    "dataset": "OPRA.PILLAR",
    "venue": "C2OX",
    "description": "OPRA - Cboe C2 Options"
  },
  {
    "publisher_id": 35,
    "dataset": "OPRA.PILLAR",
    "venue": "XPHL",
    "description": "OPRA - Nasdaq PHLX"
  },
  {
    "publisher_id": 36,
    "dataset": "OPRA.PILLAR",
    "venue": "BATO",
    "description": "OPRA - Cboe BZX Options"
  },
  {
    "publisher_id": 37,
    "dataset": "OPRA.PILLAR",
    "venue": "MXOP",
    "description": "OPRA - MEMX Options"
  },
  {
    "publisher_id": 38,
    "dataset": "IEXG.TOPS",
    "venue": "IEXG",
    "description": "IEX TOPS"
  },
  {
    "publisher_id": 39,
    "dataset": "DBEQ.BASIC",
    "venue": "XCHI",
    "description": "DBEQ Basic - NYSE Texas"
  },
  {
    "publisher_id": 40,
    "dataset": "DBEQ.BASIC",
    "venue": "XCIS",
    "description": "DBEQ Basic - NYSE National"
  },
  {
    "publisher_id": 41,
    "dataset": "DBEQ.BASIC",
    "venue": "IEXG",
    "description": "DBEQ Basic - IEX"
  },
  {
    "publisher_id": 42,
    "dataset": "DBEQ.BASIC",
    "venue": "EPRL",
    "description": "DBEQ Basic - MIAX Pearl"
  },
  {
    "publisher_id": 43,
    "dataset": "ARCX.PILLAR",
    "venue": "ARCX",
    "description": "NYSE Arca Integrated"
  },
  {
    "publisher_id": 44,
    "dataset": "XNYS.BBO",
    "venue": "XNYS",
    "description": "NYSE BBO"
  },
  {
    "publisher_id": 45,
    "dataset": "XNYS.TRADES",
    "venue": "XNYS",
    "description": "NYSE Trades"
  },
  {
    "publisher_id": 46,
    "dataset": "XNAS.QBBO",
    "venue": "XNAS",
    "description": "Nasdaq QBBO"
  },
  {
    "publisher_id": 47,
    "dataset": "XNAS.NLS",
    "venue": "XNAS",
    "description": "Nasdaq Trades"
  },
  {
    "publisher_id": 48,
    "dataset": "EQUS.PLUS",
    "venue": "XCHI",
    "description": "Databento US Equities Plus - NYSE Texas"
  },
  {
    "publisher_id": 49,
    "dataset": "EQUS.PLUS",
    "venue": "XCIS",
    "description": "Databento US Equities Plus - NYSE National"
  },
  {
    "publisher_id": 50,
    "dataset": "EQUS.PLUS",
    "venue": "IEXG",
    "description": "Databento US Equities Plus - IEX"
  },
  {
    "publisher_id": 51,
    "dataset": "EQUS.PLUS",
    "venue": "EPRL",
    "description": "Databento US Equities Plus - MIAX Pearl"
  },
  {
    "publisher_id": 52,
    "dataset": "EQUS.PLUS",
    "venue": "XNAS",
    "description": "Databento US Equities Plus - Nasdaq"
  },
  {
    "publisher_id": 53,
    "dataset": "EQUS.PLUS",
    "venue": "XNYS",
    "description": "Databento US Equities Plus - NYSE"
  },
  {
    "publisher_id": 54,
    "dataset": "EQUS.PLUS",
    "venue": "FINN",
    "description": "Databento US Equities Plus - FINRA/Nasdaq TRF Carteret"
  },
  {
    "publisher_id": 55,
    "dataset": "EQUS.PLUS",
    "venue": "FINY",
    "description": "Databento US Equities Plus - FINRA/NYSE TRF"
  },
  {
    "publisher_id": 56,
    "dataset": "EQUS.PLUS",
    "venue": "FINC",
    "description": "Databento US Equities Plus - FINRA/Nasdaq TRF Chicago"
  },
  {
    "publisher_id": 57,
    "dataset": "IFEU.IMPACT",
    "venue": "IFEU",
    "description": "ICE Europe Commodities"
  },
  {
    "publisher_id": 58,
    "dataset": "NDEX.IMPACT",
    "venue": "NDEX",
    "description": "ICE Endex"
  },
  {
    "publisher_id": 59,
    "dataset": "DBEQ.BASIC",
    "venue": "DBEQ",
    "description": "Databento US Equities Basic - Consolidated"
  },
  {
    "publisher_id": 60,
    "dataset": "EQUS.PLUS",
    "venue": "EQUS",
    "description": "EQUS Plus - Consolidated"
  },
  {
    "publisher_id": 61,
    "dataset": "OPRA.PILLAR",
    "venue": "SPHR",
    "description": "OPRA - MIAX Sapphire"
  },
  {
    "publisher_id": 62,
    "dataset": "EQUS.ALL",
    "venue": "XCHI",
    "description": "Databento US Equities (All Feeds) - NYSE Texas"
  },
  {
    "publisher_id": 63,
    "dataset": "EQUS.ALL",
    "venue": "XCIS",
    "description": "Databento US Equities (All Feeds) - NYSE National"
  },
  {
    "publisher_id": 64,
    "dataset": "EQUS.ALL",
    "venue": "IEXG",
    "description": "Databento US Equities (All Feeds) - IEX"
  },
  {
    "publisher_id": 65,
    "dataset": "EQUS.ALL",
    "venue": "EPRL",
    "description": "Databento US Equities (All Feeds) - MIAX Pearl"
  },
  {
    "publisher_id": 66,
    "dataset": "EQUS.ALL",
    "venue": "XNAS",
    "description": "Databento US Equities (All Feeds) - Nasdaq"
  },
  {
    "publisher_id": 67,
    "dataset": "EQUS.ALL",
    "venue": "XNYS",
    "description": "Databento US Equities (All Feeds) - NYSE"
  },
  {
    "publisher_id": 68,
    "dataset": "EQUS.ALL",
    "venue": "FINN",
    "description": "Databento US Equities (All Feeds) - FINRA/Nasdaq TRF Carteret"
  },
  {
    "publisher_id": 69,
    "dataset": "EQUS.ALL",
    "venue": "FINY",
    "description": "Databento US Equities (All Feeds) - FINRA/NYSE TRF"
  },
  {
    "publisher_id": 70,
    "dataset": "EQUS.ALL",
    "venue": "FINC",
    "description": "Databento US Equities (All Feeds) - FINRA/Nasdaq TRF Chicago"
  },
  {
    "publisher_id": 71,
    "dataset": "EQUS.ALL",
    "venue": "BATS",
    "description": "Databento US Equities (All Feeds) - Cboe BZX"
  },
  {
    "publisher_id": 72,
    "dataset": "EQUS.ALL",
    "venue": "BATY",
    "description": "Databento US Equities (All Feeds) - Cboe BYX"
  },
  {
    "publisher_id": 73,
    "dataset": "EQUS.ALL",
    "venue": "EDGA",
    "description": "Databento US Equities (All Feeds) - Cboe EDGA"
  },
  {
    "publisher_id": 74,
    "dataset": "EQUS.ALL",
    "venue": "EDGX",
    "description": "Databento US Equities (All Feeds) - Cboe EDGX"
  },
  {
    "publisher_id": 75,
    "dataset": "EQUS.ALL",
    "venue": "XBOS",
    "description": "Databento US Equities (All Feeds) - Nasdaq BX"
  },
  {
    "publisher_id": 76,
    "dataset": "EQUS.ALL",
    "venue": "XPSX",
    "description": "Databento US Equities (All Feeds) - Nasdaq PSX"
  },
  {
    "publisher_id": 77,
    "dataset": "EQUS.ALL",
    "venue": "MEMX",
    "description": "Databento US Equities (All Feeds) - MEMX"
  },
  {
    "publisher_id": 78,
    "dataset": "EQUS.ALL",
    "venue": "XASE",
    "description": "Databento US Equities (All Feeds) - NYSE American"
  },
  {
    "publisher_id": 79,
    "dataset": "EQUS.ALL",
    "venue": "ARCX",
    "description": "Databento US Equities (All Feeds) - NYSE Arca"
  },
  {
    "publisher_id": 80,
    "dataset": "EQUS.ALL",
    "venue": "LTSE",
    "description": "Databento US Equities (All Feeds) - Long-Term Stock Exchange"
  },
  {
    "publisher_id": 81,
    "dataset": "XNAS.BASIC",
    "venue": "XNAS",
    "description": "Nasdaq Basic - Nasdaq"
  },
  {
    "publisher_id": 82,
    "dataset": "XNAS.BASIC",
    "venue": "FINN",
    "description": "Nasdaq Basic - FINRA/Nasdaq TRF Carteret"
  },
  {
    "publisher_id": 83,
    "dataset": "XNAS.BASIC",
    "venue": "FINC",
    "description": "Nasdaq Basic - FINRA/Nasdaq TRF Chicago"
  },
  {
    "publisher_id": 84,
    "dataset": "IFEU.IMPACT",
    "venue": "XOFF",
    "description": "ICE Europe - Off-Market Trades"
  },
  {
    "publisher_id": 85,
    "dataset": "NDEX.IMPACT",
    "venue": "XOFF",
    "description": "ICE Endex - Off-Market Trades"
  },
  {
    "publisher_id": 86,
    "dataset": "XNAS.NLS",
    "venue": "XBOS",
    "description": "Nasdaq NLS - Nasdaq BX"
  },
  {
    "publisher_id": 87,
    "dataset": "XNAS.NLS",
    "venue": "XPSX",
    "description": "Nasdaq NLS - Nasdaq PSX"
  },
  {
    "publisher_id": 88,
    "dataset": "XNAS.BASIC",
    "venue": "XBOS",
    "description": "Nasdaq Basic - Nasdaq BX"
  },
  {
    "publisher_id": 89,
    "dataset": "XNAS.BASIC",
    "venue": "XPSX",
    "description": "Nasdaq Basic - Nasdaq PSX"
  },
  {
    "publisher_id": 90,
    "dataset": "EQUS.SUMMARY",
    "venue": "EQUS",
    "description": "Databento Equities Summary"
  },
  {
    "publisher_id": 91,
    "dataset": "XCIS.TRADESBBO",
    "venue": "XCIS",
    "description": "NYSE National Trades and BBO"
  },
  {
    "publisher_id": 92,
    "dataset": "XNYS.TRADESBBO",
    "venue": "XNYS",
    "description": "NYSE Trades and BBO"
  },
  {
    "publisher_id": 93,
    "dataset": "XNAS.BASIC",
    "venue": "EQUS",
    "description": "Nasdaq Basic - Consolidated"
  },
  {
    "publisher_id": 94,
    "dataset": "EQUS.ALL",
    "venue": "EQUS",
    "description": "Databento US Equities (All Feeds) - Consolidated"
  },
  {
    "publisher_id": 95,
    "dataset": "EQUS.MINI",
    "venue": "EQUS",
    "description": "Databento US Equities Mini"
  },
  {
    "publisher_id": 96,
    "dataset": "XNYS.TRADES",
    "venue": "EQUS",
    "description": "NYSE Trades - Consolidated"
  },
  {
    "publisher_id": 97,
    "dataset": "IFUS.IMPACT",
    "venue": "IFUS",
    "description": "ICE Futures US"
  },
  {
    "publisher_id": 98,
    "dataset": "IFUS.IMPACT",
    "venue": "XOFF",
    "description": "ICE Futures US - Off-Market Trades"
  },
  {
    "publisher_id": 99,
    "dataset": "IFLL.IMPACT",
    "venue": "IFLL",
    "description": "ICE Europe Financials"
  },
  {
    "publisher_id": 100,
    "dataset": "IFLL.IMPACT",
    "venue": "XOFF",
    "description": "ICE Europe Financials - Off-Market Trades"
  },
  {
    "publisher_id": 101,
    "dataset": "XEUR.EOBI",
    "venue": "XEUR",
    "description": "Eurex EOBI"
  },
  {
    "publisher_id": 102,
    "dataset": "XEEE.EOBI",
    "venue": "XEEE",
    "description": "European Energy Exchange EOBI"
  },
  {
    "publisher_id": 103,
    "dataset": "XEUR.EOBI",
    "venue": "XOFF",
    "description": "Eurex EOBI - Off-Market Trades"
  },
  {
    "publisher_id": 104,
    "dataset": "XEEE.EOBI",
    "venue": "XOFF",
    "description": "European Energy Exchange EOBI - Off-Market Trades"
  }
]

/metadata.list_datasets

List all available dataset IDs on Databento.

Use this method to list the available dataset IDs (string identifiers), so you can use other endpoints which take the dataset parameter.

Parameters

start_date
optional
The inclusive UTC start date of the request range as an ISO 8601 date string. Defaults to the first date available.
end_date
optional
The exclusive UTC end date of the request range as an ISO 8601 date string. Defaults to the last date available.

Returns

array

A list of available dataset IDs.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.list_datasets
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_datasets' \
 -u YOUR_API_KEY:
Example response
PythonC++RustHTTP
[
  "GLBX.MDP3",
  "XNAS.ITCH"
]

/metadata.list_schemas

List all available schemas for a dataset.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.

Returns

array

A list of available data schemas.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.list_schemas
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_schemas' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
Example response
PythonC++RustHTTP
[
  "mbo",
  "mbp-1",
  "mbp-10",
  "tbbo",
  "trades",
  "ohlcv-1s",
  "ohlcv-1m",
  "ohlcv-1h",
  "ohlcv-1d",
  "definition",
  "statistics",
  "status"
]

/metadata.list_fields

List all fields for a particular schema and encoding.

Parameters

schema
required
The data record schema. Must be one of the values from list_schemas.
encoding
required
The data encoding. Must be one of 'dbn', 'csv', or 'json'. 'dbn' is recommended.

Returns

array

A list of field details objects.

name
string
The name of the field.
type
string
The type of the field.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.list_fields
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_fields' \
 -u YOUR_API_KEY: \
 -d schema=trades \
 -d encoding=dbn
Example response
PythonC++RustHTTP
[
  {
    "name": "length",
    "type": "uint8_t"
  },
  {
    "name": "rtype",
    "type": "uint8_t"
  },
  {
    "name": "publisher_id",
    "type": "uint16_t"
  },
  {
    "name": "instrument_id",
    "type": "uint32_t"
  },
  {
    "name": "ts_event",
    "type": "uint64_t"
  },
  {
    "name": "price",
    "type": "int64_t"
  },
  {
    "name": "size",
    "type": "uint32_t"
  },
  {
    "name": "action",
    "type": "char"
  },
  {
    "name": "side",
    "type": "char"
  },
  {
    "name": "flags",
    "type": "uint8_t"
  },
  {
    "name": "depth",
    "type": "uint8_t"
  },
  {
    "name": "ts_recv",
    "type": "uint64_t"
  },
  {
    "name": "ts_in_delta",
    "type": "int32_t"
  },
  {
    "name": "sequence",
    "type": "uint32_t"
  }
]

/metadata.list_unit_prices

List unit prices for each data schema in dollars per gigabyte.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.

Returns

array

A list of objects with the unit prices for a feed mode.

mode
string
The feed mode.
unit_prices
object
The map of unit prices in US dollars by schema.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.list_unit_prices
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.list_unit_prices' \
 -u YOUR_API_KEY: \
 -d dataset=OPRA.PILLAR
Example response
PythonC++RustHTTP
[
  {
    "mode": "historical",
    "unit_prices": {
      "mbp-1": 0.04,
      "ohlcv-1s": 280.0,
      "ohlcv-1m": 280.0,
      "ohlcv-1h": 600.0,
      "ohlcv-1d": 600.0,
      "tbbo": 210.0,
      "trades": 280.0,
      "statistics": 11.0,
      "definition": 5.0
    }
  },
  {
    "mode": "historical-streaming",
    "unit_prices": {
      "mbp-1": 0.04,
      "ohlcv-1s": 280.0,
      "ohlcv-1m": 280.0,
      "ohlcv-1h": 600.0,
      "ohlcv-1d": 600.0,
      "tbbo": 210.0,
      "trades": 280.0,
      "statistics": 11.0,
      "definition": 5.0
    }
  },
  {
    "mode": "live",
    "unit_prices": {
      "mbp-1": 0.05,
      "ohlcv-1s": 336.0,
      "ohlcv-1m": 336.0,
      "ohlcv-1h": 720.0,
      "ohlcv-1d": 720.0,
      "tbbo": 252.0,
      "trades": 336.0,
      "statistics": 13.2,
      "definition": 6.0
    }
  }
]

/metadata.get_dataset_condition

Get the dataset condition from Databento.

Use this method to discover data availability and quality.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
start_date
optional
The inclusive UTC start date of the request range as an ISO 8601 date string. Defaults to the first date available.
end_date
optional
The inclusive UTC end date of the request range as an ISO 8601 date string. Defaults to the last date available.

Returns

array

A list of conditions per date.

date
string
The day of the described data, as an ISO 8601 date string.
condition
string
The condition code describing the quality and availability of the data on the given day. Possible values are listed below.
last_modified_date
string
The date when any schema in the dataset on the given day was last generated or modified, as an ISO 8601 date string.

Possible values for condition:

  • available: the data is available with no known issues
  • degraded: the data is available, but there may be missing data or other correctness issues
  • pending: the data is not yet available, but may be available soon
  • missing: the data is not available
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.get_dataset_condition
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.get_dataset_condition' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d start_date='2022-06-06' \
 -d end_date='2022-06-10'
Example response
PythonC++RustHTTP
[
  {
    "date": "2022-06-06",
    "condition": "available",
    "last_modified_date": "2023-03-01"
  },
  {
    "date": "2022-06-07",
    "condition": "available",
    "last_modified_date": "2023-03-01"
  },
  {
    "date": "2022-06-08",
    "condition": "available",
    "last_modified_date": "2023-03-01"
  },
  {
    "date": "2022-06-09",
    "condition": "available",
    "last_modified_date": "2023-03-01"
  }
]

/metadata.get_dataset_range

Get the available range for the dataset given the user's entitlements.

Use this method to discover data availability. The start and end values in the response can be used with the timeseries.get_range and batch.submit_job endpoints.

This endpoint will return the start and end timestamps over the entire dataset as well as the per-schema start and end timestamps under the schema key. In some cases, a schema's availability is a subset of the entire dataset availability.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.

Returns

JSON

The available range for the dataset.

start
string
The inclusive start of the available range as an ISO 8601 timestamp.
end
string
The exclusive end of the available range as an ISO 8601 timestamp.
schema
object
A mapping of schema names to per-schema start and end timestamps.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.get_dataset_range
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.get_dataset_range' \
 -u YOUR_API_KEY: \
 -d dataset=XNAS.ITCH \
Example response
PythonC++RustHTTP
{
    "start":"2018-05-01T00:00:00.000000000Z",
    "end":"2025-01-30T00:00:00.000000000Z",
    "schema": {
        "mbo": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "mbp-1": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "mbp-10": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "bbo-1s": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "bbo-1m": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "tbbo": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "trades": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "ohlcv-1s": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "ohlcv-1m": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "ohlcv-1h": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "ohlcv-1d": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "definition": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "statistics": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "status": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        },
        "imbalance": {
            "start":"2018-05-01T00:00:00.000000000Z",
            "end":"2025-01-30T00:00:00.000000000Z"
        }
    }
}

/metadata.get_record_count

Get the record count of the time series data query.

This method may not be accurate for time ranges that are not discrete multiples of 10 minutes, potentially over-reporting the number of records in such cases. The definition schema is only accurate for discrete multiples of 24 hours.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
symbols
optional
The product symbols to filter for. Takes up to 2,000 symbols per request. If 'ALL_SYMBOLS' or not specified then will select all symbols.
schema
optional, default 'trades'
The data record schema. Must be one of the values from list_schemas.
start
required
The inclusive start of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.
end
optional
The exclusive end of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.
stype_in
optional, default 'raw_symbol'
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
limit
optional
The maximum number of records to return. If not specified, then no limit.

Returns

int

The record count.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.get_record_count
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.get_record_count' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESM2 \
 -d schema=trades \
 -d start='2022-06-06T00:00' \
 -d end='2022-06-10T00:10'
Example response
PythonC++RustHTTP
1990595

/metadata.get_billable_size

Get the billable uncompressed raw binary size for historical streaming or batched files.

This method may not be accurate for time ranges that are not discrete multiples of 10 minutes, potentially over-reporting the size in such cases. The definition schema is only accurate for discrete multiples of 24 hours.

Info
Info

The amount billed will be based on the actual amount of bytes sent; see our pricing documentation for more details.

Parameters

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
symbols
optional
The product symbols to filter for. Takes up to 2,000 symbols per request. If 'ALL_SYMBOLS' or not specified then will select all symbols.
schema
optional, default 'trades'
The data record schema. Must be one of the values from list_schemas.
start
required
The inclusive start of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.
end
optional
The exclusive end of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.
stype_in
optional, default 'raw_symbol'
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
limit
optional
The maximum number of records to return. If not specified, then no limit.

Returns

number

The size in number of bytes used for billing.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.get_billable_size
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.get_billable_size' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESM2 \
 -d schema=trades \
 -d start='2022-06-02T00:00' \
 -d end='2022-06-10T00:10'
Example response
PythonC++RustHTTP
142505232

/metadata.get_cost

Get the cost in US dollars for a historical streaming or batch download request. This cost respects any discounts provided by flat rate plans.

This method may not be accurate for time ranges that are not discrete multiples of 10 minutes, potentially over-reporting the cost in such cases. The definition schema is only accurate for discrete multiples of 24 hours.

Info
Info

The amount billed will be based on the actual amount of bytes sent; see our pricing documentation for more details.

Parameters

dataset
required
The dataset code. Must be one of the values from list_datasets.
symbols
optional
The product symbols to filter for. Takes up to 2,000 symbols per request. If 'ALL_SYMBOLS' or not specified then will select all symbols.
schema
optional, default 'trades'
The data record schema. Must be one of the values from list_schemas.
start
required
The inclusive start of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.
end
optional
The exclusive end of the request range. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.
stype_in
optional, default 'raw_symbol'
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
limit
optional
The maximum number of records to return. If not specified, then no limit.

Returns

number

The cost in US dollars.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/metadata.get_cost
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/metadata.get_cost' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESM2 \
 -d schema=mbo \
 -d start='2022-06-06T00:00' \
 -d end='2022-06-10T00:10'
Example response
PythonC++RustHTTP
4.923090054095

Time series

/timeseries.get_range

Make a streaming request for time series data from Databento.

Primary method for getting historical intraday and daily market data, instrument definitions, and market status data directly into your application.

For large requests, consider using /batch.submit_job instead.

Parameters

The following parameters should be encoded as form data (not in a JSON body).

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
start
required
The inclusive start of the request range. Filters on ts_recv if it exists in the schema, otherwise ts_event. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.
end
optional
The exclusive end of the request range. Filters on ts_recv if it exists in the schema, otherwise ts_event. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.
symbols
optional
The product symbols to filter for. Takes up to 2,000 symbols per request. If more than 1 symbol is specified, the data is merged and sorted by time. If 'ALL_SYMBOLS' or not specified then will select all symbols.
schema
optional, default 'trades'
The data record schema. Must be one of the values from list_schemas.
encoding
optional, default 'csv'
The data encoding. Must be one of 'dbn', 'csv', 'json'. For fastest transfer speed, 'dbn' is recommended.
compression
optional, default 'none'
The data compression mode. Must be either 'zstd' or 'none'. For fastest transfer speed, 'zstd' is recommended.
stype_in
optional, default 'raw_symbol'
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
stype_out
optional, default 'instrument_id'
The symbology type of output symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
limit
optional
The maximum number of records to return. If not specified, then no limit.
pretty_px
optional, default 'false'
If prices should be formatted to the correct scale (using the fixed-precision scalar 1e-9). Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.
pretty_ts
optional, default 'false'
If timestamps should be formatted as ISO 8601 strings. Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.
map_symbols
optional, default 'false'
If a symbol field should be included with each text-encoded record. Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.

Returns

Either a DBN, CSV, or JSON file depending on the encoding parameter.

The JSON encoding follows the JSON lines specification with one record per line.

A full list of fields for each schema is available through /metadata.list_fields.

API method
PythonC++RustHTTP
POST https://hist.databento.com/v0/timeseries.get_range
Example usage
PythonC++RustHTTP
curl -X POST 'https://hist.databento.com/v0/timeseries.get_range' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESM2 \
 -d schema=trades \
 -d start='2022-06-06T00:00' \
 -d end='2022-06-10T00:10' \
 -d encoding=json \
 -d pretty_px=true \
 -d pretty_ts=true \
 -d map_symbols=true \
 -d limit=1
Example response
PythonC++RustHTTP
{"ts_recv":"2022-06-06T00:00:00.070314216Z","hd":{"ts_event":"2022-06-06T00:00:00.070033767Z","rtype":0,"publisher_id":1,"instrument_id":3403},"action":"T","side":"A","depth":0,"price":"4108.500000000","size":1,"flags":0,"ts_in_delta":18681,"sequence":157862,"symbol":"ESM2"}

Symbology

/symbology.resolve

Resolve a list of symbols from an input symbology type, to an output symbology type.

Take, for example, a raw symbol to an instrument ID: ESM2 ā†’ 3403.

Parameters

The following parameters should be encoded as form data (not in a JSON body).

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
symbols
required
The symbols to resolve. Takes up to 2,000 symbols per request. Use 'ALL_SYMBOLS' to request all symbols (not available for every dataset).
stype_in
required
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
stype_out
required
The symbology type of output symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
start_date
required
The inclusive UTC start date of the request range as an ISO 8601 date string.
end_date
optional
The exclusive UTC end date of the request range as an ISO 8601 date string. Defaults to the forward filled value of start based on the resolution provided.

Returns

JSON

A JSON object containing symbol resolutions and any symbols or time periods for which a symbol could not be resolved.

API method
PythonC++RustHTTP
POST https://hist.databento.com/v0/symbology.resolve
Example usage
PythonC++RustHTTP
curl -X POST 'https://hist.databento.com/v0/symbology.resolve' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESM2 \
 -d stype_in=raw_symbol \
 -d stype_out=instrument_id \
 -d start_date='2022-06-06' \
 -d end_date='2022-06-10'
Example response
PythonC++RustHTTP
{
  "result": {
    "ESM2": [
      {
        "d0": "2022-06-06",
        "d1": "2022-06-10",
        "s": "3403"
      }
    ]
  },
  "symbols": [
    "ESM2"
  ],
  "stype_in": "raw_symbol",
  "stype_out": "instrument_id",
  "start_date": "2022-06-06",
  "end_date": "2022-06-10",
  "partial": [],
  "not_found": [],
  "message": "OK",
  "status": 0
}

Batch downloads

Batch downloads allow you to download flat files directly from within your portal. For more information, see Streaming vs. batch download.

/batch.submit_job

Make a batch download job request for flat files.

Once a request is submitted, our system processes the request and prepares the batch files in the background. The status of your request and the files can be accessed from the Download center from your user portal.

This method takes longer than a streaming request, but is advantageous for larger requests as it supports delivery mechanisms that allow multiple accesses of the data without additional cost for each subsequent download after the first.

Related: batch.list_jobs.

Parameters

The following parameters should be encoded as form data (not in a JSON body).

dataset
required
The dataset code (string identifier). Must be one of the values from list_datasets.
start
required
The inclusive start of the request range. Filters on ts_recv if it exists in the schema, otherwise ts_event. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.
end
optional
The exclusive end of the request range. Filters on ts_recv if it exists in the schema, otherwise ts_event. Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified. Defaults to the forward filled value of start based on the resolution provided.
symbols
optional
The product symbols to filter for. Takes up to 2,000 symbols per request. If more than 1 symbol is specified, the data is merged and sorted by time. If 'ALL_SYMBOLS' or not specified then will select all symbols.
schema
required
The data record schema. Must be one of the values from list_schemas.
encoding
required
The data encoding. Must be one of 'dbn', 'csv', 'json'. For fastest transfer speed, 'dbn' is recommended.
compression
optional, default 'none'
The data compression mode. Must be either 'zstd' or 'none'. For fastest transfer speed, 'zstd' is recommended.
stype_in
optional, default 'raw_symbol'
The symbology type of input symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
stype_out
optional, default 'instrument_id'
The symbology type of output symbols. Must be one of 'raw_symbol', 'instrument_id', 'parent', or 'continuous'.
limit
optional
The maximum number of records to return. Defaults to no limit. Cannot be used with split_symbols.
pretty_px
optional, default 'false'
If prices should be formatted to the correct scale (using the fixed-precision scalar 1e-9). Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.
pretty_ts
optional, default 'false'
If timestamps should be formatted as ISO 8601 strings. Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.
map_symbols
optional, default 'false'
If a symbol field should be included with each text-encoded record. Only applicable for 'csv' or 'json' encodings. Must be a boolean-like value 'true' or 'false'.
split_symbols
optional, default 'false'
If files should be split by raw symbol. Cannot be requested with 'ALL_SYMBOLS'. Must be a boolean-like value 'true' or 'false'. Cannot be used with limit.
split_duration
optional, default 'day'
The maximum time duration before batched data files are split into multiple files. Must be one of 'day', 'week', 'month', or 'none'. A week starts on Sunday UTC.
split_size
optional
The maximum size (in bytes) of each batched data file before being split. Must be an integer between 1e9 and 10e9 inclusive (1GB - 10GB). Defaults to no split size.
delivery
optional, default 'download'
The delivery mechanism for the batched data files once processed. Only 'download' is supported at this time.

Returns

JSON

A JSON object containing a description of the submitted batch job.

id
string
The unique job ID for the request.
user_id
string
The user ID of the user who made the request.
api_key
string or null
The API key name for the request (if Basic Auth was used).
cost_usd
number or null
The cost of the job in US dollars (null until the job is processed).
dataset
string
The dataset code (string identifier).
symbols
string
The list of symbols specified in the request.
stype_in
string
The symbology type of input symbols.
stype_out
string
The symbology type of output symbols.
schema
string
The data record schema.
start
string
The ISO 8601 timestamp start of request time range (inclusive).
end
string
The ISO 8601 timestamp end of request time range (exclusive).
limit
number or null
The maximum number of records to return.
encoding
string
The data encoding.
compression
string
The data compression mode.
pretty_px
bool
If prices are formatted to the correct scale (using the fixed-precision scalar 1e-9).
pretty_ts
bool
If timestamps are formatted as ISO 8601 strings.
map_symbols
bool
If a symbol field is included with each text-encoded record.
split_symbols
bool
If files are split by raw symbol.
split_duration
string
The maximum time interval for an individual file before splitting into multiple files.
split_size
number or null
The maximum size for an individual file before splitting into multiple files.
packaging
string or null
The archive packaging method of the batched data, one of 'none', 'zip', or 'tar'.
delivery
string
The delivery mechanism of the batched data. Only 'download' is supported at this time.
record_count
number or null
The number of data records (null until the job is processed).
billed_size
number or null
The size of the raw binary data used to process the batch job (used for billing purposes).
actual_size
number or null
The total size of the result of the batch job after splitting and compression.
package_size
number or null
The total size of the result of the batch job after any packaging (including metadata).
state
string
The current status of the batch job. One of 'received', 'queued', 'processing', 'done', or 'expired'.
ts_received
string
The ISO 8601 timestamp when Databento received the batch job.
ts_queued
string or null
The ISO 8601 timestamp when the batch job was queued.
ts_process_start
string or null
The ISO 8601 timestamp when the batch job began processing (if it's begun).
ts_process_done
string or null
The ISO 8601 timestamp when the batch job finished processing (if it's finished).
ts_expiration
string or null
The ISO 8601 timestamp when the batch job will expire from the Download center.
API method
PythonC++RustHTTP
POST https://hist.databento.com/v0/batch.submit_job
Example usage
PythonC++RustHTTP
curl -X POST 'https://hist.databento.com/v0/batch.submit_job' \
 -u YOUR_API_KEY: \
 -d dataset=GLBX.MDP3 \
 -d symbols=ESH2 \
 -d schema=trades \
 -d start='2022-01-03' \
 -d end='2022-01-20' \
 -d encoding=dbn
Example response
PythonC++RustHTTP
{
  "id": "GLBX-20220901-5DEFXVTMSM",
  "user_id": "46PCMCVF",
  "api_key": "prod-001",
  "cost_usd": null,
  "dataset": "GLBX.MDP3",
  "symbols": "ESH2",
  "stype_in": "raw_symbol",
  "stype_out": "instrument_id",
  "schema": "trades",
  "start": "2022-01-03T00:00:00.000000000Z",
  "end": "2022-01-20T00:00:00.000000000Z",
  "limit": null,
  "encoding": "dbn",
  "compression": "none",
  "pretty_px": false,
  "pretty_ts": false,
  "map_symbols": false,
  "split_symbols": false,
  "split_duration": "day",
  "split_size": null,
  "packaging": "none",
  "delivery": "download",
  "record_count": null,
  "billed_size": null,
  "actual_size": null,
  "package_size": null,
  "state": "queued",
  "ts_received": "2022-11-30T20:33:08.006406.000000000Z",
  "ts_queued": null,
  "ts_process_start": null,
  "ts_process_done": null,
  "ts_expiration": null
}

/batch.list_jobs

List batch job details for the user account.

The job details will be sorted in order of ts_received.

Related: Download center.

Parameters

states
optional, default 'queued,processing,done,expired'
The filter for job states as a list of comma separated values. Can include 'queued', 'processing', 'done', and 'expired'. Defaults to all except 'expired'.
since
optional
The filter for timestamp submitted (will not include jobs prior to this). Takes an ISO 8601 string or UNIX timestamp in nanoseconds. Assumes UTC as timezone unless otherwise specified.

Returns

JSON

A list of JSON objects containing batch job details.

id
string
The unique job ID for the request.
user_id
string
The user ID of the user who made the request.
api_key
string or null
The API key name for the request (if Basic Auth was used).
cost_usd
number or null
The cost of the job in US dollars (null until the job is processed).
dataset
string
The dataset code (string identifier).
symbols
string
The list of symbols specified in the request.
stype_in
string
The symbology type of input symbols.
stype_out
string
The symbology type of output symbols.
schema
string
The data record schema.
start
string
The ISO 8601 timestamp start of request time range (inclusive).
end
string
The ISO 8601 timestamp end of request time range (exclusive).
limit
number or null
The maximum number of records to return.
encoding
string
The data encoding.
compression
string
The data compression mode.
pretty_px
bool
If prices are formatted to the correct scale (using the fixed-precision scalar 1e-9).
pretty_ts
bool
If timestamps are formatted as ISO 8601 strings.
map_symbols
bool
If a symbol field is included with each text-encoded record.
split_symbols
bool
If files are split by raw symbol.
split_duration
string
The maximum time interval for an individual file before splitting into multiple files.
split_size
number or null
The maximum size for an individual file before splitting into multiple files.
packaging
string or null
The packaging method of the batch data, one of 'none', 'zip', or 'tar'.
delivery
string
The delivery mechanism of the batch data, one of 'download', 's3', or 'disk'.
record_count
number or null
The number of data records (null until the job is processed).
billed_size
number or null
The size of the raw binary data used to process the batch job (used for billing purposes).
actual_size
number or null
The total size of the result of the batch job after splitting and compression.
package_size
number or null
The total size of the result of the batch job after any packaging (including metadata).
state
string
The current status of the batch job. One of 'received', 'queued', 'processing', 'done', or 'expired'.
ts_received
string
The ISO 8601 timestamp when Databento received the batch job.
ts_queued
string or null
The ISO 8601 timestamp when the batch job was queued.
ts_process_start
string or null
The ISO 8601 timestamp when the batch job began processing (if it's begun).
ts_process_done
string or null
The ISO 8601 timestamp when the batch job finished processing (if it's finished).
ts_expiration
string or null
The ISO 8601 timestamp when the batch job will expire from the Download center.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/batch.list_jobs
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/batch.list_jobs' \
 -u YOUR_API_KEY: \
 -d states=queued,processing,done \
 -d since='20220601T00:00:00'
Example response
PythonC++RustHTTP
[
  {
    "id": "GLBX-20220901-5DEFXVTMSM",
    "user_id": "46PCMCVF",
    "api_key": "prod-001",
    "cost_usd": 6.72198,
    "dataset": "GLBX.MDP3",
    "symbols": "ESH2",
    "stype_in": "raw_symbol",
    "stype_out": "instrument_id",
    "schema": "trades",
    "start": "2022-01-03T00:00:00.000000000Z",
    "end": "2022-01-20T00:00:00.000000000Z",
    "limit": null,
    "encoding": "dbn",
    "compression": "zstd",
    "pretty_px": false,
    "pretty_ts": false,
    "map_symbols": false,
    "split_symbols": false,
    "split_duration": "day",
    "split_size": null,
    "packaging": null,
    "delivery": "download",
    "record_count": 6063235,
    "billed_size": 291035280,
    "actual_size": null,
    "package_size": null,
    "state": "queued",
    "ts_received": "2022-11-30T20:33:08.006406.000000000Z",
    "ts_queued": null,
    "ts_process_start": null,
    "ts_process_done": null,
    "ts_expiration": null,
    "progress": 100
  },
  ...
]

/batch.list_files

List files for a batch job.

This will include all data files and support files.

Related: Download center.

Parameters

job_id
required
The batch job identifier.

Returns

JSON

A list of JSON objects containing file details for the batch job.

filename
string
The file name.
size
number
The size of the file in bytes.
hash
string
The SHA256 hash of the file.
urls
object
A map of download protocol to URL.
API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/batch.list_files
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/batch.list_files' \
 -u YOUR_API_KEY: \
 -d job_id=GLBX-20220610-5DEFXVTMSM
Example response
PythonC++RustHTTP
[
  {
    "filename": "metadata.json",
    "size": 1102,
    "hash": "sha256:0168d53e1705b69b1d6407f10bb3ab48aac492fa0f68f863cc9b092931cc67a7",
    "urls": {
      "https": "https://api.databento.com/v0/batch/download/46PCMCVF/GLBX-20230203-WF9WJYSCDU/metadata.json",
      "ftp": "ftp://ftp.databento.com/46PCMCVF/GLBX-20230203-WF9WJYSCDU/metadata.json"
    }
  },
  {
    "filename": "glbx-mdp3-20220610.mbo.csv.zst",
    "size": 21832,
    "hash": "sha256:1218930af153b4953632216044ef87607afa467fc7ab7fbb1f031fceacf9d52a",
    "urls": {
      "https": "https://api.databento.com/v0/batch/download/46PCMCVF/GLBX-20230203-WF9WJYSCDU/glbx-mdp3-20220610.mbo.csv.zst",
      "ftp": "ftp://ftp.databento.com/46PCMCVF/GLBX-20230203-WF9WJYSCDU/glbx-mdp3-20220610.mbo.csv.zst"
    }
  }
]

/batch.download

Download a file from a batch job.

All files for a job can be downloaded as a single ZIP archive by using the job ID appended with ".zip" as the filename.

Related: Download center.

Parameters

Info
Info

This endpoint uses path parameters.

user_id
required
The user ID for the batch job. This can be found on the API key management page of the portal.
job_id
required
The batch job ID. This can be found in the download center.
filename
required
The filename from the job to download.

Returns

The file data. It is recommended to output this to a file.

API method
PythonC++RustHTTP
GET https://hist.databento.com/v0/batch/download/{user_id}/{job_id}/{filename}
Example usage
PythonC++RustHTTP
curl -G 'https://hist.databento.com/v0/batch/download/WJSPXEQK/XNAS-20240711-Q5D8WRF377/XNAS-20240711-Q5D8WRF377.zip' \
 -u YOUR_API_KEY:
Python C++ Rust HTTP/Raw