semantic-scholar

name

semantic-scholar

description

Search and retrieve research paper metadata using the Semantic Scholar Academic Graph API via curl. Use this skill whenever the user wants to find academic papers, look up citations, get paper details by DOI/arXiv ID/title, explore an author's publications, or fetch reference/citation lists. Trigger on phrases like "find papers on X", "look up this paper", "how many citations does X have", "papers citing X", "search for research about X", "get metadata for arxiv:...", or any request to explore academic literature. Always use this skill when the task involves academic paper search or metadata retrieval — even if the user just pastes a DOI or arXiv link and wants info about it.

Semantic Scholar Paper Metadata Skill

Search and retrieve research paper metadata using the Semantic Scholar Academic Graph API.

Base URL: https://api.semanticscholar.org/graph/v1 Auth: No key required for basic use. For higher rate limits, get a free key at https://www.semanticscholar.org/product/api and pass it as x-api-key header.

---

Choosing the Right Endpoint

Goal	Endpoint
Search by keywords/topic	GET /paper/search
Boolean/filtered bulk search	GET /paper/search/bulk
Match by exact/near-exact title	GET /paper/search/match
Look up a specific paper (DOI, arXiv, etc.)	GET /paper/{paper_id}
Fetch multiple papers at once	POST /paper/batch
Papers that cite a paper	GET /paper/{paper_id}/citations
Papers referenced by a paper	GET /paper/{paper_id}/references
Author's papers	GET /author/{author_id}/papers

---

Field Selection

All endpoints accept a fields parameter — a comma-separated list. Default response only includes paperId and title. Always request the fields you need.

Common fields:

paperId, corpusId, externalIds, title, abstract, year, venue,
publicationDate, authors, citationCount, referenceCount,
influentialCitationCount, isOpenAccess, openAccessPdf,
fieldsOfStudy, s2FieldsOfStudy, publicationTypes

Nested fields use dot notation:

authors.name, authors.affiliations,
citations.title, citations.year, citations.authors,
references.title, references.externalIds,
openAccessPdf.url

---

Endpoint Details & curl Examples

1. Keyword Search — /paper/search

Best for: topic discovery, finding relevant papers by concept.

curl -G "https://api.semanticscholar.org/graph/v1/paper/search" \
  --data-urlencode "query=transformer attention mechanism" \
  --data-urlencode "fields=title,year,authors,citationCount,abstract" \
  --data-urlencode "limit=10"

Filters (all optional, combine freely):

--data-urlencode "year=2020-2024"               # year range
--data-urlencode "venue=NeurIPS,ICML"           # specific venues
--data-urlencode "fieldsOfStudy=Computer Science"
--data-urlencode "minCitationCount=50"
--data-urlencode "openAccessPdf="               # open access only (empty value = true)
--data-urlencode "publicationDateOrYear=2023-01-01:2023-12-31"

Pagination: Response includes total, offset, next. Use offset=N to page through results (max 1,000 total).

---

2. Bulk Search — /paper/search/bulk

Best for: large result sets, boolean queries, sorted/filtered exports.

Supports AND/OR/NOT operators and returns up to 1,000 results per call with token-based pagination (no 1,000 total cap).

curl -G "https://api.semanticscholar.org/graph/v1/paper/search/bulk" \
  --data-urlencode "query=large language models AND safety" \
  --data-urlencode "fields=title,year,citationCount,authors" \
  --data-urlencode "sort=citationCount:desc" \
  --data-urlencode "limit=100"

Sort options: paperId, publicationDate, citationCount (append :asc or :desc).

Pagination: Response includes a token field. Pass it as &token=... on the next call.

---

3. Title Match — /paper/search/match

Best for: "I have this paper title, give me its metadata." Returns a single best match or 404. Includes a matchScore.

curl -G "https://api.semanticscholar.org/graph/v1/paper/search/match" \
  --data-urlencode "query=Attention Is All You Need" \
  --data-urlencode "fields=title,year,authors,citationCount,externalIds"

---

4. Paper by ID — /paper/{paper_id}

Best for: fetching full metadata when you already have an identifier.

Supported ID formats (prefix as shown):

Format	Example
S2 Paper ID (bare)	649def34f8be52c8b66281af98ae884c09aef38a
Corpus ID	CorpusId:215416146
DOI	DOI:10.18653/v1/2020.acl-main.463
arXiv	ARXIV:2005.14165
PubMed	PMID:23193287
PubMed Central	PMCID:PMC4535869
ACL Anthology	ACL:2020.acl-main.463
Semantic Scholar URL	URL:https://www.semanticscholar.org/paper/...

# By arXiv ID
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762?fields=title,abstract,year,authors,citationCount,referenceCount,isOpenAccess,openAccessPdf"

# By DOI
curl "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1145/3292500.3330919?fields=title,year,venue,citationCount"

---

5. Batch Paper Lookup — POST /paper/batch

Best for: fetching metadata for a list of known paper IDs (up to 500).

curl -X POST "https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,year,citationCount" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["ARXIV:1706.03762", "ARXIV:2005.14165", "DOI:10.18653/v1/2020.acl-main.463"]}'

---

6. Citations & References

# Papers that CITE this paper (incoming)
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762/citations?fields=title,year,authors,citationCount&limit=20"

# Papers this paper CITES (outgoing)
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762/references?fields=title,year,authors&limit=20"

Response wraps each item in a citingPaper or citedPaper key:

{ "data": [{ "citingPaper": { "title": "...", "year": 2023 } }] }

---

7. Author Lookup

# Find an author's ID by name
curl -G "https://api.semanticscholar.org/graph/v1/author/search" \
  --data-urlencode "query=Yoshua Bengio" \
  --data-urlencode "fields=name,affiliations,paperCount,citationCount,hIndex"

# Get their papers
curl "https://api.semanticscholar.org/graph/v1/author/{authorId}/papers?fields=title,year,citationCount&limit=20"

---

Rate Limits & API Key

• Without a key: ~100 requests/5 min (shared pool)
• With a free API key: ~1 request/sec sustained

To use an API key:

curl -H "x-api-key: YOUR_KEY" "https://api.semanticscholar.org/graph/v1/paper/..."

Store the key in an env var: export S2_API_KEY=... Then use: -H "x-api-key: $S2_API_KEY"

---

Parsing Results

Use jq to extract fields from responses:

# List titles and citation counts from a search
curl -s -G "https://api.semanticscholar.org/graph/v1/paper/search" \
  --data-urlencode "query=BERT language model" \
  --data-urlencode "fields=title,year,citationCount" \
  --data-urlencode "limit=5" \
| jq '.data[] | "\(.citationCount)\t\(.year)\t\(.title)"'

# Get all author names from a paper
curl -s "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762?fields=authors.name" \
| jq '[.authors[].name]'

# Extract open access PDF URL
curl -s "https://api.semanticscholar.org/graph/v1/paper/ARXIV:2005.14165?fields=openAccessPdf" \
| jq '.openAccessPdf.url'

---

Workflow Tips

• Start with /paper/search/match when the user provides a full title — it's faster than a keyword search.
• Use /paper/{id} when they give you a DOI, arXiv link, or PubMed ID — extract the ID and call directly.
• For "papers about X" questions, use /paper/search with minCitationCount and year filters to surface foundational work.
• For citation counts and h-index exploration, combine /author/search → /author/{id}/papers sorted by citationCount:desc.
• Always request only the fields you need — smaller responses, faster calls.
• When displaying results, format as a table with title, year, venue, and citation count for readability.