Semantic Scholar Search Workflow

Search academic papers via the Semantic Scholar API using a structured 4-phase workflow.

Critical rule: NEVER make multiple sequential Bash calls for API requests. Always write ONE Python script that runs all searches, then execute it once. All rate limiting is handled inside

s2.py

Phase 1: Understand & Plan

Parse the user's intent and choose a search strategy:

Decision Tree

search_relevance()

search_bulk()

build_bool_query()

search_snippets()

match_title()

get_paper()

get_citations()

find_similar()

recommend()

search_authors()

get_author()

get_author_papers()

Query Construction Rules

• Ambiguous terms (e.g., "stem cells" could mean mesenchymal or stem-like T cells): Use

  build_bool_query()

  with exact phrases and exclusions
  • Example:

    build_bool_query(phrases=["stem-like T cells"], required=["CD4", "TCF7"], excluded=["mesenchymal", "hematopoietic stem cell"])

• Multi-context queries (e.g., "topic X in cancer AND autoimmunity"): Plan separate searches, deduplicate with

  deduplicate()

• Broad topics: Use

  search_relevance()

  with filters (year, venue, fieldsOfStudy, minCitationCount)

Plan Filters

year="2020-"

publication_date="2024-01-01:2024-06-30"

fields_of_study="Medicine"

min_citations=10

pub_types="Review"

pub_types="ClinicalTrial"

open_access=True

Checkpoint: Before proceeding, verify: (1) search strategy matches user intent, (2) filters are appropriate, (3) query is specific enough to avoid irrelevant results.

Phase 2: Execute Search

Write ONE Python script. Example:

import sys, os
SKILL_DIR = next((p for p in [
    os.path.expanduser("~/.claude/skills/semanticscholar-skill"),
    os.path.expanduser("~/.openclaw/skills/semanticscholar-skill"),
] if os.path.isdir(p)), ".")
sys.path.insert(0, SKILL_DIR)
from s2 import *

# Build precise query
q = build_bool_query(
    phrases=["stem-like T cells"],
    required=["CD4", "IBD"],
    excluded=["mesenchymal"]
)
papers = search_bulk(q, max_results=30, year="2018-", fields_of_study="Medicine")
papers = deduplicate(papers)

print(format_results(papers, "Stem-like CD4 T cells in IBD"))

Execute with:

python3 /tmp/s2_search.py

Rules:

• Import everything from s2:

  from s2 import *

• Write script to

  /tmp/s2_search.py

  (or similar temp path)
• One Bash call to execute. Never chain multiple API calls via separate Bash invocations.
• Rate limiting, retries, and backoff are automatic inside s2.py

Checkpoint: Verify the script ran successfully (no exceptions) and returned results. If 0 results, broaden the query or relax filters before presenting.

Worked Examples

Example 1: Author workflow — "Find papers by Yann LeCun on self-supervised learning"

import sys, os
SKILL_DIR = next((p for p in [
    os.path.expanduser("~/.claude/skills/semanticscholar-skill"),
    os.path.expanduser("~/.openclaw/skills/semanticscholar-skill"),
] if os.path.isdir(p)), ".")
sys.path.insert(0, SKILL_DIR)
from s2 import *

authors = search_authors("Yann LeCun", max_results=5)
print(format_authors(authors))

# Use the first match's ID to get their papers
author_id = authors[0]["authorId"]
papers = get_author_papers(author_id, max_results=50)
# Filter locally for topic
ssl_papers = [p for p in papers if "self-supervised" in (p.get("title") or "").lower()]
print(format_results(ssl_papers, "Yann LeCun - Self-Supervised Learning"))

Example 2: Citation chain — "Who cited the Transformer paper and what did they build on?"

import sys, os
SKILL_DIR = next((p for p in [
    os.path.expanduser("~/.claude/skills/semanticscholar-skill"),
    os.path.expanduser("~/.openclaw/skills/semanticscholar-skill"),
] if os.path.isdir(p)), ".")
sys.path.insert(0, SKILL_DIR)
from s2 import *

paper = get_paper("DOI:10.48550/arXiv.1706.03762")
print(f"Title: {paper['title']}, Citations: {paper['citationCount']}")

# Get top-cited papers that cite this one
citing = get_citations(paper["paperId"], max_results=50)
citing_papers = [c["citingPaper"] for c in citing if c.get("citingPaper")]
citing_papers.sort(key=lambda p: p.get("citationCount", 0), reverse=True)
print(format_results(citing_papers, "Most-cited papers citing Attention Is All You Need"))

Example 3: Multi-seed recommendations with BibTeX export — "Find papers like these two but not about NLP"

import sys, os
SKILL_DIR = next((p for p in [
    os.path.expanduser("~/.claude/skills/semanticscholar-skill"),
    os.path.expanduser("~/.openclaw/skills/semanticscholar-skill"),
] if os.path.isdir(p)), ".")
sys.path.insert(0, SKILL_DIR)
from s2 import *

recs = recommend(
    positive_ids=["DOI:10.1038/nature14539", "ARXIV:2010.11929"],
    negative_ids=["ARXIV:1706.03762"],
    limit=20
)
print(format_results(recs, "Vision papers like Deep Learning & ViT, excluding NLP"))

# Export BibTeX for top results
bib_data = batch_papers([r["paperId"] for r in recs[:10]], fields="title,citationStyles")
print(export_bibtex(bib_data))

Phase 3: Summarize & Present

• Use

  format_results()

  for consistent output (summary table + top-10 details)
• If user's language is Chinese, present summaries in Chinese
• Always note total results count and search strategy used
• Highlight most relevant papers based on the user's specific question

Phase 4: User Interaction Loop

After presenting results, always offer these options:

1. Translate — titles/summaries to Chinese (or other language)
2. Details — full abstract for specific paper numbers
3. Refine — narrow or expand search with different terms/filters
4. Similar — find papers similar to a specific result (

   find_similar()

   )
5. Citations — who cited a specific paper (

   get_citations()

   )
6. Export — save results via

   export_bibtex()

   ,

   export_markdown()

   , or

   export_json()

7. Done — end search session

Loop until user says done. Each follow-up uses the same single-script pattern.

API Quick Reference

Helper Module (

s2.py

)

import sys, os
SKILL_DIR = next((p for p in [
    os.path.expanduser("~/.claude/skills/semanticscholar-skill"),
    os.path.expanduser("~/.openclaw/skills/semanticscholar-skill"),
] if os.path.isdir(p)), ".")
sys.path.insert(0, SKILL_DIR)
from s2 import *

Paper Search Functions

search_relevance(query, **filters)

search_bulk(query, sort=..., **filters)

search_snippets(query, **filters)

match_title(title)

get_paper(paper_id)

get_citations(paper_id, max_results)

get_references(paper_id, max_results)

find_similar(paper_id, limit, pool)

recommend(positive_ids, negative_ids, limit)

batch_papers(ids, fields)

Author Functions

search_authors(query, max_results)

get_author(author_id)

get_author_papers(author_id, max_results)

get_paper_authors(paper_id, max_results)

batch_authors(ids, fields)

Filter Parameters (kwargs)

year

publication_date

venue

fields_of_study

min_citations

pub_types

open_access

• year

  :

  "2020-"

  ,

  "-2019"

  ,

  "2016-2020"

• publication_date

  :

  "2024-01-01:2024-06-30"

  (YYYY-MM-DD range, open-ended OK)

• pub_types

  :

  Review

  ,

  JournalArticle

  ,

  Conference

  ,

  ClinicalTrial

  ,

  MetaAnalysis

  ,

  Dataset

  ,

  Book

  ,

  CaseReport

  ,

  Editorial

  ,

  LettersAndComments

  ,

  News

  ,

  Study

  ,

  BookSection

Boolean Query Syntax (bulk search only)

"..."

"deep learning"

+

+transformer

-

-survey

|

CNN | RNN

*

neuro*

()

(CNN | RNN) +attention

Use

build_bool_query(phrases, required, excluded, or_terms)

Output Functions

format_table(papers, max_rows=30)

format_details(papers, max_papers=10)

format_results(papers, query_desc)

format_authors(authors, max_rows=20)

export_bibtex(papers)

citationStyles

export_markdown(papers, query_desc)

export_json(papers, path)

deduplicate(papers)

Supported ID Formats

DOI:10.1038/...

ARXIV:2106.15928

PMID:19872477

PMCID:PMC2323569

CorpusId:215416146

ACL:2020.acl-main.447

DBLP:conf/acl/...

MAG:3015453090

URL:https://...

Paper Fields

Default:

title,year,citationCount,authors,venue,externalIds,tldr

Additional:

abstract

references

citations

openAccessPdf

publicationDate

publicationVenue

fieldsOfStudy

s2FieldsOfStudy

journal

isOpenAccess

referenceCount

influentialCitationCount

citationStyles

embedding

textAvailability

Author fields:

name

affiliations

paperCount

citationCount

hIndex

homepage

externalIds

papers

Rate Limiting

Handled automatically by

s2.py

Troubleshooting

HTTPError 403

S2_API_KEY

echo $S2_API_KEY

HTTPError 429

max_results

ModuleNotFoundError: s2

~/.claude/skills/

~/.openclaw/skills/

ModuleNotFoundError: requests

requests

pip install requests

uv pip install requests

search_relevance()

search_bulk()

KeyError: 'data'

r.get("message")

tldr

abstract

tldr