# OpenAlex Scraper — Academic Papers, Citations, Authors (`yadroo/openalex-works`) Actor

Search 250M+ scholarly works via OpenAlex: title, authors and institutions, year, venue, citations count, open-access PDF link, DOI, concepts, abstract. Filter by year and citations, sort by relevance or citations. Complements arXiv. No API key.

- **URL**: https://apify.com/yadroo/openalex-works.md
- **Developed by:** [Samat Makatov](https://apify.com/yadroo) (community)
- **Categories:** AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 result items

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## OpenAlex Scholarly Search — works, authors, journals, institutions, topics with citations & open access

Query **OpenAlex**, the open index of 250M+ scholarly works from every publisher (journals, preprints, books, datasets), plus its 100M authors, 250k sources, 100k institutions, funders and topics. Filter by year/date, citations, open-access status, type, language, country, institution, author, journal, topic or funder; sort by citations, date or field-weighted impact; get counts per group (`groupBy`) for instant analytics; crawl the citation graph with `cites` / `citedBy`. Built for research analysts, tech-scouting and competitive-intel teams, grant offices, science journalists and AI agents.

No API key, no proxy, no browser — the free OpenAlex REST API (polite pool).

### Use cases

- **Expert / KOL discovery** — `entity: "authors"`, `query: "battery electrolytes"`, `countryCodes: ["DE"]`, `sortBy: "cited_by_count"` → researchers based in Germany who published on the topic since `fromYear`, most cited first, with papers on the topic (`topicWorksCount`), h-index, ORCID and current institution. (OpenAlex's own author search matches names only — the actor finds the matching papers and ranks their authors; see `authorSearchMode`.)
- **Competitive research intelligence** — `institutionIds: ["I…"]` of a competitor's lab + `fromDate` → everything they published this quarter, with topics and funders.
- **Citation alerts** — `cites: "W2741809807"` run weekly → new papers citing your key patent/paper.
- **Market-sizing of a research field** — `groupBy: "publication_year"` or `"authorships.institutions.country_code"` on a query gives publication trends and country shares in one request.
- **Journal selection / APC budgeting** — `entity: "sources"`, `query: "machine learning"`, `customFilter: "is_in_doaj:true"` → open-access journals with APC prices and h-index.
- **Literature review / RAG corpus** — `openAccessOnly: true`, `hasAbstract: true`, `fields: ["id","doi","title","abstract","pdfUrl"]`, `limit: 5000`.
- **Grant landscape** — `funderIds: ["F4320306076"]` (NSF) + topic query → funded work, corresponding authors, institutions.

### Input

All fields are optional. Provide at least a `query`, one filter, `ids`/`dois` or `sample`. Works-only filters are ignored (with a warning) for other entities.

| Field | Type | Default | Allowed values / notes |
|---|---|---|---|
| `entity` | string | `works` | `works`, `authors`, `sources`, `institutions`, `topics`, `concepts`, `funders`, `publishers` |
| `query` | string | – | Search text: stemmed, case-insensitive, `"quoted phrases"`, `AND` / `OR` / `NOT`, `-excluded`. When sorting works by anything other than relevance, a plain 2–6 word query is matched as an exact phrase (falls back to all words if no work contains the phrase); add your own quotes or operators to control matching. |
| `searchIn` | string | `titleAndAbstract` | Works (and experts by topic): `titleAndAbstract`, `title`, `abstract`, `default` (title + abstract + **full text** — broadest, but also matches papers that merely mention the words in their body), `fulltext`, `keyword`, `rawAffiliation`, `semantic` (embedding search, ranks by meaning). |
| `authorSearchMode` | string | `auto` | `entity: "authors"` + `query` only. `topic` = **experts by topic**: works matching the query (with all works filters — `fromYear`, `countryCodes`, `types`…) grouped by author, ranked by papers on the topic (`topicWorksCount`) or by the author's citations / works count via `sortBy`; `countryCodes` keeps authors whose last known institution is there; `minCitations` applies to the author; max 200 authors. `name` = OpenAlex author name search. `auto` = name search only when the query looks like a person's name that OpenAlex knows ("Ashish Vaswani"), otherwise topic. |
| `fromYear` / `toYear` | integer | `2020` / – | Publication year window (works). |
| `fromDate` / `toDate` | string | – | `YYYY-MM-DD`; overrides the year fields. |
| `minCitations` / `maxCitations` | integer | – | `cited_by_count` range. `maxCitations: 0` = uncited only. |
| `openAccessOnly` | boolean | `false` | `is_oa:true`. |
| `oaStatus` | string\[] | `[]` | `diamond`, `gold`, `green`, `hybrid`, `bronze`, `closed` |
| `types` | string\[] | `[]` | `article`, `book-chapter`, `dataset`, `preprint`, `dissertation`, `book`, `review`, `paratext`, `libguides`, `letter`, `other`, `reference-entry`, `report`, `editorial`, `peer-review`, `erratum`, `standard`, `grant`, `supplementary-materials`, `retraction` |
| `languages` | string\[] | `[]` | ISO 639-1 (`en`, `ru`, `de`, `zh`…). |
| `countryCodes` | string\[] | `[]` | ISO 3166-1 alpha-2. Works: any author affiliated there; authors: last known institution; institutions/sources/funders/publishers: own country. |
| `institutionIds` | string\[] | `[]` | `I…` ids (lineage — child institutes included). Find with `entity: "institutions"`. |
| `authorIds` | string\[] | `[]` | `A…` ids. Find with `entity: "authors"`. |
| `sourceIds` | string\[] | `[]` | `S…` ids (journal/repository), e.g. `S137773608` = Nature. |
| `topicIds` | string\[] | `[]` | `T…` ids. Find with `entity: "topics"`. |
| `funderIds` | string\[] | `[]` | `F…` ids, e.g. `F4320306076` = NSF, `F4320320879` = ERC. |
| `ids` | string\[] | `[]` | Fetch specific records by OpenAlex id (any entity), ≤100. Full URLs accepted. |
| `dois` | string\[] | `[]` | Fetch works by DOI, ≤100. |
| `cites` | string | – | `W…`: works that cite this work (incoming citations). |
| `citedBy` | string | – | `W…`: works this work cites (its reference list). |
| `hasDoi` / `hasAbstract` | boolean | – | Presence filters (unset = any). |
| `excludeRetracted` | boolean | `false` | `is_retracted:false`. |
| `customFilter` | string | – | Raw OpenAlex filter appended verbatim (see **Reference**), e.g. `primary_location.source.is_in_doaj:true,authorships.institutions.type:company`. |
| `sortBy` | string | `relevance_score` | works: `relevance_score`, `cited_by_count`, `publication_date`, `publication_year`, `fwci`, `display_name`, `created_date`, `updated_date`; other entities: `relevance_score`, `cited_by_count`, `works_count`, `display_name` (+ `level` for concepts). Relevance without a query falls back to citations / works count. |
| `sortOrder` | string | `desc` | `desc`, `asc` |
| `limit` (alias `maxItems`) | integer | `25` | 1–10 000, cursor paging 200 per request. |
| `groupBy` | string | – | Return counts per group instead of records (max 200 groups). Any filter field, e.g. `publication_year`, `type`, `oa_status`, `authorships.institutions.country_code`, `primary_location.source.id`, `primary_topic.id`, `funders.id`. |
| `sample` | integer | – | Reproducible random sample of N matching records (seed 42) instead of the sorted list. |
| `flagCitationAnomalies` | boolean | `true` | Sanity-check citation counts of up to 25 works with ≥500 citations per run (+1 cheap request each): `citationsSuspect: true` when ≥5% of the citing works were published 2+ years before the work itself — see FAQ. |
| `includeAbstract` | boolean | `true` | Rebuild the abstract from the inverted index (works). |
| `maxAuthors` | integer | `10` | Truncate author lists; `authorsCount` keeps the real number. |
| `includeAuthorDetails` | boolean | `false` | Adds `authorsDetailed` (id, ORCID, position, corresponding flag, institutions with ROR/country). |
| `includeCountsByYear` | boolean | `false` | Adds `countsByYear`. |
| `includeReferencedWorks` | boolean | `false` | Adds `referencedWorks` (W… ids) for graph crawling. |
| `fields` | string\[] | `[]` | Keep only these output fields. |
| `mailto` | string | Yadroo's | Your e-mail for the OpenAlex polite pool. |
| `apiKey` | string | – | Optional OpenAlex premium key. Never required. |

### Reference

#### Entity ids

| Prefix | Entity | Example |
|---|---|---|
| `W` | work | `W2741809807` (Attention Is All You Need) |
| `A` | author | `A5103024730` |
| `S` | source (journal / repository / conference) | `S137773608` (Nature), `S4306400194` (arXiv) |
| `I` | institution | `I136199984` (Harvard), `I185571130` (Al-Farabi KazNU) |
| `T` | topic | `T10028` (Topic Modeling) |
| `F` | funder | `F4320306076` (NSF) |
| `P` | publisher | `P4310319965` (Springer Nature) |
| `C` | concept (legacy) | `C41008148` (Computer Science) |

#### Work filters usable in `customFilter` (most common)

Syntax: `field:value`, several values `a|b` = OR, several filters separated by `,` = AND, `!value` = NOT, numbers accept `>` / `<`. Full list: https://docs.openalex.org/api-entities/works/filter-works

| Filter | Meaning |
|---|---|
| `publication_year`, `publication_date`, `from_publication_date`, `to_publication_date` | when published |
| `from_created_date`, `from_updated_date` | when OpenAlex added / updated the record (needs `apiKey` for created\_date) |
| `type`, `type_crossref`, `language`, `is_retracted`, `is_paratext` | record kind |
| `cited_by_count`, `fwci`, `citation_normalized_percentile.value`, `referenced_works_count` | impact |
| `is_oa`, `oa_status`, `open_access.any_repository_has_fulltext`, `best_oa_location.license` | open access |
| `authorships.author.id`, `authorships.author.orcid`, `authorships.is_corresponding`, `authors_count` | authors |
| `authorships.institutions.id`, `.lineage`, `.ror`, `.country_code`, `.continent`, `.type` (`education`, `company`, `government`, `healthcare`, `nonprofit`, `facility`, `archive`, `other`), `.is_global_south` | affiliations |
| `primary_location.source.id`, `.issn`, `.type` (`journal`, `repository`, `conference`, `ebook platform`, `book series`), `.is_in_doaj`, `.is_core`, `.publisher_lineage`, `.host_organization` | venue |
| `primary_topic.id`, `topics.id`, `primary_topic.subfield.id`, `.field.id`, `.domain.id`, `keywords.id`, `concepts.id` | subject |
| `funders.id`, `grants.award_id`, `sustainable_development_goals.id` | funding / SDG |
| `has_doi`, `has_pmid`, `has_pmcid`, `has_abstract`, `has_fulltext`, `has_references`, `has_orcid` | completeness |
| `ids.pmid`, `ids.openalex`, `doi`, `title.search`, `abstract.search`, `fulltext.search`, `raw_affiliation_strings.search`, `default.search` | ids and searches |
| `cites`, `cited_by`, `related_to` | graph |
| `indexed_in` (`crossref`, `pubmed`, `doaj`, `arxiv`, `datacite`), `locations_count`, `has_oa_accepted_or_published_version` | misc |

Other entities: authors — `last_known_institutions.id/.country_code`, `affiliations.institution.id`, `orcid`, `has_orcid`, `works_count`, `cited_by_count`, `summary_stats.h_index`; sources — `type`, `country_code`, `is_oa`, `is_in_doaj`, `is_core`, `apc_usd`, `host_organization`, `issn`; institutions — `country_code`, `type`, `continent`, `is_global_south`, `lineage`, `ror`; topics — `subfield.id`, `field.id`, `domain.id`; funders / publishers — `country_code`, `works_count`, `grants_count`.

#### Open-access status

| `oaStatus` | Meaning |
|---|---|
| `diamond` | OA journal without APC |
| `gold` | OA journal (usually APC) |
| `hybrid` | OA article in a subscription journal |
| `green` | free copy only in a repository |
| `bronze` | free on the publisher site, no license |
| `closed` | no free copy known |

### Examples

**Most cited recent papers on a topic (literature review starter)**

```json
{ "query": "solid-state battery electrolyte", "searchIn": "titleAndAbstract", "fromYear": 2023, "minCitations": 20, "sortBy": "cited_by_count", "limit": 100 }
```

**Who works on this in Kazakhstan — experts by topic, ranked by citations**

```json
{ "entity": "authors", "query": "wheat breeding", "countryCodes": ["KZ"], "sortBy": "cited_by_count", "limit": 50 }
```

Returns authors of KZ-affiliated papers on wheat breeding since 2020 whose last known institution is in Kazakhstan (e.g. Al-Farabi KazNU, Seifullin Agro Technical University), with `topicWorksCount`, total citations and h-index. Drop `sortBy` to rank by number of papers on the topic.

**Look up an author by name**

```json
{ "entity": "authors", "query": "Ashish Vaswani", "authorSearchMode": "name", "limit": 5 }
```

**Weekly citation alert for a key paper**

```json
{ "cites": "W2741809807", "fromDate": "2026-09-06", "sortBy": "publication_date", "limit": 200, "fields": ["id", "doi", "title", "publishedAt", "venue", "authors", "url"] }
```

**Country shares of a research field (one request, no items)**

```json
{ "query": "agentic AI", "fromYear": 2024, "groupBy": "authorships.institutions.country_code", "limit": 50 }
```

**Corporate research output this quarter (competitor intel)**

```json
{ "institutionIds": ["I1291425158"], "fromDate": "2026-07-01", "sortBy": "publication_date", "includeAuthorDetails": true, "limit": 500 }
```

**Open-access journals in a field with APC prices**

```json
{ "entity": "sources", "query": "computer vision", "customFilter": "is_in_doaj:true", "sortBy": "cited_by_count", "limit": 30 }
```

### Output

One item per record. Works example (trimmed):

```json
{
  "id": "W7211905801",
  "openalexUrl": "https://openalex.org/W7211905801",
  "doi": "10.54254/2755-2721/2026.ld28741",
  "doiUrl": "https://doi.org/10.54254/2755-2721/2026.ld28741",
  "title": "A Survey on Reinforcement Learning Optimization Methods for Multi-Agent Collaboration of Large Language Models",
  "year": 2026,
  "publishedAt": "2026-09-08",
  "type": "article",
  "language": "en",
  "venue": "Applied and Computational Engineering",
  "venueId": "S4387284237",
  "venueType": "journal",
  "publisher": "EWA Publishing",
  "authors": ["Qianling Zhang"],
  "authorsCount": 1,
  "institutions": ["Xiangtan University"],
  "countries": ["CN"],
  "correspondingAuthors": ["Qianling Zhang"],
  "citations": 0,
  "fwci": null,
  "citationPercentile": null,
  "isOpenAccess": true,
  "oaStatus": "gold",
  "pdfUrl": "https://ace.ewapub.com/article/view/36623.pdf",
  "url": "https://doi.org/10.54254/2755-2721/2026.ld28741",
  "primaryTopic": "Multi-Agent Systems and Negotiation",
  "field": "Computer Science",
  "domain": "Physical Sciences",
  "topics": ["Multi-Agent Systems and Negotiation", "Reinforcement Learning in Robotics"],
  "keywords": ["Reinforcement learning", "Multi-agent system"],
  "abstract": "Large language models (LLMs) …",
  "source": "openalex",
  "fetchedAt": "2026-09-13T08:01:05.123Z"
}
```

| Field group | Works fields |
|---|---|
| identity | `id`, `openalexUrl`, `doi`, `doiUrl`, `pmid`, `arxivId`, `title`, `type`, `typeCrossref`, `language`, `year`, `firstVersionYear` (year of the earliest arXiv/bioRxiv version merged into the record, else `year`), `publishedAt` |
| venue | `venue`, `venueId`, `venueType`, `issn`, `publisher`, `volume`, `issue`, `pages` |
| people | `authors`, `authorsCount`, `authorsTruncated`, `correspondingAuthors`, `institutions`, `countries`, optional `authorsDetailed[]` |
| impact | `citations`, `fwci`, `citationPercentile`, `isTop10Percent`, `isTop1Percent`, `referencedWorksCount`, optional `countsByYear[]`, `referencedWorks[]` |
| access | `isOpenAccess`, `oaStatus`, `pdfUrl`, `url`, `license`, `version`, `isRetracted` |
| subject | `primaryTopic`, `primaryTopicId`, `subfield`, `field`, `domain`, `topics[]`, `keywords[]`, `concepts[]`, `sdgs[]`, `funders[]` |
| text | `abstract` |
| provenance | `source`, `fetchedAt` |

Works also carry `citationsSuspect` (`true` / `false`, `null` = not checked) and `citationsPredatingWork` (citing works published 2+ years before the work's first version). Authors: `id`, `name`, `orcid`, `worksCount`, `citations`, `hIndex`, `i10Index`, `meanCitedness2y`, `lastKnownInstitutions`, `lastKnownCountry`, `lastKnownCountries`, `country`, `affiliations[]`, `topics[]`, `matchedBy` (`topic` / `name`); experts by topic add `topicWorksCount` (papers matching the query) and `topicQuery`. Sources: `name`, `type`, `issnL`, `publisher`, `country`, `worksCount`, `citations`, `hIndex`, `isOpenAccess`, `isInDoaj`, `apcUsd`, `homepage`. Institutions: `name`, `ror`, `country`, `city`, `type`, `worksCount`, `citations`, `hIndex`, `homepage`, `parentIds`. Topics: `name`, `description`, `keywords`, `subfield`, `field`, `domain`, `worksCount`. Group-by rows: `groupBy`, `key`, `keyDisplayName`, `count`, `share`.

A `SUMMARY` record in the key-value store holds the exact filter string, the first request URL and `totalMatching`.

### Use it from code / agents

```bash
curl -X POST "https://api.apify.com/v2/acts/yadroo~openalex-works/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"agentic commerce","fromYear":2024,"sortBy":"cited_by_count","limit":50}'
```

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('yadroo/openalex-works').call({ entity: 'authors', query: 'perovskite solar', countryCodes: ['DE'], limit: 50 });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

```python
from apify_client import ApifyClient
client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("yadroo/openalex-works").call(run_input={"cites": "W2741809807", "fromDate": "2026-09-01", "limit": 200})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

MCP: add `https://mcp.apify.com` to Claude / Cursor / any MCP client and call the `yadroo/openalex-works` tool with the same JSON input.

### Pricing

Pay per event: **$0.001 per run start + $0.001 per item** (a group-by row counts as an item).
Typical runs: 25-record lookup ≈ $0.026; 500-paper competitor snapshot ≈ $0.5; 50-row country breakdown ≈ $0.051.

### Limits & FAQ

- **Rate limits** — OpenAlex meters its free API: without an API key each IP gets a small daily budget (about $0.10/day of API credit in September 2026 — a search request costs $0.001, a plain filter/lookup $0.0001), ~10 requests/s. The actor pages 200 records per request with a 250 ms pause and retries 429/5xx with backoff; when the daily budget is spent it stops with a clear error — pass your own free `apiKey` for heavy use.
- **Citation counts are OpenAlex's own** (`citations` = `cited_by_count`, not remapped). OpenAlex occasionally credits another paper's citations to the wrong record — e.g. a 2023 conference paper showing 79 000 citations, 15% of them from papers written before it existed. `flagCitationAnomalies` catches this pattern (`citationsSuspect: true`) for highly cited works, measuring from the first public version so a journal record of an older arXiv preprint is not flagged; it cannot catch records where only the title is wrong (a few arXiv records carry an unrelated title but the real paper's authors and citations) — check the DOI when a result looks odd.
- **Search precision** — the default `titleAndAbstract` avoids papers that mention the words only in their body; `title` is the most precise for citation-ranked lists. `default` / `fulltext` are for recall, not for citation rankings.
- **Freshness** — OpenAlex ingests Crossref/PubMed/arXiv within days; citation counts update roughly weekly.
- **Depth** — up to 10 000 records per run via cursor paging; split bigger jobs by year or source. `ids`/`dois` take up to 100 per run (one request).
- **Abstracts** — rebuilt from OpenAlex's inverted index; ~40% of works have none (`hasAbstract: true` to filter).
- **Errors** — an invalid filter/sort fails fast with OpenAlex's own message (it lists the valid field names); unknown enum values are warned about before the request.
- **Not included** — full text, publisher paywalled PDFs; `pdfUrl` points to the best open copy when one exists.
- **Roadmap** — autocomplete helper for ids, N-gram endpoint, Semantic Scholar cross-links.

***

Made by **Yadroo**. Sibling actors: [arxiv-papers](https://apify.com/yadroo/arxiv-papers) (preprints with full category taxonomy), [wikipedia-search](https://apify.com/yadroo/wikipedia-search), [openlibrary-books](https://apify.com/yadroo/openlibrary-books), [sec-edgar-filings](https://apify.com/yadroo/sec-edgar-filings), [github-repo-intel](https://apify.com/yadroo/github-repo-intel).

# Actor input Schema

## `entity` (type: `string`):

Which OpenAlex entity to list. Most filters below apply to works; for other entities use query, countryCodes, minCitations, ids and customFilter.

## `query` (type: `string`):

Search text (stemmed, case-insensitive, supports "quoted phrases", AND/OR/NOT, -excluded). Works: matched in title + abstract by default (see searchIn); wrap multi-word topics in quotes when sorting by citations. Authors: a topic finds the experts who publish on it, a person's name finds that author (see authorSearchMode).

## `searchIn` (type: `string`):

Which field the query is matched in. Default: title and abstract. `default` adds the full text, which also matches any paper that merely mentions the words in its body (e.g. NumPy for "large language models"). `rawAffiliation` finds papers whose authors listed a given organization (e.g. a company name) — handy for competitor research.

## `authorSearchMode` (type: `string`):

OpenAlex's author search matches names only, so a topic like "battery electrolytes" finds nobody. `topic` finds the papers matching the query (with the works filters: fromYear, countryCodes…) and returns their authors ranked by number of matching papers (`topicWorksCount`), or by citations / works count via sortBy. `name` is the plain name lookup. `auto` uses name search only for a capitalised name that OpenAlex knows ("Ashish Vaswani").

## `fromYear` (type: `integer`):

Earliest publication year (works). Set 0/empty and use fromDate for day precision.

## `toYear` (type: `integer`):

Latest publication year (works), inclusive.

## `fromDate` (type: `string`):

Earliest publication date YYYY-MM-DD (overrides fromYear).

## `toDate` (type: `string`):

Latest publication date YYYY-MM-DD (overrides toYear).

## `minCitations` (type: `integer`):

Only items cited at least this many times (works: cited\_by\_count; other entities too).

## `maxCitations` (type: `integer`):

Only works cited at most this many times (e.g. 0 to find uncited recent papers).

## `openAccessOnly` (type: `boolean`):

Only works with a free-to-read copy (is\_oa:true).

## `oaStatus` (type: `array`):

Restrict works to these open-access statuses.

## `types` (type: `array`):

Restrict works to these types.

## `languages` (type: `array`):

ISO 639-1 codes, e.g. \["en","ru","de"].

## `countryCodes` (type: `array`):

ISO 3166-1 alpha-2 codes (US, KZ, DE, CN…). Works: at least one author affiliated in these countries. Institutions/sources/funders/publishers: entity country. Authors: last known institution country.

## `institutionIds` (type: `array`):

OpenAlex institution ids (I…), incl. child institutions via lineage. Find them with entity=institutions. Example: I60559429 = Nazarbayev University.

## `authorIds` (type: `array`):

OpenAlex author ids (A…). Find them with entity=authors. Example: A5103024730 = Ashish Vaswani.

## `sourceIds` (type: `array`):

OpenAlex source ids (S…), e.g. S137773608 = Nature. Find them with entity=sources.

## `topicIds` (type: `array`):

OpenAlex topic ids (T…). Find them with entity=topics.

## `funderIds` (type: `array`):

OpenAlex funder ids (F…), e.g. F4320306076 = NSF.

## `ids` (type: `array`):

Fetch specific records by OpenAlex id (W…, A…, S…, I…), up to 100 per run. Works with every entity.

## `dois` (type: `array`):

Fetch works by DOI (with or without https://doi.org/ prefix), up to 100.

## `citedBy` (type: `string`):

Work id (W…): return the works this work cites (its reference list).

## `cites` (type: `string`):

Work id (W…): return the works that cite this one (incoming citations).

## `hasDoi` (type: `boolean`):

Filter works by DOI presence (leave unset for any).

## `hasAbstract` (type: `boolean`):

Filter works by abstract presence (leave unset for any).

## `excludeRetracted` (type: `boolean`):

Drop retracted works.

## `customFilter` (type: `string`):

Raw OpenAlex filter string appended verbatim, e.g. `primary_location.source.is_in_doaj:true,authorships.institutions.type:company`. Full field list in README Reference.

## `sortBy` (type: `string`):

Server-side sort. Relevance falls back to citations/works count when there is no query.

## `sortOrder` (type: `string`):

Sort direction.

## `limit` (type: `integer`):

Stop after this many records (cursor paging, 200 per request). Alias: maxItems.

## `groupBy` (type: `string`):

Instead of records, return counts per group for the same query/filters — e.g. `publication_year` (trend), `authorships.institutions.country_code` (where research happens), `authorships.institutions.id` (top institutions), `primary_location.source.id` (top journals), `type`, `oa_status`, `primary_topic.id`, `funders.id`. Up to 200 groups per run. Any filterable field works.

## `sample` (type: `integer`):

Return a reproducible random sample of N matching records instead of the sorted list (seed fixed).

## `flagCitationAnomalies` (type: `boolean`):

OpenAlex occasionally credits one paper's citations to another record. For up to 25 works with ≥500 citations per run the actor counts citing works published 2+ years before the work's first version (arXiv/bioRxiv preprint if merged) and sets citationsSuspect=true when they are ≥5% (+1 cheap request per checked work).

## `includeAbstract` (type: `boolean`):

Reconstruct the abstract from OpenAlex's inverted index (works).

## `maxAuthors` (type: `integer`):

Truncate author lists (authorsCount always holds the real number).

## `includeAuthorDetails` (type: `boolean`):

Add authorsDetailed: id, ORCID, position, corresponding flag, institutions with ROR/country, raw affiliation strings.

## `includeCountsByYear` (type: `boolean`):

Add countsByYear (last ~10 years) for works.

## `includeReferencedWorks` (type: `boolean`):

Add referencedWorks (list of W… ids) for citation-graph crawling.

## `fields` (type: `array`):

Keep only these output fields, e.g. \["id","doi","title","year","citations"]. Empty = all.

## `mailto` (type: `string`):

Your e-mail for OpenAlex's polite pool (faster, more reliable). Defaults to Yadroo's.

## `apiKey` (type: `string`):

Optional OpenAlex api\_key for premium/higher limits. Not required.

## Actor input object example

```json
{
  "entity": "works",
  "query": "agent-based commerce trust protocol",
  "searchIn": "titleAndAbstract",
  "authorSearchMode": "auto",
  "fromYear": 2020,
  "minCitations": 0,
  "openAccessOnly": false,
  "excludeRetracted": false,
  "sortBy": "relevance_score",
  "sortOrder": "desc",
  "limit": 25,
  "flagCitationAnomalies": true,
  "includeAbstract": true,
  "maxAuthors": 10,
  "includeAuthorDetails": false,
  "includeCountsByYear": false,
  "includeReferencedWorks": false
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "agent-based commerce trust protocol"
};

// Run the Actor and wait for it to finish
const run = await client.actor("yadroo/openalex-works").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "agent-based commerce trust protocol" }

# Run the Actor and wait for it to finish
run = client.actor("yadroo/openalex-works").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "agent-based commerce trust protocol"
}' |
apify call yadroo/openalex-works --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,yadroo/openalex-works"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/U1fXxxbsetozr7pYZ/builds/f73sFG9RFxbuLuU2U/openapi.json