Filtering

Narrow search results by metadata fields using the filters parameter. Two formats are supported: a simple key-value format and a structured DSL with boolean combinators. The API auto-detects the format based on top-level keys.

Operators

Operator	Description	Example value
`eq`	Equals	`"research"`
`ne`	Not equals	`"deleted"`
`in`	Matches any in list	`["tech", "science"]`
`not_in`	Excludes values in list	`["spam", "junk"]`
`gt`	Greater than	`2020`
`gte`	Greater than or equal	`2020`
`lt`	Less than	`2025`
`lte`	Less than or equal	`2025`
`between`	Range (inclusive)	`[2020, 2025]`

Simple Format

Key-value pairs where each key is a metadata field name. Supports exact match, list membership, range operators, and negation.

Exact match

Range

Any-of list

Pass an array to match any value in the list (equivalent to in).

Negation

Structured DSL

Use boolean combinators (and, or, not) with explicit field conditions for complex filtering logic. Supports arbitrary nesting.

Basic AND condition

OR condition

Nested combinators

Combinators can be nested to build complex expressions. This example matches documents from 2020-2025 that are either in one of two journals or published by SAGE.

NOT combinator

Use not to exclude results matching a condition. Like and and or, it takes an array of conditions — passing a bare object is a parse error.

Filtering by journal and article identity

issn and doi are both indexed. Prefer issn over journal when you mean a specific journal: the same journal appears in the corpus under several title spellings ("PLOS ONE", "PLOS One", "PLoS ONE"), while its ISSN does not change.

ISSN — any spelling works

Hyphenated or bare, upper- or lower-case check character. All four forms select the same journal.

DOI — case-insensitive

Excluding journals

Exclusion uses the operators you already have — ne, not_in and not. There is no separate exclusion syntax. Note that documents carrying no ISSN at all are not excluded by an issn exclusion.

Journal metrics

Filter by a journal-level citation metric. These fields accept range operators only (gt, gte, lt, lte, between) and are resolved server-side into the matching ISSNs, so they cost nothing extra at search time.

Available: journal_metric.2yr_mean_citedness, journal_metric.h_index, journal_metric.i10_index.

This is not an impact factor. The value is OpenAlex's 2-year mean citedness, published under CC0. The Journal Impact Factor is Clarivate's proprietary metric, computed over the Web of Science corpus with a different citation window; the two are not interchangeable and the numbers will not agree.

A journal the metric provider has no value for is absent from the result, not scored zero — so a lt threshold does not sweep up unrated journals.

Above a threshold

Below a threshold

Excluding by metric

The expansion is reported back

The response says exactly how many journals and ISSNs your threshold resolved to, so the selection is inspectable. The expansion is capped: a threshold matching more ISSNs than the cap returns an error rather than a truncated list, because a partial list would return confidently wrong results.

Filtering on other fields

Indexed fields are doc_id, journal, publisher, keywords, publication_date, doi, issn and curated_sets.

Filtering on any other payload field still works and is not rejected — but it is matched by scanning rather than by index, which can be slow or time out on large collections. When that happens the response carries a warning so you are not left guessing.

Date Filtering

ISO date strings (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS) are automatically detected and used for datetime range queries. No special syntax is needed -- just pass the date string as a value.

Date range with gte/lte

Date range with between

The filters parameter is part of the Search API request body. See the full endpoint reference for more details.