Filter entity lists

Filters narrow the list down to just entities that meet a particular condition--specifically, a particular value for a particular attribute.
A list of filters are set using the filter parameter, formatted like this: filter=attribute:value,attribute2:value2. Examples:
Filters are case-insensitive.

Logical expressions

Inequality

For numerical filters, use the less-than (<) and greater-than (>) symbols to filter by inequalities. Example:
Some attributes have special filters that act as syntactic sugar around commonly-expressed inequalities: for example, the from_publication_date filter on works. See the endpoint-specific documentation below for more information. Example:

Negation (NOT)

You can negate any filter, numerical or otherwise, by prepending the exclamation mark symbol (!) to the filter value. Example:

Intersection (AND)

By default, the returned result set includes only records that satisfy all the supplied filters. In other words, filters are combined as an AND query. Example:
You can repeat a filter to create an AND query within a single attribute. Example:

Addition (OR)

Use the pipe symbol (|) to input lists of values such that any of the values can be satisfied--in other words, when you separate filter values with a pipe, they'll be combined as an OR query. Example:
This is particularly useful when you want to retrieve a many records by ID all at once. Instead of making a whole bunch of singleton calls in a loop, you can make one call, like this:
You can combine up to 50 values for a given filter in this way.
You can use OR for values within a given filter, but not between different filters. So this, for example, doesn't work and will return an error:

/works filters

/works attribute filters

You can filter using these attributes of the Work entity object (click each one to view their documentation on the Work entity page):

/works convenience filters

These filters aren't attributes of the Work entity object, but they're handy for solving some common use cases:

display_name.search (alias: title.search)

Value: a search string
Returns: works whosedisplay_name (title) includes the given string; see the search filter for details.
For most cases, you should use the search parameter instead of this filter, because it uses a better search algorithm and searches over abstracts as well as titles.

abstract.search

Value: a search string
Returns: works whose abstract includes the given string. See the search filter for details on the search algorithm used.

fulltext.search

Value: a search string
Returns: works whose fulltext includes the given string. Fulltext search is powered by an index of word sequences called n-grams - see Get N-grams for coverage details.

raw_affiliation_string.search

Value: a search string
Returns: works that have at least one raw_affiliation_string which includes the given string. See the search filter for details on the search algorithm used.

has_abstract

Value: a Boolean (true or false)
Returns: works that have or lack an abstract, depending on the given value.

has_doi

Value: a Boolean (true or false)
Returns: works that have or lack a DOI, depending on the given value. It's especially useful for grouping.

has_orcid

Value: a Boolean (true or false)
Returns: if true it returns works where at least one author or has an ORCID ID. If false, it returns works where no authors have an ORCID ID. This is based on the orcid field within authorships.author.

has_pmid

Value: a Boolean (true or false)
Returns: works that have or lack a PubMed identifier (pmid), depending on the given value.

has_pmcid

Value: a Boolean (true or false)
Returns: works that have or lack a PubMed Central identifier (pmcid) depending on the given value.

has_ngrams

Value: a Boolean (true or false)
Returns: works for which n-grams are available or unavailable, depending on the given value. N-grams power fulltext searches through the fulltext.search filter and the search parameter.

has_references

Value: a Boolean (true or false)
Returns: works that have or lack referenced_works, depending on the given value.

cites

Value: the OpenAlex ID for a given work
Returns: works that cite the given work. This is works that have the given OpenAlex ID in the referenced_works section. You can think of this as incoming citations.
The number of results returned by this filter may be slightly higher than the work'scited_by_countdue to a timing lag in updating that field.

cited_by

Value: the OpenAlex ID for a given work
Returns: works found in the given work's referenced_works section. You can think of this as outgoing citations.
Value: the OpenAlex ID for a given work
Returns: works found in the given work's related_works section.

from_publication_date

Value: a date, formatted as yyyy-mm-dd
Returns: works with publication_date greater than or equal to the given date.

to_publication_date

Value: a date, formatted as yyyy-mm-dd
Returns: works with publication_date less than or equal to the given date.

has_oa_accepted_or_published_version

Value: a Boolean (true or false)
Returns: works with at least one host_venue or alternate_host_venue where is_oa= true and version is acceptedVersion or publishedVersion. For Works that undergo peer review, like journal articles, this means there is a peer-reviewed OA copy somewhere. For some items, like books, a published version doesn't imply peer review, so they aren't quite synonymous.

has_oa_submitted_version

Value: a Boolean (true or false)
Returns: works with at least one host_venue or alternate_host_venue where is_oa= true and version is submittedVersion. This is useful for finding works with preprints deposited somewhere.

authorships.institutions.continent (alias: institutions.continent)

Value: a String with a valid continent filter
Returns: works where at least one of the author's institutions is in the chosen continent (read more).

authorships.institutions.is_global_south (alias: institutions.is_global_south)

Value: a Boolean (true or false)
Returns: works where at least one of the author's institutions is in the Global South (read more).

repository

Value: the OpenAlex ID for a given venue
Returns: works where the chosen venue ID exists within the host_venue or the alternate_host_venues objects.
You can use this to find works where authors are associated with your university, but the work is not part of the university's repository.
👏

version

Value: a String with value publishedVersion, submittedVersion, acceptedVersion, or null
Returns: works where the chosen version exists within the host_venue or the alternate_host_venues objects. If null, it returns works where no version is found in either location.

authors_count

Value: an Integer
Returns: works with the chosen number of authorships objects (authors). You can use the inequality filter to select a range, such as authors_count:>5.

concepts_count

Value: an Integer
Returns: works with the chosen number of concepts.

/authors filters

/authors attribute filters

You can filter using these attributes of the Author entity object (click each one to view their documentation on the Author entity page):

/authors convenience filters

These filters aren't attributes of the Author entity object, but they're included to address some common use cases:

display_name.search

Value: a search string
Returns: Authors whose display_name contains the given string; see the search filter for details.
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.

has_orcid

Value: a Boolean (true or false)
Returns: authors that have or lack an orcid, depending on the given value.

last_known_institution.continent

Value: a String with a valid continent filter
Returns: authors where where the last known institution is in the chosen continent (read more).

last_known_institution.is_global_south

Value: a Boolean (true or false)
Returns: works where at least one of the author's institutions is in the Global South (read more).

/venues filters

/venues attribute filters

You can filter using these attributes of the Venue entity object (click each one to view their documentation on the Venue entity page):

/venues convenience filters

These filters aren't attributes of the Venue entity object, but they're included to address some common use cases:

display_name.search

Value: a search string
Returns: venues with a display_name containing the given string; see the search filter for details.
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.

has_issn

Value: a Boolean (true or false)
Returns: venues that have or lack an ISSN, depending on the given value.

continent

Value: a String with a valid continent filter
Returns: venues that are associated with the chosen continent (read more).

is_global_south

Value: a Boolean (true or false)
Returns: venues that are associated with the Global South (read more).

/institutions filters

/institutions attribute filters

You can filter using these attributes of the Institution entity object (click each one to view their documentation on the Institution entity page):

/institutions convenience filters

These filters aren't attributes of the Institution entity object, but they're included to address some common use cases:

display_name.search

Value: a search string
Returns: institutions with a display_name containing the given string; see the search filter for details.
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.

has_ror

Value: a Boolean (true or false)
Returns: institutions that have or lack a ROR ID, depending on the given value.

continent

Value: a String with a valid continent filter
Returns: institutions that are located in the chosen continent (read more).

is_global_south

Value: a Boolean (true or false)
Returns: institutions that are located in the Global South (read more).

/concepts filters

/concepts attribute filters

You can filter using these attributes of the Concept entity object ((click each one to view their documentation on the Concept entity page):

/concepts convenience filters

These filters aren't attributes of the Concept entity object, but they're included to address some common use cases:

display_name.search

Value: a search string
Returns: concepts with a display_name containing the given string; see the search filter for details.
In most cases, you should use the search parameter instead of this filter because it uses a better search algorithm.

has_wikidata

Value: a Boolean (true or false)
Returns: concepts that have or lack a Wikidata ID, depending on the given value. For now, all concepts in OpenAlex do have Wikidata IDs.