Metadata Filters

Use GET https://api-beta.ai-baseline.xyz/v2/sandp_500/metadata-filters to inspect metadata-filter fields, value types, supported operators, bounds, and optional categorical values.

curl "https://api-beta.ai-baseline.xyz/v2/sandp_500/metadata-filters?include_values=true" \
  -H "X-API-Key: $AI_BASELINE_API_KEY"

To inspect one field:

curl "https://api-beta.ai-baseline.xyz/v2/sandp_500/metadata-filters?field=sec_ticker&include_values=true" \
  -H "X-API-Key: $AI_BASELINE_API_KEY"

Available Fields

The metadata endpoint returns the current field list. For the S&P 500 domain, supported fields include:

Field	Format	Example	Operators
`report_filing_date`	Date string, `YYYY-MM-DD`	`"2025-01-01"`	`eq`, `gte`, `lte`
`sec_fiscal_year`	Fiscal year string, `FY-YYYY`	`"FY-2025"`	`eq`, `neq`, `in`
`sec_fiscal_year_end`	SEC fiscal year-end string	`"09-27"`	`eq`, `neq`, `in`
`sec_form_type`	SEC EDGAR form type string	`"10-K"`	`eq`, `neq`, `in`
`sec_gics_sector`	GICS sector string	`"Information Technology"`	`eq`, `neq`, `in`
`sec_gics_sub_industry`	GICS sub-industry string	`"Technology Hardware, Storage & Peripherals"`	`eq`, `neq`, `in`
`sec_item_tag`	SEC Form 10-K item tag string	`"10K-Item-1A"`	`eq`, `neq`, `in`
`sec_ticker`	Primary ticker symbol string	`"AAPL"`	`eq`, `neq`, `in`

Shorthand Forms

Scalar values use eq:

{
  "metadata_filters": {
    "sec_ticker": "AAPL"
  }
}

Arrays use in:

{
  "metadata_filters": {
    "sec_ticker": ["AAPL", "MSFT"]
  }
}

Operator objects use the field-specific operators listed above:

{
  "metadata_filters": {
    "sec_ticker": "AAPL",
    "sec_form_type": ["10-K", "10-Q"],
    "sec_fiscal_year": ["FY-2024", "FY-2025"],
    "report_filing_date": {
      "gte": "2025-01-01"
    }
  }
}

Filter Semantics

Request shape	Behavior
`metadata_filters` omitted	`research` and `agentic_research` attempt to infer relevant metadata filters from the natural-language query.
`metadata_filters: null`	Same as omitted.
`metadata_filters: {}`	Same as omitted.
`metadata_filters: {...}`	Applies caller-provided metadata filters before retrieval. Values are normalized and validated. The API may also add filters inferred from the query.

Caller-provided metadata_filters are supported for research and agentic_research. basic rejects non-empty metadata filters, and basic is the default mode. If you send metadata_filters, explicitly set mode to research or agentic_research. Use metadata_filters, not filters. The legacy filters request key is rejected by request validation. Boolean expression roots such as and, or, not, and field are not part of the supported metadata filter format and return FILTER_EXPRESSION_UNSUPPORTED.

Limits

The API validates metadata filters before running the query:

Limit	Value
Maximum raw JSON body size	`65,536` bytes
Maximum query length	`4,000` normalized characters
Maximum metadata-filter conditions	`50`
Maximum values per metadata-filter condition	`100`
Maximum total metadata-filter values	`250`
Maximum metadata-filter string value length	`256` characters

Validation errors use the standard ErrorResponse envelope.

Get Started

Guides

API Reference

Available Fields

Shorthand Forms

Filter Semantics

Limits

​Available Fields

​Shorthand Forms

​Filter Semantics

​Limits

Available Fields

Shorthand Forms

Filter Semantics

Limits