{ "openapi": "3.0.1", "info": { "title": "OpenAlex Scraper — Academic Papers, Citations, Authors", "description": "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.", "version": "0.1", "x-build-id": "f73sFG9RFxbuLuU2U" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yadroo~openalex-works/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yadroo-openalex-works", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/yadroo~openalex-works/runs": { "post": { "operationId": "runs-sync-yadroo-openalex-works", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/yadroo~openalex-works/run-sync": { "post": { "operationId": "run-sync-yadroo-openalex-works", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "entity": { "title": "Entity", "enum": [ "works", "authors", "sources", "institutions", "topics", "concepts", "funders", "publishers" ], "type": "string", "description": "Which OpenAlex entity to list. Most filters below apply to works; for other entities use query, countryCodes, minCitations, ids and customFilter.", "default": "works" }, "query": { "title": "Search query", "type": "string", "description": "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": { "title": "Search in (works only)", "enum": [ "default", "title", "abstract", "titleAndAbstract", "fulltext", "keyword", "rawAffiliation", "semantic" ], "type": "string", "description": "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.", "default": "titleAndAbstract" }, "authorSearchMode": { "title": "Authors: search by (entity = authors)", "enum": [ "auto", "topic", "name" ], "type": "string", "description": "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\").", "default": "auto" }, "fromYear": { "title": "From year", "minimum": 1000, "maximum": 2100, "type": "integer", "description": "Earliest publication year (works). Set 0/empty and use fromDate for day precision.", "default": 2020 }, "toYear": { "title": "To year", "minimum": 1000, "maximum": 2100, "type": "integer", "description": "Latest publication year (works), inclusive." }, "fromDate": { "title": "From date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Earliest publication date YYYY-MM-DD (overrides fromYear)." }, "toDate": { "title": "To date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Latest publication date YYYY-MM-DD (overrides toYear)." }, "minCitations": { "title": "Min citations", "minimum": 0, "type": "integer", "description": "Only items cited at least this many times (works: cited_by_count; other entities too).", "default": 0 }, "maxCitations": { "title": "Max citations", "minimum": 0, "type": "integer", "description": "Only works cited at most this many times (e.g. 0 to find uncited recent papers)." }, "openAccessOnly": { "title": "Open access only", "type": "boolean", "description": "Only works with a free-to-read copy (is_oa:true).", "default": false }, "oaStatus": { "title": "OA status", "type": "array", "description": "Restrict works to these open-access statuses.", "items": { "type": "string", "enum": [ "diamond", "gold", "green", "hybrid", "bronze", "closed" ], "enumTitles": [ "Diamond (OA journal, no APC)", "Gold (OA journal)", "Green (repository copy)", "Hybrid (OA article in subscription journal)", "Bronze (free on publisher site, no license)", "Closed" ] } }, "types": { "title": "Work types", "type": "array", "description": "Restrict works to these types.", "items": { "type": "string", "enum": [ "article", "preprint", "review", "book", "book-chapter", "dataset", "dissertation", "report", "standard", "letter", "editorial", "erratum", "retraction", "peer-review", "reference-entry", "paratext", "libguides", "supplementary-materials", "grant", "other" ] } }, "languages": { "title": "Languages", "type": "array", "description": "ISO 639-1 codes, e.g. [\"en\",\"ru\",\"de\"].", "items": { "type": "string" } }, "countryCodes": { "title": "Author institution countries", "type": "array", "description": "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.", "items": { "type": "string" } }, "institutionIds": { "title": "Institution IDs", "type": "array", "description": "OpenAlex institution ids (I…), incl. child institutions via lineage. Find them with entity=institutions. Example: I60559429 = Nazarbayev University.", "items": { "type": "string" } }, "authorIds": { "title": "Author IDs", "type": "array", "description": "OpenAlex author ids (A…). Find them with entity=authors. Example: A5103024730 = Ashish Vaswani.", "items": { "type": "string" } }, "sourceIds": { "title": "Source (journal) IDs", "type": "array", "description": "OpenAlex source ids (S…), e.g. S137773608 = Nature. Find them with entity=sources.", "items": { "type": "string" } }, "topicIds": { "title": "Topic IDs", "type": "array", "description": "OpenAlex topic ids (T…). Find them with entity=topics.", "items": { "type": "string" } }, "funderIds": { "title": "Funder IDs", "type": "array", "description": "OpenAlex funder ids (F…), e.g. F4320306076 = NSF.", "items": { "type": "string" } }, "ids": { "title": "Entity IDs to fetch", "type": "array", "description": "Fetch specific records by OpenAlex id (W…, A…, S…, I…), up to 100 per run. Works with every entity.", "items": { "type": "string" } }, "dois": { "title": "DOIs", "type": "array", "description": "Fetch works by DOI (with or without https://doi.org/ prefix), up to 100.", "items": { "type": "string" } }, "citedBy": { "title": "Cited by work", "type": "string", "description": "Work id (W…): return the works this work cites (its reference list)." }, "cites": { "title": "Cites work", "type": "string", "description": "Work id (W…): return the works that cite this one (incoming citations)." }, "hasDoi": { "title": "Has DOI", "type": "boolean", "description": "Filter works by DOI presence (leave unset for any)." }, "hasAbstract": { "title": "Has abstract", "type": "boolean", "description": "Filter works by abstract presence (leave unset for any)." }, "excludeRetracted": { "title": "Exclude retracted", "type": "boolean", "description": "Drop retracted works.", "default": false }, "customFilter": { "title": "Custom filter", "type": "string", "description": "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": { "title": "Sort by", "enum": [ "relevance_score", "cited_by_count", "publication_date", "publication_year", "fwci", "works_count", "display_name", "created_date", "updated_date" ], "type": "string", "description": "Server-side sort. Relevance falls back to citations/works count when there is no query.", "default": "relevance_score" }, "sortOrder": { "title": "Sort order", "enum": [ "desc", "asc" ], "type": "string", "description": "Sort direction.", "default": "desc" }, "limit": { "title": "Max items", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop after this many records (cursor paging, 200 per request). Alias: maxItems.", "default": 25 }, "groupBy": { "title": "Group by (analytics mode)", "type": "string", "description": "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": { "title": "Random sample size", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Return a reproducible random sample of N matching records instead of the sorted list (seed fixed)." }, "flagCitationAnomalies": { "title": "Flag suspect citation counts", "type": "boolean", "description": "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).", "default": true }, "includeAbstract": { "title": "Include abstract", "type": "boolean", "description": "Reconstruct the abstract from OpenAlex's inverted index (works).", "default": true }, "maxAuthors": { "title": "Max authors per work", "minimum": 1, "maximum": 500, "type": "integer", "description": "Truncate author lists (authorsCount always holds the real number).", "default": 10 }, "includeAuthorDetails": { "title": "Include author details", "type": "boolean", "description": "Add authorsDetailed: id, ORCID, position, corresponding flag, institutions with ROR/country, raw affiliation strings.", "default": false }, "includeCountsByYear": { "title": "Include citations by year", "type": "boolean", "description": "Add countsByYear (last ~10 years) for works.", "default": false }, "includeReferencedWorks": { "title": "Include referenced work IDs", "type": "boolean", "description": "Add referencedWorks (list of W… ids) for citation-graph crawling.", "default": false }, "fields": { "title": "Output fields", "type": "array", "description": "Keep only these output fields, e.g. [\"id\",\"doi\",\"title\",\"year\",\"citations\"]. Empty = all.", "items": { "type": "string" } }, "mailto": { "title": "Polite-pool e-mail", "type": "string", "description": "Your e-mail for OpenAlex's polite pool (faster, more reliable). Defaults to Yadroo's." }, "apiKey": { "title": "OpenAlex API key (optional)", "type": "string", "description": "Optional OpenAlex api_key for premium/higher limits. Not required." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }