# OpenAlex Citation & Open-Access Works Explorer (`vexaloom-labs/openalex-citation-and-open-access-works-explorer`) Actor

Search OpenAlex's open catalog of scholarly works and authors, or pull every work tied to an author, journal/source or institution. Returns citations, open-access status, abstracts, authorships and topic tags per work.

- **URL**: https://apify.com/vexaloom-labs/openalex-citation-and-open-access-works-explorer.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Developer tools, Open source
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Citation & Open-Access Works Explorer

OpenAlex is a free, open index of scholarly works, authors, institutions and venues. This actor searches it, pulls records by ID, walks citations in either direction, and returns the evidence around open access: every OA copy, its license, and the PDF/TEI links where OpenAlex has full text. No cookies, login or proxy.

### Modes

| Mode | What it returns |
|---|---|
| `searchWorks` | Works matching a keyword/Boolean query and/or server-side filters. A query is optional when at least one filter is set, so you can browse e.g. every 2024 open-access review. |
| `getCitations` | Works that cite each seed work (forward citations). |
| `getReferences` | Works each seed work cites (backward citations / references). |
| `getCitationGraph` | Both directions for each seed, with a `citationContext` on every row. |
| `searchAuthors` | Author profiles: ORCID, works/citation counts, h-index, affiliations, topics. |
| `byWorkIds` | Fetch specific works by OpenAlex ID, DOI, PMID, PMCID or MAG ID. |
| `byAuthorIds` | Every work by an author ID or ORCID. |
| `byVenueIds` | Every work in a journal / repository / conference source ID or ISSN. |
| `byInstitutionIds` | Every work with an author affiliated to an institution ID or ROR. |

### What each work record contains

- **Identifiers:** `openalexId`, `doi`, `pmid`, `pmcid`, `magId`, `openalexUrl`
- **Bibliographic:** `title`, `publicationDate`, `publicationYear`, `type`, `language`, `biblio` (volume/issue/pages)
- **Citations:** `citedByCount`, `referencedWorksCount`, `fwci`, `citationPercentile`, `citedByPercentileYear`, `countsByYear`
- **Open access:** `isOa`, `openAccessStatus` (diamond/gold/green/hybrid/bronze/closed), `openAccessOaUrl`, `bestOaUrl`, `anyRepositoryHasFulltext`, `oaLocations[]` (every OA landing page/PDF with license, version and source), `contentUrls` (OpenAlex PDF and Grobid TEI when cached)
- **Authors:** `authorships[]` with author ID, ORCID, position, corresponding flag, raw name, institution names, institution details and countries; scalar `primaryAuthor`
- **Topics:** `primaryTopic`, `topics[]` (topic → subfield → field → domain), `keywords[]`, `sdgs[]`, plus legacy `concepts[]`
- **Abstract:** reconstructed readable text from OpenAlex's inverted index
- **Flags:** `isRetracted`, `isParatext`, `isPulled`, `isXpac`, `isTraditional`, `hasFulltext`, `hasContent`
- **Cost data:** `apcPaid`, `apcList`
- **Citation mode only:** `citationContext` (`seedWorkId`, `seedDoi`, `seedTitle`, `direction`)
- **Meta:** `recordType`, `scrapedAt`

Opt in to `referencedWorks` / `relatedWorks` ID arrays and `citedByApiUrl` with `includeCitationIds=true`.

Author rows carry `openalexId`, `name`, `fullName`, `orcid`, `worksCount`, `citedByCount`, `summaryStats` (h-index, i10-index, 2-year mean citedness), `affiliations[]`, `lastKnownInstitutions`, `topics[]`, `nameAlternatives`, `worksApiUrl`, `recordType` and `scrapedAt`.

### Inputs

| Field | Default | Notes |
|---|---|---|
| `mode` | `searchWorks` | One of the nine modes above. |
| `searchQuery` | `large language models` | Used by `searchWorks` / `searchAuthors`. OpenAlex Boolean syntax is supported. |
| `searchField` | `default` | `title`, `titleAbstractKeywords`, `titleAndAbstract`, `abstract` or `fulltext` for cheaper scoped searches. |
| `workIds` | – | Work IDs/DOIs/PMIDs for direct lookup **and** citation seeds. |
| `authorIds` / `venueIds` / `institutionIds` | – | IDs, ORCIDs, ISSNs or RORs for the matching lookup modes. |
| `citationDirection` | `both` | `citations`, `references` or `both` for `getCitationGraph`. |
| `publicationYearMin` / `publicationYearMax` | – | Server-side publication-year range. |
| `minCitedBy` | – | Server-side citation floor; `0` means no minimum. |
| `openAccessOnly` | `false` | Server-side OA filter. |
| `oaStatus` | `any` | `diamond`, `gold`, `green`, `hybrid`, `bronze` or `closed`. |
| `hasFulltextOnly` | `false` | Only works with searchable full text. |
| `workType` | `any` | Article, book, dataset, preprint, review, etc. |
| `sortBy` | `relevance_score:desc` | Citation/date/year/FWCI sorts; filter-only modes fall back to most cited. |
| `perPage` | `50` | 1–100 records per API page. |
| `startPage` | `1` | Resume page paging. Page × perPage must stay within 10,000. |
| `useCursor` | `false` | Optional cursor paging; needs the optional free API key. |
| `startCursor` | — | Cursor value to resume a cursor-paged run. |
| `customFilter` | – | Extra raw OpenAlex filter, e.g. `language:en,is_retracted:false`. |
| `includeAbstract` / `includeAuthorships` / `includeConcepts` | `true` | Toggle those blocks. |
| `includeTopics` | `true` | Current topics, keywords and SDGs. |
| `includeOpenAccessLocations` | `true` | All OA copies plus full-text links. |
| `includeCitationIds` | `false` | Referenced/related ID arrays and cited-by API URL. |
| `userAgentEmail` | `apify-actor@noreply.apify.com` | Contact address for OpenAlex's polite pool. |
| `apiKey` | empty | Optional free key from openalex.org/settings/api; never required. |
| `maxItems` | `50` | Hard cap, 1–10,000. |

Legacy saved-task keys are mapped in code, not kept in the input form: `query`/`searchTerm` → `searchQuery`, `ids`/`dois` → `workIds`, `authorId` → `authorIds`, `venueId` → `venueIds`, `institutionId` → `institutionIds`, `maxResults`/`limit` → `maxItems`, `fromYear`/`toYear` → publication-year bounds, `minCitations` → `minCitedBy`, `oaOnly`/`openAccess` → `openAccessOnly`, `type` → `workType`, `sort` → `sortBy`, `email`/`mailto` → `userAgentEmail`, `includeAbstracts` → `includeAbstract`. A legacy key wins when the new field still holds its schema default, so old tasks keep their saved limits and filters.

### Examples

Top-cited open-access 2024 articles:

```json
{
  "mode": "searchWorks",
  "searchQuery": "large language models",
  "publicationYearMin": 2024,
  "minCitedBy": 50,
  "openAccessOnly": true,
  "workType": "article",
  "sortBy": "cited_by_count:desc",
  "maxItems": 100
}
```

Forward citations of a paper:

```json
{
  "mode": "getCitations",
  "workIds": ["W2741809807"],
  "sortBy": "cited_by_count:desc",
  "maxItems": 50
}
```

Both directions with OA copies:

```json
{
  "mode": "getCitationGraph",
  "workIds": ["https://doi.org/10.7717/peerj.4375"],
  "citationDirection": "both",
  "includeOpenAccessLocations": true,
  "maxItems": 100
}
```

Browse every 2024 open-access review without a keyword:

```json
{
  "mode": "searchWorks",
  "publicationYearMin": 2024,
  "publicationYearMax": 2024,
  "openAccessOnly": true,
  "workType": "review",
  "maxItems": 200
}
```

### Pagination

Page paging is the default and needs no key. `startPage` resumes a page-paged run; the first 10,000 results are reachable. Cursor paging (`useCursor=true`) follows OpenAlex `next_cursor` values beyond that and needs the optional free API key. `startCursor` resumes a cursor-paged run. The actor stops only on `maxItems`, source exhaustion, or the cursor/page limit — never on a wall-clock timer.

### OpenAlex API budget

OpenAlex is free but its anonymous list/search calls share a small daily budget per IP. Single-record lookups (the default prefill) are free. For heavy use, add a free API key from [openalex.org/settings/api](https://openalex.org/settings/api); it raises the daily budget and enables cursor paging. The actor treats the key as optional and never requires it.

### FAQ

**Do I need an API key?** No. Everything works without one. A free key only helps with very large runs and cursor paging.

**Why is an abstract sometimes missing?** OpenAlex omits it when the publisher's license does not allow redistribution. The row still contains the work; only the `abstract` field is omitted.

**Why does the citation count differ from Google Scholar?** OpenAlex matches reference lists to records in its index. Unmatched references are left out, so counts are usually lower than a publisher PDF's reference list.

**What is `fwci`?** Field-Weighted Citation Impact: citations received divided by the field-year-type average. `1.0` is the world average.

**Why are some OA fields missing?** OpenAlex only emits OA evidence when it has found a free copy. Closed works have `isOa=false` and no OA locations; fields are omitted rather than set to null.

**Can I get the full text?** `contentUrls.pdf` and `contentUrls.grobidXml` point to OpenAlex's cached copies for works where `hasFulltext` is true; `oaLocations` lists publisher and repository copies.

**Is this affiliated with OpenAlex?** No. It is an independent third-party actor that reads OpenAlex's public API. OpenAlex is run by OurResearch.

# Actor input Schema

## `mode` (type: `string`):

Pick a search mode, a direct-lookup mode, or a citation direction.

## `searchQuery` (type: `string`):

Keyword, phrase, or OpenAlex Boolean query. Used by searchWorks and searchAuthors. In searchWorks it may be omitted when at least one filter is set (filter-only browsing).

## `searchField` (type: `string`):

Which text field the query searches. Title/abstract options are much cheaper and faster than full text.

## `workIds` (type: `array`):

Used by byWorkIds and as the citation seeds for getCitations / getReferences / getCitationGraph. Accepts OpenAlex W-IDs, DOI URLs, bare DOIs, PMIDs, PMCIDs and MAG IDs. Examples: W2741809807, https://doi.org/10.1145/3442188.3445922, pmid:25524000.

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

OpenAlex author IDs (A...) or ORCIDs, for byAuthorIds.

## `venueIds` (type: `array`):

OpenAlex source IDs (S..., journal / repository / conference) or ISSNs, for byVenueIds. Examples: S4306400194 (arXiv), S137773608 (Nature), 0028-0836.

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

OpenAlex institution IDs (I...) or ROR URLs, for byInstitutionIds. Examples: I136199984 (Harvard), I32971472 (MIT), https://ror.org/042nb2s44.

## `citationDirection` (type: `string`):

Which side of the citation graph to walk when mode is getCitationGraph.

## `publicationYearMin` (type: `integer`):

Drop works published before this year. Sent to OpenAlex as a server-side filter.

## `publicationYearMax` (type: `integer`):

Drop works published after this year. Sent to OpenAlex as a server-side filter.

## `minCitedBy` (type: `integer`):

Drop works cited fewer times than this. 0 means no minimum.

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

Only return works with a free, legal full-text copy.

## `oaStatus` (type: `string`):

Filter by OpenAlex's OA colour. Any status other than 'any' also implies open access.

## `hasFulltextOnly` (type: `boolean`):

Only works where OpenAlex has machine-readable full text.

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

Optional OpenAlex work type filter.

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

Ordering for works. Relevance requires a search query; filter-only modes fall back to most cited.

## `perPage` (type: `integer`):

How many records to request per page (1-100). Smaller pages keep the daily test cheap.

## `startPage` (type: `integer`):

Resume page-based paging from this page (1-10000 combined with perPage must stay within 10,000 results).

## `useCursor` (type: `boolean`):

Follow OpenAlex next_cursor pages instead of page numbers. Needs the optional free API key; without it the actor uses page paging.

## `startCursor` (type: `string`):

Optional saved OpenAlex cursor for a resumable cursor-paged run. Leave empty to start from the beginning.

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

Advanced: an extra OpenAlex filter expression, e.g. language:en,is_retracted:false or topics.id:T10102. Combined with the filters above.

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

Reconstruct readable abstract text from OpenAlex's inverted index. No extra API calls.

## `includeAuthorships` (type: `boolean`):

Include every author, their affiliations and corresponding-author flag.

## `includeConcepts` (type: `boolean`):

Include OpenAlex's deprecated concept tags (kept for backward compatibility). Prefer topics.

## `includeTopics` (type: `boolean`):

Include the current OpenAlex topic hierarchy, keyword tags and UN Sustainable Development Goals.

## `includeOpenAccessLocations` (type: `boolean`):

Include all OA landing pages / PDFs, licenses and the OpenAlex full-text PDF and TEI links when available.

## `includeCitationIds` (type: `boolean`):

Include referencedWorks / relatedWorks ID arrays and the citedBy API URL. Off by default because long reference lists make records large.

## `userAgentEmail` (type: `string`):

Email sent in the User-Agent so OpenAlex can contact you about API usage. The default works; supply your own for high-volume runs.

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

Optional free key from openalex.org/settings/api. Only needed for cursor paging past 10,000 results or a larger daily request budget. Never required.

## `maxItems` (type: `integer`):

Hard cap on emitted records.

## Actor input object example

```json
{
  "mode": "byWorkIds",
  "searchQuery": "large language models",
  "searchField": "default",
  "workIds": [
    "W2741809807"
  ],
  "authorIds": [],
  "venueIds": [],
  "institutionIds": [],
  "citationDirection": "both",
  "openAccessOnly": false,
  "oaStatus": "any",
  "hasFulltextOnly": false,
  "workType": "any",
  "sortBy": "relevance_score:desc",
  "perPage": 3,
  "startPage": 1,
  "useCursor": false,
  "startCursor": "",
  "customFilter": "",
  "includeAbstract": true,
  "includeAuthorships": true,
  "includeConcepts": true,
  "includeTopics": true,
  "includeOpenAccessLocations": true,
  "includeCitationIds": false,
  "userAgentEmail": "apify-actor@noreply.apify.com",
  "apiKey": "",
  "maxItems": 1
}
```

# Actor output Schema

## `works` (type: `string`):

Dataset containing scraped works (search, lookup, author/venue/institution and citation modes) and author profiles (searchAuthors).

# 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 = {
    "mode": "byWorkIds",
    "searchQuery": "large language models",
    "searchField": "default",
    "workIds": [
        "W2741809807"
    ],
    "authorIds": [],
    "venueIds": [],
    "institutionIds": [],
    "citationDirection": "both",
    "openAccessOnly": false,
    "oaStatus": "any",
    "hasFulltextOnly": false,
    "workType": "any",
    "sortBy": "relevance_score:desc",
    "perPage": 3,
    "startPage": 1,
    "useCursor": false,
    "startCursor": "",
    "customFilter": "",
    "includeAbstract": true,
    "includeAuthorships": true,
    "includeConcepts": true,
    "includeTopics": true,
    "includeOpenAccessLocations": true,
    "includeCitationIds": false,
    "userAgentEmail": "apify-actor@noreply.apify.com",
    "apiKey": "",
    "maxItems": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/openalex-citation-and-open-access-works-explorer").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 = {
    "mode": "byWorkIds",
    "searchQuery": "large language models",
    "searchField": "default",
    "workIds": ["W2741809807"],
    "authorIds": [],
    "venueIds": [],
    "institutionIds": [],
    "citationDirection": "both",
    "openAccessOnly": False,
    "oaStatus": "any",
    "hasFulltextOnly": False,
    "workType": "any",
    "sortBy": "relevance_score:desc",
    "perPage": 3,
    "startPage": 1,
    "useCursor": False,
    "startCursor": "",
    "customFilter": "",
    "includeAbstract": True,
    "includeAuthorships": True,
    "includeConcepts": True,
    "includeTopics": True,
    "includeOpenAccessLocations": True,
    "includeCitationIds": False,
    "userAgentEmail": "apify-actor@noreply.apify.com",
    "apiKey": "",
    "maxItems": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/openalex-citation-and-open-access-works-explorer").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 '{
  "mode": "byWorkIds",
  "searchQuery": "large language models",
  "searchField": "default",
  "workIds": [
    "W2741809807"
  ],
  "authorIds": [],
  "venueIds": [],
  "institutionIds": [],
  "citationDirection": "both",
  "openAccessOnly": false,
  "oaStatus": "any",
  "hasFulltextOnly": false,
  "workType": "any",
  "sortBy": "relevance_score:desc",
  "perPage": 3,
  "startPage": 1,
  "useCursor": false,
  "startCursor": "",
  "customFilter": "",
  "includeAbstract": true,
  "includeAuthorships": true,
  "includeConcepts": true,
  "includeTopics": true,
  "includeOpenAccessLocations": true,
  "includeCitationIds": false,
  "userAgentEmail": "apify-actor@noreply.apify.com",
  "apiKey": "",
  "maxItems": 1
}' |
apify call vexaloom-labs/openalex-citation-and-open-access-works-explorer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/openalex-citation-and-open-access-works-explorer"
        }
    }
}
```

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/KRVXCtklGxsJ0N9lt/builds/N7bYgi4PEsoNePL68/openapi.json
