openapi: 3.0.3
info:
title: Databento Historical and Reference API
description: >-
Databento's Historical HTTP API serves historical financial market data and
reference data over REST. A request selects a dataset (e.g. GLBX.MDP3,
XNAS.ITCH, DBEQ.BASIC), one or more symbols, a schema (MBO full order book,
MBP-1, MBP-10, trades, OHLCV bars, statistics, definition, and more), and a
time range, and receives normalized records in Databento Binary Encoding
(DBN), CSV, or JSON. Endpoints are grouped as metadata (catalog discovery and
cost estimation), timeseries (streaming data retrieval), symbology (symbol
resolution), batch (asynchronous flat-file jobs), and reference (security
master, corporate actions, adjustment factors). Requests authenticate with
HTTP Basic auth using your Databento API key as the username and an empty
password. Live market data is delivered separately over a raw TCP binary DBN
protocol (with CRAM authentication) and is NOT part of this REST document.
version: '0'
contact:
name: Databento
url: https://databento.com
license:
name: Databento Terms
url: https://databento.com/terms
servers:
- url: https://hist.databento.com/v0
description: Databento Historical and Reference HTTP API
security:
- apiKeyBasicAuth: []
tags:
- name: Metadata
description: Catalog discovery, dataset ranges and conditions, and cost estimation.
- name: Timeseries
description: Stream historical records for a symbol set over a time range.
- name: Symbology
description: Resolve symbols across Databento symbology systems.
- name: Batch
description: Submit and manage asynchronous flat-file download jobs.
- name: Reference
description: Security master, corporate actions, and adjustment factors.
paths:
/metadata.list_publishers:
get:
operationId: listPublishers
tags:
- Metadata
summary: List publishers
description: Lists all publishers and their details.
responses:
'200':
description: A list of publishers.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.list_datasets:
get:
operationId: listDatasets
tags:
- Metadata
summary: List datasets
description: Lists all available dataset codes, optionally filtered by an available date range.
parameters:
- name: start_date
in: query
schema:
type: string
format: date
- name: end_date
in: query
schema:
type: string
format: date
responses:
'200':
description: A list of dataset codes.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.list_schemas:
get:
operationId: listSchemas
tags:
- Metadata
summary: List schemas
description: Lists all data record schemas available for a dataset.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
responses:
'200':
description: A list of schema names.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.list_fields:
get:
operationId: listFields
tags:
- Metadata
summary: List fields
description: Lists the fields of a record schema for a given encoding.
parameters:
- name: schema
in: query
required: true
schema:
type: string
- name: encoding
in: query
schema:
type: string
enum: [dbn, csv, json]
responses:
'200':
description: A list of fields with names and types.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.list_unit_prices:
get:
operationId: listUnitPrices
tags:
- Metadata
summary: List unit prices
description: Lists the per-unit prices for each data schema and feed mode of a dataset.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
responses:
'200':
description: Unit prices per schema and mode.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.get_dataset_condition:
get:
operationId: getDatasetCondition
tags:
- Metadata
summary: Get dataset condition
description: Returns the data-quality condition (available, degraded, pending, missing) per day for a dataset and date range.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
- name: start_date
in: query
schema:
type: string
format: date
- name: end_date
in: query
schema:
type: string
format: date
responses:
'200':
description: Per-day condition entries.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.get_dataset_range:
get:
operationId: getDatasetRange
tags:
- Metadata
summary: Get dataset range
description: Returns the earliest and latest available datetime for a dataset.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
responses:
'200':
description: The available start and end range for the dataset.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.get_record_count:
get:
operationId: getRecordCount
tags:
- Metadata
summary: Get record count
description: Returns the number of records a timeseries query would return, without streaming the data.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
- name: symbols
in: query
schema:
type: string
- name: schema
in: query
schema:
type: string
- name: start
in: query
schema:
type: string
- name: end
in: query
schema:
type: string
responses:
'200':
description: The record count for the query.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.get_billable_size:
get:
operationId: getBillableSize
tags:
- Metadata
summary: Get billable size
description: Returns the uncompressed binary size in bytes that a timeseries query would bill.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
- name: symbols
in: query
schema:
type: string
- name: schema
in: query
schema:
type: string
- name: start
in: query
schema:
type: string
- name: end
in: query
schema:
type: string
responses:
'200':
description: The billable size in bytes.
'401':
$ref: '#/components/responses/Unauthorized'
/metadata.get_cost:
get:
operationId: getCost
tags:
- Metadata
summary: Get cost
description: Returns the estimated US dollar cost of a timeseries query before running it.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
- name: symbols
in: query
schema:
type: string
- name: schema
in: query
schema:
type: string
- name: start
in: query
schema:
type: string
- name: end
in: query
schema:
type: string
- name: mode
in: query
schema:
type: string
enum: [historical, historical-streaming, live]
responses:
'200':
description: The estimated cost in US dollars.
'401':
$ref: '#/components/responses/Unauthorized'
/timeseries.get_range:
get:
operationId: timeseriesGetRange
tags:
- Timeseries
summary: Get timeseries range
description: >-
Streams historical records for the given dataset, symbols, schema, and
time range as an HTTP streaming response in DBN, CSV, or JSON. Billed per
byte streamed. The same operation also accepts POST for large symbol
lists.
parameters:
- name: dataset
in: query
required: true
schema:
type: string
example: GLBX.MDP3
- name: symbols
in: query
schema:
type: string
example: ESH4
- name: schema
in: query
schema:
type: string
example: trades
- name: start
in: query
required: true
schema:
type: string
example: '2024-02-12'
- name: end
in: query
schema:
type: string
example: '2024-02-17'
- name: stype_in
in: query
schema:
type: string
enum: [raw_symbol, instrument_id, parent, continuous]
- name: stype_out
in: query
schema:
type: string
- name: encoding
in: query
schema:
type: string
enum: [dbn, csv, json]
- name: compression
in: query
schema:
type: string
enum: [none, zstd]
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: A stream of records in the requested encoding.
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
post:
operationId: timeseriesGetRangePost
tags:
- Timeseries
summary: Get timeseries range (POST)
description: Same as the GET form, accepting parameters as a form body for large symbol lists.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
dataset:
type: string
symbols:
type: string
schema:
type: string
start:
type: string
end:
type: string
encoding:
type: string
responses:
'200':
description: A stream of records in the requested encoding.
'401':
$ref: '#/components/responses/Unauthorized'
/symbology.resolve:
post:
operationId: symbologyResolve
tags:
- Symbology
summary: Resolve symbols
description: >-
Resolves a list of symbols from one symbology type to another for a
dataset over a date range - for example mapping raw symbols to instrument
IDs, or continuous contract references to raw symbols.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- dataset
- symbols
properties:
dataset:
type: string
symbols:
type: string
stype_in:
type: string
stype_out:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
responses:
'200':
description: A mapping of input symbols to resolved symbols with validity intervals.
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/batch.submit_job:
post:
operationId: batchSubmitJob
tags:
- Batch
summary: Submit batch job
description: >-
Submits an asynchronous batch job that materializes a historical request
into downloadable flat files, optionally split by day, symbol, or size.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- dataset
- symbols
- schema
- start
properties:
dataset:
type: string
symbols:
type: string
schema:
type: string
start:
type: string
end:
type: string
encoding:
type: string
enum: [dbn, csv, json]
compression:
type: string
enum: [none, zstd]
split_duration:
type: string
split_symbols:
type: boolean
split_size:
type: integer
responses:
'200':
description: The created batch job with its id and state.
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/ValidationError'
/batch.list_jobs:
get:
operationId: batchListJobs
tags:
- Batch
summary: List batch jobs
description: Lists batch jobs for the account, optionally filtered by state and submission time.
parameters:
- name: states
in: query
schema:
type: string
description: Comma-separated states such as received, queued, processing, done, expired.
- name: since
in: query
schema:
type: string
responses:
'200':
description: A list of batch jobs.
'401':
$ref: '#/components/responses/Unauthorized'
/batch.list_files:
get:
operationId: batchListFiles
tags:
- Batch
summary: List batch files
description: Lists the output files for a completed batch job, including HTTPS and FTP download URIs and hashes.
parameters:
- name: job_id
in: query
required: true
schema:
type: string
responses:
'200':
description: A list of files with download URIs.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/security_master.get_range:
post:
operationId: securityMasterGetRange
tags:
- Reference
summary: Get security master range
description: Returns point-in-time security master records (instrument definitions and identifiers) for symbols over a date range.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- symbols
- start_date
properties:
dataset:
type: string
symbols:
type: string
stype_in:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
responses:
'200':
description: Security master records.
'401':
$ref: '#/components/responses/Unauthorized'
/security_master.get_last:
post:
operationId: securityMasterGetLast
tags:
- Reference
summary: Get latest security master
description: Returns the most recent security master records for the requested symbols.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- symbols
properties:
dataset:
type: string
symbols:
type: string
stype_in:
type: string
responses:
'200':
description: The latest security master records.
'401':
$ref: '#/components/responses/Unauthorized'
/corporate_actions.get_range:
post:
operationId: corporateActionsGetRange
tags:
- Reference
summary: Get corporate actions range
description: Returns corporate action events (splits, dividends, symbol changes, and more) for symbols over a date range.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- symbols
- start_date
properties:
dataset:
type: string
symbols:
type: string
events:
type: string
stype_in:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
responses:
'200':
description: Corporate action event records.
'401':
$ref: '#/components/responses/Unauthorized'
/adjustment_factors.get_range:
post:
operationId: adjustmentFactorsGetRange
tags:
- Reference
summary: Get adjustment factors range
description: Returns price and volume adjustment factors used to build back-adjusted series, for symbols over a date range.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- symbols
- start_date
properties:
dataset:
type: string
symbols:
type: string
stype_in:
type: string
start_date:
type: string
format: date
end_date:
type: string
format: date
responses:
'200':
description: Adjustment factor records.
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
apiKeyBasicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Supply your Databento API key (prefixed with
db-) as the username and leave the password empty.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
ValidationError:
description: The request parameters failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
detail:
type: string
description: A human-readable description of the error.
case_id:
type: string
description: An identifier for the error case, useful when contacting support.