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.