# OpenAlex Scholarly Works Scraper (`datamule/openalex-scholarly-works-scraper`) Actor

Scrape scholarly works (papers, preprints, books), authors, institutions & journals from the free public OpenAlex API. Search + filter by author, institution, concept, year, type & open-access; sort; auto-paginate. Clean columns + raw. Pay per record.

- **URL**: https://apify.com/datamule/openalex-scholarly-works-scraper.md
- **Developed by:** [Datamule](https://apify.com/datamule) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.35 / 1,000 records

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## OpenAlex Scholarly Works Scraper

Turn the free, fully-open **[OpenAlex](https://openalex.org)** catalogue into clean, paginated
dataset rows. OpenAlex is the open index of the world's scholarly research (~250M+ works,
authors, institutions and journals) that filled the gap left by Microsoft Academic Graph's
shutdown. This actor queries its **official public REST API** (`https://api.openalex.org`,
no account, no API key) and returns one tidy record per result plus the complete raw object.

Great for **literature reviews, bibliometrics, research-trend analysis, competitive
intelligence, and building scholarly datasets**.

### What it scrapes

- **Works** — papers, preprints, books, book chapters, datasets, dissertations, reviews…
  Each record has: OpenAlex id, DOI, title, publication year & date, type, language, author
  names + ids, affiliated institutions + countries, host venue (journal/repository), citation
  count, open-access status + URL, concepts/topics, referenced-works count, a reconstructed
  plain-text abstract, and a link to the OpenAlex page — plus the lossless `raw` work object.
- **Authors / Institutions / Sources** — set **What to scrape** to one of these to resolve an
  entity (name, ids, ORCID/ROR/ISSN, works & citation counts, h-index) — handy for finding the
  id to plug back into a Works query.

### How to query

- **Search term** — free text across titles/abstracts/full text (Works) or names (others).
- **Structured Works filters** — author id, institution id, concept id, source id, work type,
  year range or exact year, open-access-only. All combined server-side (AND).
- **Advanced raw filter** — any [OpenAlex filter](https://docs.openalex.org/api-entities/works/filter-works)
  expression, e.g. `cited_by_count:>100,has_doi:true`, AND-ed onto the above.
- **Sort** — e.g. `cited_by_count:desc`, `publication_date:desc`.
- **Max results** — the actor auto-paginates via OpenAlex's cursor (200/request), so this can
  be large.

#### Example input

```json
{
  "entityType": "works",
  "search": "machine learning",
  "fromYear": 2022,
  "openAccessOnly": true,
  "sort": "cited_by_count:desc",
  "maxResults": 500
}
```

Find a specific author's papers:

```json
{ "entityType": "works", "authorId": "A5105141183", "sort": "publication_date:desc" }
```

Look up an institution id:

```json
{ "entityType": "institutions", "search": "Harvard University" }
```

### Output

One dataset item per result. A no-match query returns 0 items (not an error). Every optional
column is nullable, so records from different entity types share one schema; use the `raw`
field for anything the normalized columns don't expose.

### Pricing

**Pay per result** — you're charged one event per record returned. A query that matches
nothing costs nothing.

### Notes

- Uses OpenAlex's **polite pool** via a contact email in the request; set **Contact email** to
  your address for the best service. No key required either way.
- Data © the OpenAlex project, released under **CC0**. Please cite OpenAlex where appropriate.
- Not affiliated with or endorsed by OpenAlex.

# Actor input Schema

## `entityType` (type: `string`):

Which OpenAlex entity to query. Works = scholarly outputs (papers, preprints, books, datasets…) with full author/venue/citation metadata (the primary use case). Authors / Institutions / Sources return those entities (name, ids, works & citation counts) — useful for resolving an author/institution/journal id to feed back into a works query.

## `search` (type: `string`):

Free-text search. For Works this matches the title, abstract and full text; for Authors/Institutions/Sources it matches their names. e.g. "machine learning", "CRISPR gene editing", "Harvard University". Leave empty to browse by filter/sort only.

## `workType` (type: `string`):

Restrict Works to a single OpenAlex type, e.g. article, preprint, book, book-chapter, dataset, dissertation, review, report. Leave empty for all types. Ignored for non-Works entities.

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

Only Works published on/after this year (inclusive). Combine with "To year" for a range. Ignored if "Exact publication year" is set, or for non-Works entities.

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

Only Works published on/before this year (inclusive). Ignored if "Exact publication year" is set, or for non-Works entities.

## `publicationYear` (type: `integer`):

Only Works published in exactly this year. Overrides the From/To year range when set. Ignored for non-Works entities.

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

When on, return only open-access Works (is\_oa:true). Ignored for non-Works entities.

## `authorId` (type: `string`):

Restrict Works to those by a given author. Accepts an OpenAlex author id (e.g. A5105141183 or the full https://openalex.org/A5105141183 URL). Tip: run this actor with "Authors" first to find the id. Ignored for non-Works entities.

## `institutionId` (type: `string`):

Restrict Works to those affiliated with a given institution (e.g. I136199984 for Harvard). Ignored for non-Works entities.

## `conceptId` (type: `string`):

Restrict Works tagged with a given concept/topic (e.g. C519991488). Ignored for non-Works entities.

## `sourceId` (type: `string`):

Restrict Works published in a given source — a journal or repository (e.g. S4306400194 for arXiv). Ignored for non-Works entities.

## `filter` (type: `string`):

Optional raw OpenAlex filter string, AND-ed onto the structured filters above. Use OpenAlex's own filter grammar for anything not exposed as a field, e.g. "cited\_by\_count:>100,has\_doi:true" or "authorships.countries:US". See https://docs.openalex.org/api-entities/works/filter-works. For non-Works entities this is the only structured filter input.

## `sort` (type: `string`):

How to order results, as "field:direction", e.g. "cited\_by\_count:desc" (most-cited first), "publication\_date:desc" (newest first), "works\_count:desc" (for authors/institutions). Leave empty for the default relevance order (or a plain listing when there's no search term).

## `maxResults` (type: `integer`):

Maximum number of records to return. The actor paginates automatically via OpenAlex's cursor (200 per request), so this can be large. Each returned record is one billable item.

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

Optional email address added to requests per OpenAlex's polite-pool convention for faster, more reliable service. No account or key is required. If omitted a neutral default is used.

## Actor input object example

```json
{
  "entityType": "works",
  "search": "machine learning",
  "openAccessOnly": false,
  "sort": "cited_by_count:desc",
  "maxResults": 200
}
```

# Actor output Schema

## `results` (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 = {
    "search": "machine learning",
    "sort": "cited_by_count:desc",
    "maxResults": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/openalex-scholarly-works-scraper").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 = {
    "search": "machine learning",
    "sort": "cited_by_count:desc",
    "maxResults": 200,
}

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

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

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

```

## CLI example

```bash
echo '{
  "search": "machine learning",
  "sort": "cited_by_count:desc",
  "maxResults": 200
}' |
apify call datamule/openalex-scholarly-works-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/openalex-scholarly-works-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/KdQ1EayVC2zPbpGrE/builds/KrJjSZwHFU4lCl7rf/openapi.json