openapi: 3.0.3
info:
  title: Databento Historical and Reference Batch Timeseries 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: Timeseries
  description: Stream historical records for a symbol set over a time range.
paths:
  /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'
components:
  responses:
    ValidationError:
      description: The request parameters failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      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.
  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.