### OQL Directive Examples

Source: https://help.openalex.org/access/oql-spec.md

Examples of OQL syntax for grouping results and sampling data.

```text
works where year >= 1976 group by topic, year              (multi-dim: spec-level; the live API currently executes a single dimension)
works where … stemmed "genome editing" … sample 500
```

--------------------------------

### Install OpenAlex CLI

Source: https://help.openalex.org/access/cli.md

Install the official command-line tool using pip.

```bash
pip install openalex-official
```

--------------------------------

### Canonical OQL Formatting Example

Source: https://help.openalex.org/access/oql-spec.md

An example of a formatted OQL query demonstrating the recursive indentation and leading connective rules.

```text
works where year >= (2020)
  and title has (
    fat or obese or obesity or overweight or thin or "anti fat" or "being fat"
    or "body esteem" or "body image" or "fat ideal" or "thin ideal"
    or "weight bias"
  )
```

--------------------------------

### OQL Value Group Examples

Source: https://help.openalex.org/access/oql-spec.md

Examples of valid and invalid OQL syntax for value groups, including scalar comparisons and search groups.

```text
type is article review
```

```text
type is (article review)
```

```text
country is (us or uk)
```

```text
country is (us and uk)
```

```text
has (cancer and not mouse)
```

```text
year >= (2019 or 2020)
```

```text
retracted is (true or false)
```

```text
work is in collection (col_a or col_b)
```

```text
year is (2019 or 2020)
```

```text
title/abstract has (mental health)
```

```text
(mental health or anxiety)
```

```text
not (a or b)
```

```text
NOT(a OR b)
```

```text
x is (not a and not b)
```

```text
is not (a or b)
```

```text
language is (unknown)
```

```text
language is (en or unknown)
```

```text
is ("unknown")
```

```text
(year >= (2020) or open access is (true))
```

--------------------------------

### Boolean Logic and Precedence Examples

Source: https://help.openalex.org/access/oql-spec.md

Examples demonstrating valid and invalid boolean query structures, including the use of parentheses for grouping and case-insensitivity for operators.

```text
works where title has (apple) and title has (banana or cherry)   ✓
works where title has apple and banana or cherry       ✗ OQL_UNDELIMITED_TERM_LIST
works where title has ("a" and "b" and "c")            ✓ (pure-AND, associative)
works where title has FOO and (bar or baz)             ✓ (any case accepted on input)
```

--------------------------------

### OQL Proximity and Wildcard Syntax Examples

Source: https://help.openalex.org/access/oql-spec.md

Examples of valid and invalid proximity and wildcard expressions in OQL. Note that wildcards require quoted operands to trigger exact search.

```text
works where title has (within 3 ("smart", "phone"))     ✓ exact list proximity → .search.exact, value "smart"~3~"phone"
works where title has (within 3 (smart, phone))         ✓ stemmed list proximity → .search
works where title has (within 3 ("foo", "bar", "baz"))  ✓ K-ary proximity (3+ operands)
works where title has (within 3 ("smart", "phone*"))    ✓ wildcard in a quoted operand
works where title has ("foo*bar")                       ✓ mid-word * (quoted = no-stem .search.exact)
works where title has ("wom?n")                         ✓ ? = exactly one char (quoted = no-stem)
works where title has bar*                              ✗ OQL_WILDCARD_NEEDS_EXACT (bare = stemmed = wrong)
works where title has *cycle                            ✗ OQL_LEADING_WILDCARD
works where title has ab*                               ✗ OQL_SHORT_WILDCARD_PREFIX (need ≥3)
works where title has "smart phone" within 3 words      ✗ OQL_PROXIMITY_SUFFIX_REMOVED (write it BEFORE the terms)
works where title has within 3 (smart*, phone)          ✗ OQL_WILDCARD_NEEDS_EXACT (quote a wildcard operand)
works where title has within 3 ("only")                 ✗ OQL_PROXIMITY_NEEDS_OPERANDS (need 2+)
works where title has within 3 (foo, "bar")             ✗ OQL_PROXIMITY_MIXED_OPERANDS (all bare or all quoted)
```

--------------------------------

### GET /

Source: https://help.openalex.org/access/oql.md

Execute an OQL query against the OpenAlex API root.

```APIDOC
## GET /

### Description
Executes an OQL query to retrieve data from OpenAlex. The query string is passed as a URL parameter to the API root.

### Method
GET

### Endpoint
https://api.openalex.org/

### Parameters
#### Query Parameters
- **oql** (string) - Required - The OQL query string (e.g., "works where title has (climate change)")

### Request Example
https://api.openalex.org/?oql=works%20where%20title%20has%20(%22climate%20change%22)%20and%20year%20%3E%3D%20(2020)
```

--------------------------------

### Example REST API Queries

Source: https://help.openalex.org/access/url.md

Demonstrates basic URL construction for searching and filtering works.

```text
https://api.openalex.org/works?search=microplastics&sort=cited_by_count:desc
https://api.openalex.org/works?filter=type:book,from_publication_date:2024-01-01
```

--------------------------------

### Initial Author Partition Structure

Source: https://help.openalex.org/access/sync.md

Example of the initial directory structure for authors partitioned by updated_date.

```text
/data/jsonl/authors/
├── manifest.json
└── updated_date=2024-01-01 [1000 Authors]
```

--------------------------------

### GET /topics

Source: https://help.openalex.org/openapi.json

Get a list of topics with optional filtering, searching, sorting, and pagination.

```APIDOC
## GET /topics

### Description
Get a list of topics with optional filtering, searching, sorting, and pagination. Topics are research areas automatically assigned to works.

### Method
GET

### Endpoint
/topics

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter topics. Examples: `domain.id:1`, `field.id:17`, `subfield.id:1702`, `works_count:>1000`
- **sort** (string) - Optional - Sort by: `works_count`, `cited_by_count`. Prefix with `-` for descending.
- **group_by** (string) - Optional - Group by: `domain.id`, `field.id`, `subfield.id`

### Response
#### Success Response (200)
- **TopicsListResponse** (object) - Successful response
```

--------------------------------

### Common Error Examples

Source: https://help.openalex.org/api/errors.md

Examples of common HTTP error responses encountered when interacting with the API.

```text
400 Bad Request
"Invalid filter: publication_year:abc"
```

```text
400 Bad Request
"Unknown filter field: author_name"
```

```text
429 Too Many Requests
"Rate limit exceeded"
```

```text
404 Not Found
"Work W9999999999 not found"
```

--------------------------------

### Row-subject verb phrase examples

Source: https://help.openalex.org/access/oql-spec.md

Examples of OQL syntax for citation and relationship filtering using row-subject verb phrases.

```text
works where it cites (W123 [Some title…])                          (outgoing edge -> filter=referenced_works:W123)
works where it's cited by (W456 […])                               (incoming edge -> filter=cited_by:W456)
works where it's related to (W789 […])                             (related works -> filter=related_to:W789)
works where title has (foo) and it cites (not W123 or W456)        (composes anywhere; value-level not)
```

--------------------------------

### Execute OQL via GET

Source: https://help.openalex.org/api/oql.md

Basic usage of the OQL parameter at the API root.

```http
https://api.openalex.org/?oql=works where year is (2020)
```

```bash
curl -G "https://api.openalex.org/" \
  --data-urlencode "oql=works where title has (cancer) and year >= (2020)" \
  --data-urlencode "per-page=5"
```

--------------------------------

### GET /topics

Source: https://help.openalex.org/openapi.json

List topics.

```APIDOC
## GET /topics

### Description
List topics.

### Method
GET

### Endpoint
/topics
```

--------------------------------

### GET /funders

Source: https://help.openalex.org/openapi.json

Get a list of funders with optional filtering, searching, sorting, and pagination.

```APIDOC
## GET /funders

### Description
Get a list of funders with optional filtering, searching, sorting, and pagination.

### Method
GET

### Endpoint
/funders

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter funders. Examples: `country_code:US`, `is_global_south:true`, `continent:Q46`
- **sort** (string) - Optional - Sort by: `works_count`, `cited_by_count`, `awards_count`. Prefix with `-` for descending.
- **group_by** (string) - Optional - Group by: `country_code`, `continent`, `is_global_south`

### Response
#### Success Response (200)
- **FundersListResponse** (object) - Successful response
```

--------------------------------

### View CLI output structure

Source: https://help.openalex.org/access/cli.md

Example directory structure showing how metadata and content files are saved.

```text
output/
├── W2741809807.json     # metadata (always saved)
├── W2741809807.pdf      # content (if --content pdf)
├── W2741809807.tei.xml  # content (if --content xml)
└── W1234567890.json
```

--------------------------------

### Translate Queries via GET

Source: https://help.openalex.org/api/oql.md

Translates different query formats into others using the /query endpoint via GET requests.

```bash
curl "https://api.openalex.org/query/oql/works%20where%20year%20is%20(2020)"
curl "https://api.openalex.org/query/oxurl/works?filter=publication_year:2020"
curl "https://api.openalex.org/query/oqo/%7B%22get_rows%22%3A%22works%22%7D"
```

--------------------------------

### Download files using cURL

Source: https://help.openalex.org/access/fulltext.md

Command-line examples for downloading PDF or TEI XML files.

```bash
curl "https://content.openalex.org/works/W3038568908.pdf?api_key=YOUR_KEY"
```

```bash
curl "https://content.openalex.org/works/W3038568908.grobid-xml?api_key=YOUR_KEY"
```

--------------------------------

### GET /sources

Source: https://help.openalex.org/openapi.json

Get a list of sources (journals, repositories, conferences) with optional filtering, searching, sorting, and pagination.

```APIDOC
## GET /sources

### Description
Get a list of sources (journals, repositories, conferences) with optional filtering, searching, sorting, and pagination.

### Method
GET

### Endpoint
/sources

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter sources. Examples: `is_oa:true`, `is_in_doaj:true`, `type:journal`, `country_code:US`, `host_organization:P4310320595`
- **sort** (string) - Optional - Sort by: `works_count`, `cited_by_count`, `summary_stats.h_index`. Prefix with `-` for descending.
- **group_by** (string) - Optional - Group by: `type`, `country_code`, `is_oa`, `is_in_doaj`
```

--------------------------------

### GET /?oql=

Source: https://help.openalex.org/api/oql.md

Executes an OQL query provided as a URL-encoded string at the API root.

```APIDOC
## GET /?oql=

### Description
Executes an OQL query string. The query must specify the entity (e.g., 'works where...').

### Method
GET

### Endpoint
/?oql={oql_string}

### Parameters
#### Query Parameters
- **oql** (string) - Required - The URL-encoded OQL query string.
- **per-page** (integer) - Optional - Number of results per page.
- **page** (integer) - Optional - Page number.
- **cursor** (string) - Optional - Cursor for deep paging.
- **sort** (string) - Optional - Sorting criteria (e.g., 'column:direction').
- **select** (string) - Optional - Comma-separated list of fields to project.
- **api_key** (string) - Optional - API key for authentication.
```

--------------------------------

### Query Manifest with DuckDB

Source: https://help.openalex.org/access/fulltext.md

Example of querying the Parquet manifest files directly using DuckDB.

```python
import duckdb

# Look up one work
duckdb.sql("""
  SELECT * FROM '_manifest/content_index/*.parquet'
  WHERE openalex_id = 'W2741809807'
""")
```

--------------------------------

### Cursor Paging Initialization

Source: https://help.openalex.org/api/paging.md

Initial request to start cursor-based pagination by setting the cursor parameter to an asterisk.

```bash
https://api.openalex.org/works?filter=publication_year:2020&per_page=100&cursor=*
```

--------------------------------

### OQL error reporting examples

Source: https://help.openalex.org/access/oql.md

Common syntax errors and their corresponding OQL corrections.

```text
title contains (cancer) -> title has (cancer)
title has (bar*) -> title has ("bar*")
type is (article review) -> type is (article or review)
pub_year is (2020) -> year
```

--------------------------------

### Execute OQO via GET

Source: https://help.openalex.org/api/oql.md

Send a JSON-formatted OpenAlex Query Object (OQO) as a URL-encoded parameter.

```bash
curl -G "https://api.openalex.org/" \
  --data-urlencode 'oqo={"get_rows": "works", "filter_rows": [{"column_id": "publication_year", "value": 2020}]}' \
  --data-urlencode "per-page=1"
```

--------------------------------

### Example per-entity manifest file

Source: https://help.openalex.org/access/snapshot.md

A JSON manifest file indicating the completion of data for a specific entity.

```json
{
  "date": "2026-06-25",
  "format": "jsonl",
  "entity": "works",
  "record_count": 510372821,
  "content_length": 665688383258,
  "files": [
    {
      "url": "s3://openalex/data/jsonl/works/updated_date=2026-06-24/part_0000.gz",
      "meta": { "content_length": 936733, "record_count": 499 }
    }
  ]
}
```

--------------------------------

### Negation Syntax Example

Source: https://help.openalex.org/access/oql-spec.md

Demonstrates the use of the 'not' keyword to negate specific terms within a query.

```text
works where title has covid and abstract has not pediatric
```

--------------------------------

### Filtering Sources by Works Count

Source: https://help.openalex.org/api/filtering.md

Example of filtering sources based on the number of works hosted.

```bash
curl "https://api.openalex.org/sources?filter=works_count:>1000"
```

--------------------------------

### Filtering Works by Type

Source: https://help.openalex.org/api/filtering.md

Example of filtering works based on their publication type.

```bash
curl "https://api.openalex.org/works?filter=type:book"
```

--------------------------------

### Request all aboutness data via GET

Source: https://help.openalex.org/api/tag-aboutness.md

Submit a title to the /text endpoint to retrieve both keywords and concepts.

```bash
GET https://api.openalex.org/text?title=type%201%20diabetes%20research%20for%20children
```

--------------------------------

### Autocomplete Response Example

Source: https://help.openalex.org/api/autocomplete.md

A sample JSON response structure returned by the autocomplete endpoint.

```json
{
  "meta": {
    "count": 183,
    "db_response_time_ms": 5,
    "page": 1,
    "per_page": 10
  },
  "results": [
    {
      "id": "https://openalex.org/I33213144",
      "display_name": "University of Florida",
      "hint": "Gainesville, USA",
      "cited_by_count": 17190001,
      "entity_type": "institution",
      "external_id": "https://ror.org/02y3ad647"
    }
  ]
}
```

--------------------------------

### Perform a Filtered List Request

Source: https://help.openalex.org/api

Example of querying works with specific filters and pagination using cURL.

```bash
curl "https://api.openalex.org/works?filter=publication_year:2024,is_oa:true&per_page=10&api_key=YOUR_KEY"
```

--------------------------------

### Access CLI help

Source: https://help.openalex.org/access/cli.md

Display all available options and advanced usage instructions.

```bash
openalex download --help
```

--------------------------------

### Example API response with selected fields

Source: https://help.openalex.org/api/selecting-fields.md

The JSON structure returned when specific fields are requested.

```json
{
  "results": [
    {
      "id": "https://openalex.org/W1775749144",
      "doi": "https://doi.org/10.1016/s0021-9258(19)52451-6",
      "display_name": "PROTEIN MEASUREMENT WITH THE FOLIN PHENOL REAGENT"
    },
    {
      "id": "https://openalex.org/W2100837269",
      "doi": "https://doi.org/10.1038/227680a0",
      "display_name": "Cleavage of Structural Proteins during the Assembly of the Head of Bacteriophage T4"
    }
  ]
}
```

--------------------------------

### GET /sdgs

Source: https://help.openalex.org/data/sdgs.md

Retrieves the full list of 17 Sustainable Development Goals.

```APIDOC
## GET /sdgs

### Description
Returns the complete list of 17 Sustainable Development Goals.

### Method
GET

### Endpoint
https://api.openalex.org/sdgs
```

--------------------------------

### GET /query/spec

Source: https://help.openalex.org/api/oql.md

Provides an index of the specification artifacts that power the OQL documentation.

```APIDOC
## GET /query/spec

### Description
Returns an index of spec artifacts including the cheat sheet, guide, spec, OQO schema, and grammar.

### Method
GET

### Endpoint
/query/spec
```

--------------------------------

### GET /topics/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single topic by OpenAlex ID.

```APIDOC
## GET /topics/{id}

### Description
Retrieve a single topic by OpenAlex ID.

### Method
GET

### Endpoint
/topics/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., T12419)

### Response
#### Success Response (200)
- **Topic** (object) - Successful response
```

--------------------------------

### Execute and Translate OQL Queries

Source: https://help.openalex.org/api/oql.md

Examples for running OQL queries via GET/POST and translating between formats without execution.

```bash
# Run an OQL query (the API root, not /works — the query names its own entity):
curl -G "https://api.openalex.org/" --data-urlencode "oql=works where year is (2020)"

# Translate a query between forms without running it:
curl "https://api.openalex.org/query/oql/works%20where%20year%20is%20(2020)"

# Long query? POST it — no length limit:
curl -X POST "https://api.openalex.org/" \
  -H "Content-Type: application/json" \
  -d '{"oql": "works where year is (2020)"}'
```

--------------------------------

### Filter works with available content

Source: https://help.openalex.org/access/fulltext.md

API query examples to identify works that have downloadable content.

```text
# Works with PDFs from 2024
https://api.openalex.org/works?filter=has_content.pdf:true,publication_year:2024

# CC-BY works with PDFs
https://api.openalex.org/works?filter=has_content.pdf:true,best_oa_location.license:cc-by
```

--------------------------------

### GET /keywords/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single keyword by its OpenAlex ID.

```APIDOC
## GET /keywords/{id}

### Description
Retrieve a single keyword by OpenAlex ID.

### Method
GET

### Endpoint
/keywords/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., K12345)

### Response
#### Success Response (200)
- **Keyword** (object) - Successful response
```

--------------------------------

### Batch-fetching by ID

Source: https://help.openalex.org/how-to/api-recipes.md

Examples for retrieving multiple records in a single request using the OR operator.

```text
# Multiple works by DOI
https://api.openalex.org/works?filter=doi:https://doi.org/10.1234/a|https://doi.org/10.1234/b&per_page=100

# Multiple authors by ORCID
https://api.openalex.org/authors?filter=orcid:0000-0001-2345-6789|0000-0002-3456-7890&per_page=100
```

--------------------------------

### GET /licenses

Source: https://help.openalex.org/data/licenses.md

Retrieves the complete list of all 14 licenses recognized by OpenAlex.

```APIDOC
## GET /licenses

### Description
Returns a list of all licenses recognized by OpenAlex.

### Method
GET

### Endpoint
https://api.openalex.org/licenses
```

--------------------------------

### Request keywords via GET

Source: https://help.openalex.org/api/tag-aboutness.md

Submit a title to the /text/keywords endpoint to retrieve associated keywords.

```bash
GET https://api.openalex.org/text/keywords?title=type%201%20diabetes%20research%20for%20children
```

--------------------------------

### GET /text

Source: https://help.openalex.org/api/tag-aboutness.md

Retrieves both keywords and concepts for the provided text in a single request.

```APIDOC
## GET /text

### Description
Returns both keywords and concepts for the provided text.

### Method
GET

### Endpoint
https://api.openalex.org/text

### Parameters
#### Query Parameters
- **title** (string) - Required - The title of the text to analyze.
- **abstract** (string) - Optional - The abstract of the text to analyze.

### Response
#### Success Response (200)
- **meta** (object) - Contains counts for keywords and concepts.
- **keywords** (array) - List of keyword objects.
- **concepts** (array) - List of concept objects.
```

--------------------------------

### GET /changefiles

Source: https://help.openalex.org/openapi.json

List all available changefile dates. Each date has downloadable files containing every entity record that was created or modified on that day.

```APIDOC
## GET /changefiles

### Description
List all available changefile dates. Requires a paid plan.

### Method
GET

### Endpoint
/changefiles

### Response
#### Success Response (200)
- **meta** (object) - Metadata containing count of available dates
- **results** (array) - List of available changefile dates
```

--------------------------------

### Rate Limit Headers

Source: https://help.openalex.org/api/errors.md

Example of the HTTP headers returned by the API to track rate limit usage.

```text
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 8766
X-RateLimit-Credits-Used: 1
X-RateLimit-Reset: 43200
```

--------------------------------

### GET /works?search.exact={query}

Source: https://help.openalex.org/api/searching.md

Performs an exact, unstemmed text search.

```APIDOC
## GET /works?search.exact={query}

### Description
Performs a search without stemming or stop word removal.

### Method
GET

### Endpoint
/works?search.exact={query}

### Parameters
#### Query Parameters
- **search.exact** (string) - Required - The exact text query to search for.

### Request Example
https://api.openalex.org/works?search.exact=surgery
```

--------------------------------

### GET /properties

Source: https://help.openalex.org/api/oql.md

Retrieves the registry of queryable columns, their supported operators, and their OQL names.

```APIDOC
## GET /properties

### Description
Access the registry of queryable columns and their metadata.

### Method
GET

### Endpoint
/properties or /properties/<entity>
```

--------------------------------

### Collection response schema

Source: https://help.openalex.org/api/collections.md

Example JSON response structure for a collection listing request.

```json
{
  "meta": {
    "page": 1, "per_page": 25, "total_count": 3, "total_pages": 1
  },
  "results": [
    {
      "id": "col_beNWUTw6qY",
      "user_id": "user-TSamuHxDbnhn",
      "entity_type": "works",
      "display_name": "My altmetrics papers",
      "description": "Papers I'm tracking for the altmetrics review",
      "entity_count": 4,
      "created_at": "2026-05-20T16:00:00",
      "updated_at": "2026-05-26T14:00:00"
    }
  ]
}
```

--------------------------------

### Download a single format

Source: https://help.openalex.org/tutorials/download-the-snapshot.md

Sync only the JSONL or Parquet data folders to your local machine.

```bash
# JSON Lines only
aws s3 sync "s3://openalex/data/jsonl" "openalex-snapshot/data/jsonl" --no-sign-request

# Parquet only
aws s3 sync "s3://openalex/data/parquet" "openalex-snapshot/data/parquet" --no-sign-request
```

--------------------------------

### Updated Author Partition Structure

Source: https://help.openalex.org/access/sync.md

Example of the directory structure after records have been updated and moved to a new partition.

```text
/data/jsonl/authors/
├── manifest.json
├── updated_date=2024-01-01 [950 Authors]
└── updated_date=2024-01-15 [100 Authors]
```

--------------------------------

### Basic Paging Request

Source: https://help.openalex.org/api/paging.md

Example of requesting a specific page with a defined number of results per page.

```bash
# Page 2 with 100 results per page
https://api.openalex.org/works?page=2&per_page=100
```

--------------------------------

### GET /sources/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single source by OpenAlex ID or ISSN.

```APIDOC
## GET /sources/{id}

### Description
Retrieve a single source by OpenAlex ID or ISSN.

### Method
GET

### Endpoint
/sources/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., S1983995261) or ISSN
```

--------------------------------

### Example API response

Source: https://help.openalex.org/api/tag-aboutness.md

The JSON structure returned by the /text endpoint containing metadata, keywords, and concepts.

```json
{
  "meta": {
    "keywords_count": 5,
    "concepts_count": 3
  },
  "keywords": [
    {
      "id": "https://openalex.org/keywords/type-1-diabetes",
      "display_name": "Type 1 Diabetes",
      "score": 0.677
    }
  ],
  "concepts": [
    {
      "id": "https://openalex.org/C71924100",
      "display_name": "Medicine",
      "score": 0.85
    }
  ]
}
```

--------------------------------

### GET /authors/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single author by OpenAlex ID or ORCID.

```APIDOC
## GET /authors/{id}

### Description
Retrieve a single author by OpenAlex ID or ORCID.

### Method
GET

### Endpoint
/authors/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., A5023888391) or ORCID
```

--------------------------------

### Authenticate OQL Requests

Source: https://help.openalex.org/api/oql.md

Demonstrates how to include an API key in an OQL request using the Authorization header.

```bash
curl -G "https://api.openalex.org/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "oql=works where year is (2020)"
```

--------------------------------

### GET /countries

Source: https://help.openalex.org/data/countries.md

Retrieve a list of all countries.

```APIDOC
## GET /countries

### Description
Retrieve a list of all countries available in the system.

### Method
GET

### Endpoint
https://api.openalex.org/countries
```

--------------------------------

### ID Lookup Examples

Source: https://help.openalex.org/api/autocomplete.md

Autocomplete can directly match specific entity IDs such as ORCIDs or OpenAlex IDs.

```bash
# Find author by ORCID
https://api.openalex.org/autocomplete?q=https://orcid.org/0000-0002-7436-3176

# Find source by OpenAlex ID
https://api.openalex.org/autocomplete/sources?q=S49861241
```

--------------------------------

### Counting, Grouping, and Sampling

Source: https://help.openalex.org/how-to/api-recipes.md

Examples for aggregating data using group_by, generating random samples, and combining complex filters with search queries.

```text
# Works per year, all vs. open access (group_by returns counts, not works)
https://api.openalex.org/works?filter=publication_year:2020-2024&group_by=publication_year
https://api.openalex.org/works?filter=publication_year:2020-2024,open_access.is_oa:true&group_by=publication_year

# A reproducible random sample
https://api.openalex.org/works?filter=publication_year:2024&sample=100&per_page=100&seed=42

# Combine filters + search: highly-cited OA cancer articles from 2023
https://api.openalex.org/works?search=cancer&filter=publication_year:2023,type:article,open_access.is_oa:true,cited_by_count:>50&sort=-cited_by_count
```

--------------------------------

### GET /institution-types

Source: https://help.openalex.org/data/institution-types.md

Retrieve the complete list of institution types.

```APIDOC
## GET /institution-types

### Description
Returns the complete controlled vocabulary of institution types.

### Method
GET

### Endpoint
https://api.openalex.org/institution-types

### Response
#### Success Response (200)
- **results** (array) - A list of institution type objects.
```

--------------------------------

### GET /institutions

Source: https://help.openalex.org/api/llm-quick-reference.md

Retrieve institution information or search for institutions.

```APIDOC
## GET /institutions

### Description
Search for institutions.

### Method
GET

### Endpoint
/institutions

### Query Parameters
- **search** (string) - Optional - Search for institutions by name.
```

--------------------------------

### Group and sample OQL queries

Source: https://help.openalex.org/access/oql.md

Use group by to aggregate results into buckets and sample to retrieve a random subset of data.

```text
works where year >= (2020) group by topic
works where year >= (2020) group by topic, year
works where year is (2020) sample 500
```

--------------------------------

### GET /authors

Source: https://help.openalex.org/api/llm-quick-reference.md

Retrieve author information or search for authors.

```APIDOC
## GET /authors

### Description
Search for authors or retrieve author details.

### Method
GET

### Endpoint
/authors

### Query Parameters
- **search** (string) - Optional - Search for authors by name.
```

--------------------------------

### Retrieve entity using full URL or key

Source: https://help.openalex.org/api/get-single-entities.md

Demonstrates using either the full OpenAlex URL or the shorthand key for entity retrieval.

```bash
# Full URL
curl "https://api.openalex.org/works/https://openalex.org/W2741809807"

# Key only (recommended)
curl "https://api.openalex.org/works/W2741809807"
```

--------------------------------

### GET /text/concepts

Source: https://help.openalex.org/api/tag-aboutness.md

Retrieves concepts associated with the provided text.

```APIDOC
## GET /text/concepts

### Description
Returns concepts for the provided text.

### Method
GET

### Endpoint
https://api.openalex.org/text/concepts

### Parameters
#### Query Parameters
- **title** (string) - Required - The title of the text to analyze.
- **abstract** (string) - Optional - The abstract of the text to analyze.
```

--------------------------------

### GET /text/keywords

Source: https://help.openalex.org/api/tag-aboutness.md

Retrieves keywords associated with the provided text.

```APIDOC
## GET /text/keywords

### Description
Returns keywords for the provided text.

### Method
GET

### Endpoint
https://api.openalex.org/text/keywords

### Parameters
#### Query Parameters
- **title** (string) - Required - The title of the text to analyze.
- **abstract** (string) - Optional - The abstract of the text to analyze.
```

--------------------------------

### GET api.openalex.org/locations

Source: https://help.openalex.org/data/locations.md

Retrieves a list of locations directly from the OpenAlex API.

```APIDOC
## GET api.openalex.org/locations

### Description
Retrieves a list of locations. This endpoint allows for paging over location data directly.

### Method
GET

### Endpoint
api.openalex.org/locations
```

--------------------------------

### GET /topics

Source: https://help.openalex.org/data/topics.md

Retrieve a list of topics or a specific topic by ID.

```APIDOC
## GET /topics

### Description
Fetch a list of topics or a single topic by its unique ID.

### Method
GET

### Endpoint
https://api.openalex.org/topics

### Parameters
#### Path Parameters
- **id** (string) - Optional - The unique identifier for a specific topic (e.g., T11636).

### Query Parameters
- **filter** (string) - Optional - Filter topics by domain.id, field.id, subfield.id, works_count, cited_by_count, id, or display_name.
- **search** (string) - Optional - Perform full-text search on topics.
- **sort** (string) - Optional - Sort results by domain.id, field.id, subfield.id, works_count, cited_by_count, id, or display_name.
- **group_by** (string) - Optional - Group topics by hierarchy attributes.
- **page** (integer) - Optional - Page number for pagination.
```

--------------------------------

### GET /funders/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single funder by OpenAlex ID or Crossref Funder ID.

```APIDOC
## GET /funders/{id}

### Description
Retrieve a single funder by OpenAlex ID or Crossref Funder ID.

### Method
GET

### Endpoint
/funders/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., F4320306076) or Crossref Funder ID

### Response
#### Success Response (200)
- **Funder** (object) - Successful response
```

--------------------------------

### GET /subfields

Source: https://help.openalex.org/data/subfields.md

Retrieve a list of subfields or a specific subfield by ID.

```APIDOC
## GET /subfields

### Description
Fetch a list of subfields or a single subfield by ID.

### Method
GET

### Endpoint
/subfields
/subfields/{id}

### Parameters
#### Path Parameters
- **id** (string) - Optional - The unique identifier of the subfield.

#### Query Parameters
- **filter** (string) - Optional - Filter by domain.id, field.id, topics.id, works_count, cited_by_count, id, or display_name.
- **search** (string) - Optional - Perform full-text search on subfields.
- **sort** (string) - Optional - Sort results by available fields.
- **group_by** (string) - Optional - Group results by available fields.
- **page** (integer) - Optional - Page number for pagination.
```

--------------------------------

### GET /countries/{country_code}

Source: https://help.openalex.org/data/countries.md

Retrieve details for a specific country by its code.

```APIDOC
## GET /countries/{country_code}

### Description
Fetch details for a specific country using its unique country code.

### Method
GET

### Endpoint
https://api.openalex.org/countries/{country_code}

### Parameters
#### Path Parameters
- **country_code** (string) - Required - The unique code for the country (e.g., US).
```

--------------------------------

### GET /languages

Source: https://help.openalex.org/data/languages.md

Retrieve a list of all 180 languages supported by OpenAlex.

```APIDOC
## GET /languages

### Description
Returns a list of all languages tracked by OpenAlex. Use pagination parameters to retrieve the full list.

### Method
GET

### Endpoint
https://api.openalex.org/languages

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Number of results to return per page (e.g., 200 to pull all).
```

--------------------------------

### Access daily snapshot bucket

Source: https://help.openalex.org/access/snapshot.md

Use the configured profile to list or sync files from the daily snapshot bucket.

```bash
aws s3 ls s3://openalex-snapshots/full/ --profile openalex
aws s3 sync s3://openalex-snapshots/full/2026-04-29/jsonl/ ./openalex-snapshot-jsonl --profile openalex
```

--------------------------------

### GET /funders

Source: https://help.openalex.org/data/funders.md

Retrieve a list of funders or a specific funder by ID.

```APIDOC
## GET /funders

### Description
Retrieve a list of funders or a specific funder by ID. Supports filtering, searching, sorting, grouping, and paging.

### Method
GET

### Endpoint
https://api.openalex.org/funders

### Parameters
#### Path Parameters
- **funder_id** (string) - Optional - The unique identifier for a specific funder (e.g., F4320332161).
```

--------------------------------

### Browse and Download Snapshots

Source: https://help.openalex.org/tutorials/download-the-snapshot.md

Use AWS CLI commands to list available snapshots and sync specific JSONL or Parquet data folders to your local machine.

```shellscript
aws s3 ls s3://openalex-snapshots/full/ --profile openalex

aws s3 sync s3://openalex-snapshots/full/2026-04-29/jsonl/ ./openalex-snapshot-jsonl --profile openalex

aws s3 sync s3://openalex-snapshots/full/2026-04-29/parquet/ ./openalex-snapshot-parquet --profile openalex
```

--------------------------------

### GET /domains

Source: https://help.openalex.org/openapi.json

Retrieve a list of domains, which are top-level topic categories such as Life Sciences or Social Sciences.

```APIDOC
## GET /domains

### Description
Get a list of domains (top-level topic categories). There are only 4 domains: Life Sciences, Social Sciences, Physical Sciences, and Health Sciences.

### Method
GET

### Endpoint
/domains

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter domains. Examples: `id:1`, `works_count:>10000000`
- **sort** (string) - Optional - Sort by: `works_count`, `cited_by_count`. Prefix with `-` for descending.
- **group_by** (string) - Optional - Group results by a field and return counts.

### Response
#### Success Response (200)
- **DomainsListResponse** (object) - A list of domain objects.
```

--------------------------------

### GET /source-types/{id}

Source: https://help.openalex.org/data/source-types.md

Retrieves a single source type by its ID.

```APIDOC
## GET /source-types/{id}

### Description
Fetches details for a specific source type using its ID (e.g., 'journal').

### Method
GET

### Endpoint
https://api.openalex.org/source-types/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the source type (e.g., 'journal', 'repository').

### Response
#### Success Response (200)
- **id** (string) - The OpenAlex ID for this type.
- **display_name** (string) - The human-readable name of the type.
- **description** (string) - A one-line definition of the type.
- **works_count** (integer) - Total works hosted by sources of this type.
- **cited_by_count** (integer) - Total citations across all works hosted by sources of this type.
- **works_api_url** (string) - API URL to list works hosted by this source type.
- **created_date** (string) - Date the type was added.
- **updated_date** (string) - Timestamp of the last change.
```

--------------------------------

### Example Agent Prompt for OpenAlex

Source: https://help.openalex.org/access/agents.md

A sample natural language prompt for an AI agent to retrieve and format specific research data.

```text
Using the OpenAlex API, find the 25 most-cited papers about microplastics
published since 2024 and save them as a CSV with title, year, citations, and DOI.
```

--------------------------------

### GET /changefiles/{date}

Source: https://help.openalex.org/openapi.json

Retrieves details for a specific date's changefile, including entity types, record counts, and download links. Note that this endpoint requires a paid plan.

```APIDOC
## GET /changefiles/{date}

### Description
Get details for a specific date's changefile, including which entity types changed, how many records, and download links in JSONL and Parquet formats. Requires a paid plan.

### Method
GET

### Endpoint
/changefiles/{date}

### Parameters
#### Path Parameters
- **date** (string) - Required - The changefile date in YYYY-MM-DD format

### Response
#### Success Response (200)
- **meta** (object) - Metadata containing count and date
- **results** (array) - List of entity changes including entity type, record count, and download formats (jsonl, parquet)
```

--------------------------------

### GET /autocomplete/{entity_type}

Source: https://help.openalex.org/openapi.json

Fast typeahead search returning up to 10 results. Use for search-as-you-type interfaces.

```APIDOC
## GET /autocomplete/{entity_type}

### Description
Fast typeahead search returning up to 10 results. Use for search-as-you-type interfaces.

### Method
GET

### Endpoint
/autocomplete/{entity_type}

### Parameters
#### Path Parameters
- **entity_type** (string) - Required - Type of entity to search (works, authors, sources)
```

--------------------------------

### Bulk download with OpenAlex CLI

Source: https://help.openalex.org/access/fulltext.md

Commands for downloading large sets of files based on topics, licenses, or content types.

```bash
openalex download \
  --api-key YOUR_KEY \
  --output ./climate-pdfs \
  --filter "topics.id:T10325,has_content.pdf:true" \
  --content pdf
```

```bash
openalex download \
  --api-key YOUR_KEY \
  --output ./cc-pdfs \
  --filter "best_oa_location.license:cc-by,has_content.pdf:true" \
  --content pdf
```

```bash
openalex download \
  --api-key YOUR_KEY \
  --output ./my-corpus \
  --filter "topics.id:T10325,has_content.pdf:true" \
  --content pdf,xml
```

--------------------------------

### GET /text/topics

Source: https://help.openalex.org/openapi.json

Classify arbitrary text to find relevant OpenAlex topics. Note: This endpoint is deprecated.

```APIDOC
## GET /text/topics

### Description
Classify arbitrary text to find relevant OpenAlex topics. Costs $0.01 per request. This endpoint is deprecated and not recommended for new projects.

### Method
GET

### Endpoint
/text/topics

### Parameters
#### Query Parameters
- **title** (string) - Optional - Title text to classify
- **abstract** (string) - Optional - Abstract text to classify

### Response
#### Success Response (200)
- **TextClassificationResponse** (object) - Successful response
```

--------------------------------

### GET /awards

Source: https://help.openalex.org/data/awards.md

Retrieve a list of awards or a specific award by its ID.

```APIDOC
## GET /awards

### Description
Fetch a list of awards or a single award by its unique identifier. Supports filtering, searching, sorting, grouping, and pagination.

### Method
GET

### Endpoint
https://api.openalex.org/awards

### Parameters
#### Path Parameters
- **id** (string) - Optional - The unique identifier of the award (e.g., /awards/G5066037109)
```

--------------------------------

### GET /institution-types/{id}

Source: https://help.openalex.org/data/institution-types.md

Retrieve a single institution type by its ID.

```APIDOC
## GET /institution-types/{id}

### Description
Fetch details for a specific institution type.

### Method
GET

### Endpoint
https://api.openalex.org/institution-types/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the institution type (e.g., 'education').

### Response
#### Success Response (200)
- **id** (string) - The OpenAlex ID for this type.
- **display_name** (string) - The human-readable name of the type.
- **description** (string) - A one-line definition of the type.
- **works_count** (integer) - Number of works affiliated with this type.
- **cited_by_count** (integer) - Total citations for works affiliated with this type.
- **works_api_url** (string) - API URL to list works for this type.
- **created_date** (string) - Date added to OpenAlex.
- **updated_date** (string) - Timestamp of the last update.
```

--------------------------------

### GET /works/{id}

Source: https://help.openalex.org/openapi.json

Retrieve a single work by its OpenAlex ID or external ID (DOI, PMID, PMCID, MAG ID).

```APIDOC
## GET /works/{id}

### Description
Retrieve a single work by its OpenAlex ID or external ID (DOI, PMID, PMCID, MAG ID). External IDs can be passed as full URLs or URN format.

### Method
GET

### Endpoint
/works/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - OpenAlex ID (e.g., W2741809807) or external ID (DOI, PMID, PMCID, MAG)

### Response
#### Success Response (200)
- **Work** (object) - The requested work object.
```

--------------------------------

### GET /domains

Source: https://help.openalex.org/data/domains.md

Retrieve a list of all domains or a specific domain by ID.

```APIDOC
## GET /domains

### Description
Retrieve a list of all domains or a specific domain by ID. Since there are only four domains, an unfiltered request returns all of them.

### Method
GET

### Endpoint
/domains

### Parameters
#### Path Parameters
- **id** (string) - Optional - The unique identifier of the domain to retrieve.

#### Query Parameters
- **filter** (string) - Optional - Filter domains by fields.id, works_count, cited_by_count, id, or display_name.
- **search** (string) - Optional - Perform full-text matching on domain records.
- **sort** (string) - Optional - Sort results by fields.id, works_count, cited_by_count, id, or display_name.
- **group_by** (string) - Optional - Group results by fields.id, works_count, cited_by_count, id, or display_name.
- **page** (integer) - Optional - Page number for paginated results.
```

--------------------------------

### GET /authors/{id}

Source: https://help.openalex.org/data/authors.md

Fetch a single author by their unique identifier.

```APIDOC
## GET /authors/{id}

### Description
Fetch a single author by ID.

### Method
GET

### Endpoint
https://api.openalex.org/authors/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the author (e.g., A5023888391)
```

--------------------------------

### Retrieve x_query from a classic API call

Source: https://help.openalex.org/api/oql.md

Example of a classic API request and the resulting meta.x_query object containing OQL and OQO representations.

```bash
curl "https://api.openalex.org/works?filter=publication_year:2020&per-page=1"
```

```json
"meta": {
  "count": 11446647,
  "x_query": {
    "oql": "works where year is (2020)",
    "oqo": {"get_rows": "works", "filter_rows": [{"column_id": "publication_year", "value": 2020}], "per_page": 1},
    "url": "/works?filter=publication_year:2020&per-page=1"
  }
}
```

--------------------------------

### Download the snapshot with synchronization

Source: https://help.openalex.org/tutorials/download-the-snapshot.md

Uses the --delete flag to remove outdated files when updating an existing local snapshot folder.

```bash
aws s3 sync "s3://openalex" "openalex-snapshot" --no-sign-request --delete
```