gh-nice-wolf-studio-wolf-skills-marketplace-integrations/skills/databento/references/api-parameters.md

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