references/semantic-scholar.md
Semantic Scholar API
Semantic Scholar indexes 200M+ papers across all academic fields with AI-powered features: citation context, influential citations, TLDRs, and paper recommendations.
Base URLs
https://api.semanticscholar.org/graph/v1 (Academic Graph)
https://api.semanticscholar.org/recommendations/v1 (Recommendations)
Authentication
- Without key: Shared rate pool (frequently hits 429 errors). Works but unreliable.
- With key: 1 req/sec per key (higher on request).
- Header:
x-api-key: YOUR_KEY - Get a free key at: https://www.semanticscholar.org/product/api#api-key-form
The fields Parameter
Almost every endpoint accepts fields -- a comma-separated list (no spaces) of fields to include. Paper endpoints default to paperId + title; author endpoints default to authorId + name. Supported nested fields vary by endpoint.
Paper fields:
paperId, corpusId, externalIds, url, title, abstract, venue, publicationVenue, year, referenceCount, citationCount, influentialCitationCount, isOpenAccess, openAccessPdf, fieldsOfStudy, s2FieldsOfStudy, publicationTypes, publicationDate, journal, authors, citations, references, tldr, embedding
Author fields:
authorId, externalIds, url, name, affiliations, homepage, paperCount, citationCount, hIndex, papers
Paper ID Formats
The {paper_id} parameter accepts:
649def34f8be52c8b66281af98ae884c09aef38b(S2 hash)CorpusId:215416146DOI:10.1038/s41586-021-03819-2ARXIV:2005.14165PMID:19872477PMCID:2323736ACL:W12-3903
Key Endpoints
1. Paper search (relevance)
GET /graph/v1/paper/search?query={text}&fields={fields}&offset={n}&limit={n}
| Parameter | Default | Description |
|-----------|---------|-------------|
| query | required | Plain-text search |
| fields | paperId,title | Comma-separated |
| offset | 0 | Pagination start |
| limit | 100 | Max 100 |
| year | -- | 2019 or 2016-2020 |
| publicationDateOrYear | -- | YYYY-MM-DD:YYYY-MM-DD |
| fieldsOfStudy | -- | e.g., Computer Science,Medicine |
| publicationTypes | -- | e.g., JournalArticle,Conference |
| openAccessPdf | -- | Filter for OA papers |
| minCitationCount | -- | Minimum citations |
| venue | -- | Comma-separated venues |
Max 1,000 results accessible via offset.
Example:
https://api.semanticscholar.org/graph/v1/paper/search?query=CRISPR+gene+therapy&fields=title,year,abstract,citationCount,authors,openAccessPdf&limit=10&year=2023-2024
2. Paper bulk search (boolean queries, large result sets)
GET /graph/v1/paper/search/bulk?query={text}&fields={fields}&sort={field}:{order}&token={token}
- Supports boolean operators:
+(AND),|(OR),-(NOT),"..."(phrase),*(wildcard),()(grouping) - Token-based pagination (up to 10M papers)
- Returns up to 1,000 per call in
data; thetotalis an estimate. Followtokenuntil absent, rather than reconciling an estimated count as exact. - Nested citations/references are unavailable in bulk search; fetch those through their dedicated endpoints.
- Sortable:
citationCount:desc,publicationDate:desc,paperId:asc
3. Paper details (by ID)
GET /graph/v1/paper/{paper_id}?fields={fields}
Example:
https://api.semanticscholar.org/graph/v1/paper/DOI:10.1038/s41586-021-03819-2?fields=title,year,abstract,citationCount,referenceCount,isOpenAccess,openAccessPdf,authors,tldr
Response:
{
"paperId": "dc32a984b651256a8ec282be52310e6bd33d9815",
"title": "Highly accurate protein structure prediction with AlphaFold",
"year": 2021,
"citationCount": 34260,
"isOpenAccess": true,
"openAccessPdf": {"url": "https://...pdf", "status": "HYBRID"},
"tldr": {"text": "This work develops AlphaFold, a system that..."},
"authors": [{"authorId": "47921134", "name": "J. Jumper"}, ...]
}
4. Paper citations
GET /graph/v1/paper/{paper_id}/citations?fields={fields}&offset={n}&limit={n}
Returns data[].citingPaper with edge fields alongside the paper. limit max 1000. Pass response next as the next offset; stop when next is absent.
Citation-specific fields: contexts, intents, isInfluential
5. Paper references
GET /graph/v1/paper/{paper_id}/references?fields={fields}&offset={n}&limit={n}
Returns data[].citedPaper (opposite direction from citations). Same pagination as citations; unresolved paper IDs or optional fields can be null.
6. Paper title match
GET /graph/v1/paper/search/match?query={exact title}&fields={fields}
Returns the best match in data[], including matchScore; it is not a bare paper object. HTTP 404 if no match. Check title, author, and year before treating a fuzzy title match as identity.
7. Author search
GET /graph/v1/author/search?query={name}&fields={fields}&offset={n}&limit={n}
8. Author details
GET /graph/v1/author/{author_id}?fields={fields}
9. Author's papers
GET /graph/v1/author/{author_id}/papers?fields={fields}&offset={n}&limit={n}
10. Paper recommendations
GET /recommendations/v1/papers/forpaper/{paper_id}?fields={fields}&limit={n}&from={pool}
from: recent (default) or all-cs. limit defaults to 100, max 500. Both recommendation routes return recommendedPapers[], not data[]; they have no cursor pagination.
11. Multi-paper recommendations (POST)
POST /recommendations/v1/papers/
Content-Type: application/json
{
"positivePaperIds": ["paperId1", "paperId2"],
"negativePaperIds": ["paperId3"]
}
12. Paper batch (POST)
POST /graph/v1/paper/batch?fields={fields}
Content-Type: application/json
{"ids": ["DOI:10.1038/nature12373", "ARXIV:2005.14165"]}
Max 500 IDs per request. The response is an ordered array, with null entries possible for unresolved IDs. Keep positional correspondence and report missing items. fields belongs in the URL, not the JSON body.
Pagination
| Endpoint | Max per page | Max total | Method | |----------|-------------|-----------|--------| | Relevance search | 100 | 1,000 | offset/next | | Bulk search | 1,000 | 10,000,000 | token | | Citations/References | 1,000 | all | offset/next | | Author search / author papers | 1,000 | -- | offset/next |
Publication Types
Review, JournalArticle, CaseReport, ClinicalTrial, Conference, Dataset, Editorial, LettersAndComments, MetaAnalysis, News, Study, Book, BookSection
Fields of Study
Computer Science, Medicine, Chemistry, Biology, Materials Science, Physics, Geology, Psychology, Art, History, Geography, Sociology, Business, Political Science, Economics, Philosophy, Mathematics, Engineering, Environmental Science, Agricultural and Food Sciences, Education, Law, Linguistics
Error Format
{"message": "Too Many Requests", "code": "429"}
HTTP 404 for not found, 429 for rate limit.
Official sources reviewed 2026-09-30
- https://api.semanticscholar.org/graph/v1/swagger.json
- https://api.semanticscholar.org/recommendations/v1/swagger.json