Databento Batch API

openapi: 3.2.0
info:
  title: Databento Batch API
  version: '1.0'
  description: 'Operations tagged Batch across 2 of this provider''s published API definitions: databento-batch-api-openapi.yml, databento-platform-openapi-official.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://hist.databento.com/v0
  description: Databento Historical and Reference HTTP API
tags:
- name: Batch
  description: Submit and manage asynchronous flat-file download jobs.
paths:
  /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'
      security:
      - apiKeyBasicAuth: []
    servers:
    - url: https://hist.databento.com/v0
      description: Databento Historical and Reference HTTP API
  /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'
      security:
      - apiKeyBasicAuth: []
    servers:
    - url: https://hist.databento.com/v0
      description: Databento Historical and Reference HTTP API
  /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:
      - apiKeyBasicAuth: []
    servers:
    - url: https://hist.databento.com/v0
      description: Databento Historical and Reference HTTP API
  /v0/batch/me:
    post:
      tags:
      - Batch
      summary: Submit Batch Request With Token Auth
      operationId: submit_batch_request_with_token_auth_v0_batch_me_post
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: dataset
        in: query
        required: true
        schema:
          type: string
          title: Dataset
      - name: symbols
        in: query
        required: true
        schema:
          type: string
          title: Symbols
      - name: schema
        in: query
        required: true
        schema:
          type: string
          title: Schema
      - name: encoding
        in: query
        required: true
        schema:
          type: string
          title: Encoding
      - name: start
        in: query
        required: true
        schema:
          type: string
          title: Start
      - name: end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: End
      - name: stype_in
        in: query
        required: false
        schema:
          type: string
          default: raw_symbol
          title: Stype In
      - name: stype_out
        in: query
        required: false
        schema:
          type: string
          default: instrument_id
          title: Stype Out
      - name: compression
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Compression
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Limit
      - name: pretty_px
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Pretty Px
      - name: pretty_ts
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Pretty Ts
      - name: map_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Map Symbols
      - name: split_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Split Symbols
      - name: split_duration
        in: query
        required: false
        schema:
          type: string
          default: day
          title: Split Duration
      - name: split_size
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Split Size
      - name: packaging
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Packaging
      - name: delivery
        in: query
        required: false
        schema:
          type: string
          default: download
          title: Delivery
      - name: symbol
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Symbol
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      - name: user-agent
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User-Agent
      responses:
        '200':
          description: Successful request (all symbols resolve)
          content:
            application/json:
              schema: {}
        '206':
          description: Successful request (with partial symbol resolution)
        '400':
          description: If bad or unacceptable query param
        '401':
          description: If user authentication fails
        '402':
          description: If insufficient funds
        '403':
          description: If user does not have sufficient permissions
        '404':
          description: If no data found for request
        '422':
          description: If unprocessable request
        '429':
          description: If request rate limit exceeded
    get:
      tags:
      - Batch
      summary: List Batch Jobs With Auth Token
      operationId: list_batch_jobs_with_auth_token_v0_batch_me_get
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: query
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 500
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '403':
          description: If user does not have sufficient permissions
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch.submit_job:
    post:
      tags:
      - Batch
      summary: Submit Batch Request With Basic Auth
      operationId: submit_batch_request_with_basic_auth_v0_batch_submit_job_post
      security:
      - HTTPBasic: []
      parameters:
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      - name: user-agent
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User-Agent
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_submit_batch_request_with_basic_auth_v0_batch_submit_job_post'
      responses:
        '200':
          description: Successful request (all symbols resolve)
          content:
            application/json:
              schema: {}
        '206':
          description: Successful request (with partial symbol resolution)
        '400':
          description: If bad or unacceptable query param
        '401':
          description: If user authentication fails
        '402':
          description: If insufficient funds
        '404':
          description: If no data found for request
        '422':
          description: If unprocessable request, or no data found for request
        '429':
          description: If request rate limit exceeded
  /v0/batch.list_jobs:
    get:
      tags:
      - Batch
      summary: List Batch Jobs
      operationId: list_batch_jobs_v0_batch_list_jobs_get
      parameters:
      - name: states
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: States
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
      - name: short
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Short
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '404':
          description: If no data found for request
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/progress/{job_id}:
    get:
      tags:
      - Batch
      summary: Get Job Progress By Id
      operationId: get_job_progress_by_id_v0_batch_progress__job_id__get
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '403':
          description: If user does not have sufficient permissions
        '404':
          description: If job ID not found
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/files/{job_id}:
    get:
      tags:
      - Batch
      summary: Get Batch Files For Job
      operationId: get_batch_files_for_job_v0_batch_files__job_id__get
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 100
          title: Limit
      - name: protocol
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Protocol
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '403':
          description: If user does not have sufficient permissions
        '429':
          description: If request rate limit exceeded
        '501':
          description: Unsupported delivery method
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch.list_files:
    get:
      tags:
      - Batch
      summary: List Batch Job Files With Basic Auth
      operationId: list_batch_job_files_with_basic_auth_v0_batch_list_files_get
      security:
      - HTTPBasic: []
      parameters:
      - name: job_id
        in: query
        required: true
        schema:
          type: string
          title: Job Id
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchFileDetails'
                title: Response List Batch Job Files With Basic Auth V0 Batch List Files Get
        '401':
          description: If user authentication fails
        '404':
          description: If job file not found
        '410':
          description: If job files are no longer available
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/me/job_description/{job_id}:
    get:
      tags:
      - Batch
      summary: Get Job Description By Id
      operationId: get_job_description_by_id_v0_batch_me_job_description__job_id__get
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: instrument_name
        in: query
        required: true
        schema:
          type: boolean
          title: Instrument Name
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobDescription'
        '401':
          description: If user authentication fails
        '403':
          description: If user does not have sufficient permissions
        '404':
          description: If job ID not found
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/me/download/{job_id}/{filename}:
    get:
      tags:
      - Batch
      summary: Download Batch File With Token Auth
      operationId: download_batch_file_with_token_auth_v0_batch_me_download__job_id___filename__get
      security:
      - OAuth2PasswordBearerWithCookie: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '403':
          description: If user does not have sufficient permissions
        '404':
          description: If job file not found
        '410':
          description: If job files are no longer available
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch.download:
    get:
      tags:
      - Batch
      summary: Download Batch Zip
      operationId: download_batch_zip_v0_batch_download_get
      parameters:
      - name: job_id
        in: query
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '404':
          description: If job file not found
        '410':
          description: If job files are no longer available
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/download/{user_id}/{job_id}/{filename}:
    get:
      tags:
      - Batch
      summary: Download Batch File With Basic Auth
      operationId: download_batch_file_with_basic_auth_v0_batch_download__user_id___job_id___filename__get
      security:
      - HTTPBasic: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: filename
        in: path
        required: true
        schema:
          type: string
          title: Filename
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '401':
          description: If user authentication fails
        '404':
          description: If job file not found
        '410':
          description: If job files are no longer available
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/display:
    get:
      tags:
      - Batch
      summary: Get Batch Job Display Mappings
      operationId: get_batch_job_display_mappings_v0_batch_display_get
      parameters:
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '429':
          description: If request rate limit exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/quote_job:
    post:
      tags:
      - Batch
      summary: Quote Batch Request
      operationId: quote_batch_request_v0_batch_quote_job_post
      parameters:
      - name: dataset
        in: query
        required: true
        schema:
          type: string
          title: Dataset
      - name: symbols
        in: query
        required: true
        schema:
          type: string
          title: Symbols
      - name: schema
        in: query
        required: true
        schema:
          type: string
          title: Schema
      - name: encoding
        in: query
        required: true
        schema:
          type: string
          title: Encoding
      - name: start
        in: query
        required: true
        schema:
          type: string
          title: Start
      - name: end
        in: query
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: End
      - name: stype_in
        in: query
        required: false
        schema:
          type: string
          default: raw_symbol
          title: Stype In
      - name: stype_out
        in: query
        required: false
        schema:
          type: string
          default: instrument_id
          title: Stype Out
      - name: compression
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Compression
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Limit
      - name: split_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Split Symbols
      - name: split_duration
        in: query
        required: false
        schema:
          type: string
          default: day
          title: Split Duration
      - name: split_size
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Split Size
      - name: packaging
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Packaging
      - name: map_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Map Symbols
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchQuoteJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v0/batch/quote_user_job:
    post:
      tags:
      - Batch
      summary: Quote User Batch Request
      operationId: quote_user_batch_request_v0_batch_quote_user_job_post
      parameters:
      - name: dataset
        in: query
        required: true
        schema:
          type: string
          title: Dataset
      - name: symbols
        in: query
        required: true
        schema:
          type: string
          title: Symbols
      - name: schema
        in: query
        required: true
        schema:
          type: string
          title: Schema
      - name: encoding
        in: query
        required: true
        schema:
          type: string
          title: Encoding
      - name: start
        in: query
        required: true
        schema:
          type: string
          title: Start
      - name: end
        in: query
        required: true
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: End
      - name: stype_in
        in: query
        required: false
        schema:
          type: string
          default: raw_symbol
          title: Stype In
      - name: stype_out
        in: query
        required: false
        schema:
          type: string
          default: instrument_id
          title: Stype Out
      - name: compression
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Compression
      - name: limit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Limit
      - name: split_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Split Symbols
      - name: split_duration
        in: query
        required: false
        schema:
          type: string
          default: day
          title: Split Duration
      - name: split_size
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Split Size
      - name: packaging
        in: query
        required: false
        schema:
          type: string
          default: none
          title: Packaging
      - name: map_symbols
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Map Symbols
      - name: retry
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Retry
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchQuoteJobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
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'
    NotFound:
      description: The requested resource was not found.
      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.
    InstrumentDescription:
      properties:
        symbol:
          type: string
          title: Symbol
        display_symbol:
          type: string
          title: Display Symbol
        instrument_name:
          type: string
          title: Instrument Name
        asset_class:
          anyOf:
          - type: string
          - type: 'null'
          title: Asset Class
        security_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Security Type
          default: raw_symbol
        dataset_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataset Id
        dataset_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Dataset Name
        publisher:
          anyOf:
          - type: string
          - type: 'null'
          title: Publisher
        first_seen:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: First Seen
        last_seen:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Last Seen
      type: object
      required:
      - symbol
      - display_symbol
      - instrument_name
      title: InstrumentDescription
    BatchQuoteJobResponse:
      properties:
        estimated_size:
          type: integer
          title: Estimated Size
        estimated_cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Estimated Cost Usd
        net_estimated_cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Net Estimated Cost Usd
        standard_plan_cost_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Standard Plan Cost Usd
        estimated_file_count:
          type: integer
          title: Estimated File Count
        warnings:
          items:
            type: string
          type: array
          title: Warnings
        errors:
          items:
            type: string
          type: array
          title: Errors
        can_submit:
          type: boolean
          title: Can Submit
      type: object
      required:
      - estimated_size
      - estimated_cost_usd
      - net_estimated_cost_usd
      - standard_plan_cost_usd
      - estimated_file_count
      - warnings
      - errors
      - can_submit
      title: BatchQuoteJobResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BatchJobDescription:
      properties:
        dataset:
          type: string
          title: Dataset
        symbols:
          items:
            type: string
          type: array
          title: Symbols
        stype_in:
          type: string
          title: Stype In
        stype_out:
          type: string
          title: Stype Out
        schema_name:
          type: string
          title: Schema Name
        start:
          type: integer
          title: Start
        end:
          type: integer
          title: End
        encoding:
          type: string
          title: Encoding
        delivery:
          type: string
          title: Delivery
        compression:
          type: string
          title: Compression
        pretty_px:
          type: boolean
          title: Pretty Px
          default: false
        pretty_ts:
          type: boolean
          title: Pretty Ts
          default: false
        map_symbols:
          type: boolean
          title: Map Symbols
          default: false
        split_symbols:
          type: boolean
          title: Split Symbols
          default: false
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          title

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/databento/refs/heads/main/openapi/databento-batch-api-openapi.yml