zhongwei/gh-nice-wolf-studio-wolf-skills-marketplace-integrations
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
gh-nice-wolf-studio-wolf-sk…/skills/databento/references/api-parameters.md
Zhongwei Li d6cdda3f30 Initial commit
2025-11-30 08:43:40 +08:00

10 KiB
Raw Permalink Blame History

Databento API Parameters Reference

Complete parameter reference for all Databento MCP tools with accepted values, formats, and requirements.

Date and Time Formats

Date Format

Accepted formats:

  • YYYY-MM-DD (e.g., "2024-01-15")
  • ISO 8601 with time (e.g., "2024-01-15T14:30:00Z")

Important:

  • Dates are in UTC timezone
  • Inclusive for start, exclusive for end
  • Time portion is optional

Timestamp Format

Accepted formats:

  • ISO 8601 string: "2024-01-15T14:30:00Z"
  • Unix timestamp (seconds): 1705329000
  • Unix timestamp (nanoseconds): 1705329000000000000

Schema Parameter

Valid schema values for historical data requests.

OHLCV Schemas

"ohlcv-1s"   # 1-second bars
"ohlcv-1m"   # 1-minute bars
"ohlcv-1h"   # 1-hour bars
"ohlcv-1d"   # Daily bars
"ohlcv-eod"  # End-of-day bars

Trade and Quote Schemas

"trades"     # Individual trades
"mbp-1"      # Market by price - level 1 (top of book)
"mbp-10"     # Market by price - 10 levels of depth
"mbo"        # Market by order - level 3 (order-level)
"tbbo"       # Top of book best bid/offer

Metadata Schemas

"definition"   # Instrument definitions and metadata
"statistics"   # Market statistics
"status"       # Trading status changes
"imbalance"    # Order imbalance data

Usage:

# timeseries_get_range
schema="ohlcv-1h"

# batch_submit_job
schema="trades"

Symbology Type (stype) Parameter

Used for symbol input and output format specification.

stype_in (Input Symbol Type)

"raw_symbol"     # Native exchange symbols (ESH5, AAPL)
"instrument_id"  # Databento numeric IDs
"continuous"     # Continuous contracts (ES.c.0)
"parent"         # Parent symbols (ES, NQ)
"nasdaq"         # Nasdaq symbology
"cms"            # CMS symbology
"bats"           # BATS symbology
"smart"          # Smart routing symbols

stype_out (Output Symbol Type)

Same values as stype_in.

Common Patterns:

# Continuous to instrument_id (most common)
stype_in="continuous"
stype_out="instrument_id"

# Raw symbol to instrument_id
stype_in="raw_symbol"
stype_out="instrument_id"

# Continuous to raw symbol (see current contract)
stype_in="continuous"
stype_out="raw_symbol"

Important: Always match stype_in to your actual symbol format:

  • "ES.c.0" → stype_in="continuous"
  • "ESH5" → stype_in="raw_symbol"
  • 123456 → stype_in="instrument_id"

Dataset Parameter

Dataset codes identify the data source and venue.

Common Datasets

Futures (CME):

"GLBX.MDP3"    # CME Globex - ES, NQ, and other CME futures

Equities:

"XNAS.ITCH"    # Nasdaq - all Nasdaq-listed stocks
"XNYS.PILLAR"  # NYSE - NYSE-listed stocks
"XCHI.PILLAR"  # Chicago Stock Exchange
"BATS.PITCH"   # BATS exchange
"IEXG.TOPS"    # IEX exchange

Options:

"OPRA.PILLAR"  # US equity options

Crypto:

"DBEQ.BASIC"   # Databento equities (subset)

Usage:

# ES/NQ futures
dataset="GLBX.MDP3"

# Nasdaq equities
dataset="XNAS.ITCH"

Symbols Parameter

Format Variations

String (comma-separated):

symbols="ES.c.0,NQ.c.0,GC.c.0"

Array:

symbols=["ES.c.0", "NQ.c.0", "GC.c.0"]

Single symbol:

symbols="ES.c.0"
# or
symbols=["ES.c.0"]

Limits

  • Maximum: 2000 symbols per request
  • Must match stype_in format

Symbol Wildcards

Some endpoints support wildcards:

"ES*"    # All ES contracts
"*"      # All instruments (use with caution)

Encoding Parameter (Batch Jobs)

Output format for batch download jobs.

"dbn"    # Databento Binary (native format, most efficient)
"csv"    # Comma-separated values
"json"   # JSON format

Recommendations:

  • "dbn" - Best for large datasets, fastest processing
  • "csv" - Good for spreadsheet analysis
  • "json" - Good for custom parsing, human-readable

Usage:

# batch_submit_job
encoding="dbn"

Compression Parameter (Batch Jobs)

Compression algorithm for batch downloads.

"zstd"   # Zstandard (default, best compression)
"gzip"   # Gzip (widely supported)
"none"   # No compression

Recommendations:

  • "zstd" - Best compression ratio, fastest
  • "gzip" - Good compatibility
  • "none" - Only for small datasets or testing

Usage:

# batch_submit_job
compression="zstd"

Limit Parameter

Maximum number of records to return.

Default: 100 (varies by tool) Maximum: No hard limit, but consider:

  • Timeseries: practical limit ~10M records
  • Batch jobs: unlimited but affects processing time

Usage:

# timeseries_get_range
limit=1000  # Return up to 1000 records

Important: For large datasets, use batch jobs instead of increasing limit.

Timeframe Parameter (get_historical_bars)

Specific to the get_historical_bars convenience tool.

"1h"   # 1-hour bars
"H4"   # 4-hour bars (alternative notation)
"1d"   # Daily bars

Usage:

# get_historical_bars (ES/NQ only)
timeframe="1h"
count=100

Symbol Parameter (get_futures_quote)

Specific to the get_futures_quote tool.

"ES"   # E-mini S&P 500
"NQ"   # E-mini Nasdaq-100

Usage:

# get_futures_quote
symbol="ES"

Note: Uses root symbol only, not full contract code.

Split Parameters (Batch Jobs)

Control how batch job output files are split.

split_duration

"day"      # One file per day
"week"     # One file per week
"month"    # One file per month
"none"     # Single file (default)

split_size

split_size=1000000000  # Split at 1GB
split_size=5000000000  # Split at 5GB

split_symbols

split_symbols=True   # One file per symbol
split_symbols=False  # All symbols in same file (default)

Usage:

# batch_submit_job
split_duration="day"      # Daily files
split_symbols=True        # Separate file per symbol

Filter Parameters

State Filter (list_jobs)

states=["received", "queued", "processing", "done", "expired"]

Time Filter (list_jobs)

since="2024-01-01T00:00:00Z"  # Jobs since this timestamp

Usage:

# batch_list_jobs
states=["done", "processing"]
since="2024-01-01"

Mode Parameter (get_cost)

Query mode for cost estimation.

"historical"             # Historical data (default)
"historical-streaming"   # Streaming historical
"live"                   # Live data

Usage:

# metadata_get_cost
mode="historical"

Complete Parameter Examples

timeseries_get_range

{
    "dataset": "GLBX.MDP3",
    "symbols": "ES.c.0,NQ.c.0",
    "schema": "ohlcv-1h",
    "start": "2024-01-01",
    "end": "2024-01-31",
    "stype_in": "continuous",
    "stype_out": "instrument_id",
    "limit": 1000
}

batch_submit_job

{
    "dataset": "GLBX.MDP3",
    "symbols": ["ES.c.0", "NQ.c.0"],
    "schema": "trades",
    "start": "2024-01-01",
    "end": "2024-12-31",
    "stype_in": "continuous",
    "stype_out": "instrument_id",
    "encoding": "dbn",
    "compression": "zstd",
    "split_duration": "day",
    "split_symbols": False
}

symbology_resolve

{
    "dataset": "GLBX.MDP3",
    "symbols": ["ES.c.0", "NQ.c.0"],
    "stype_in": "continuous",
    "stype_out": "instrument_id",
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
}

metadata_get_cost

{
    "dataset": "GLBX.MDP3",
    "start": "2024-01-01",
    "end": "2024-01-31",
    "symbols": "ES.c.0",
    "schema": "ohlcv-1h",
    "stype_in": "continuous",
    "mode": "historical"
}

get_futures_quote

{
    "symbol": "ES"  # or "NQ"
}

get_session_info

{
    "timestamp": "2024-01-15T14:30:00Z"  # Optional
}

get_historical_bars

{
    "symbol": "ES",  # or "NQ"
    "timeframe": "1h",
    "count": 100
}

Common Parameter Mistakes

1. Wrong stype_in for Symbol Format

Wrong:

symbols="ES.c.0"
stype_in="raw_symbol"  # WRONG!

Correct:

symbols="ES.c.0"
stype_in="continuous"

2. Date Format Errors

Wrong:

start="01/15/2024"      # US date format - WRONG
start="15-01-2024"      # Non-ISO format - WRONG

Correct:

start="2024-01-15"      # ISO format - CORRECT

3. Missing Required Parameters

Wrong:

# metadata_get_cost
dataset="GLBX.MDP3"
start="2024-01-01"
# Missing symbols and schema!

Correct:

dataset="GLBX.MDP3"
start="2024-01-01"
symbols="ES.c.0"
schema="ohlcv-1h"

4. Schema Typos

Wrong:

schema="OHLCV-1H"       # Wrong case
schema="ohlcv-1hour"    # Wrong format
schema="ohlcv_1h"       # Wrong separator

Correct:

schema="ohlcv-1h"       # Lowercase, hyphenated

5. Symbol Array vs String Confusion

Wrong:

# batch_submit_job expects array
symbols="ES.c.0,NQ.c.0"  # WRONG for batch jobs

Correct:

# batch_submit_job
symbols=["ES.c.0", "NQ.c.0"]  # CORRECT

6. Encoding/Compression Not Strings

Wrong:

encoding=dbn        # Not a string
compression=zstd    # Not a string

Correct:

encoding="dbn"
compression="zstd"

Parameter Validation Checklist

Before making API calls, verify:

  • Date format is YYYY-MM-DD or ISO 8601
  • Dataset matches your data source (GLBX.MDP3 for ES/NQ)
  • Schema is valid and lowercase
  • stype_in matches symbol format
  • Symbols parameter matches tool expectation (string vs array)
  • All required parameters are present
  • Enum values are exact strings (case-sensitive)
  • start_date <= end_date
  • limit is reasonable for dataset size

Quick Reference: Required Parameters

timeseries_get_range

Required: dataset, symbols, schema, start

Optional: end, stype_in, stype_out, limit

batch_submit_job

Required: dataset, symbols, schema, start

Optional: end, stype_in, stype_out, encoding, compression, split_duration, split_size, split_symbols, limit

symbology_resolve

Required: dataset, symbols, stype_in, stype_out, start_date

Optional: end_date

metadata_get_cost

Required: dataset, start

Optional: end, symbols, schema, stype_in, mode

get_futures_quote

Required: symbol

get_session_info

Optional: timestamp

get_historical_bars

Required: symbol, timeframe, count

Reference in New Issue View Git Blame Copy Permalink