> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-baseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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:

```bash theme={null}
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`:

```json theme={null}
{
  "metadata_filters": {
    "sec_ticker": "AAPL"
  }
}
```

Arrays use `in`:

```json theme={null}
{
  "metadata_filters": {
    "sec_ticker": ["AAPL", "MSFT"]
  }
}
```

Operator objects use the field-specific operators listed above:

```json theme={null}
{
  "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.