Metadata Filters

Discover and apply metadata filters for filing retrieval.

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.