3. Paper Search API¶

3.1 Paper Relevance Search¶

Search papers by relevance. The most basic search endpoint.

GET /graph/v1/paper/search

Parameters:

Response schema:

{
  "total": 1000,
  "offset": 0,
  "next": 10,
  "data": [ { "paperId": "...", "title": "..." } ]
}

Limitations: - Returns at most 1,000 relevance-ranked results - Single response max 10MB

Example:

curl "https://api.semanticscholar.org/graph/v1/paper/search?query=transformer+attention&fields=title,year,citationCount&limit=5"

Test with hurl¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=transformer+attention api/graph/paper-search.hurl

Change the search query via --variable. Add --json flag to output captured values as JSON.

3.2 Paper Bulk Search¶

Optimized for large-scale paper data retrieval. Similar to relevance search but without relevance ranking.

GET /graph/v1/paper/search/bulk

Characteristics: - Text query is required and supports boolean logic (empty string allowed) - Returns up to 1,000 results per call - If more results exist, a token is returned - Can page through up to 10,000,000 results (beyond that, use Datasets API) - Nested data (citations, references, etc.) is not available on this endpoint

Parameters:

Query syntax (boolean search):

sort parameter:

Format: field:order (default paperId:asc)

Records with no sort value appear last regardless of asc/desc. The default paperId sort is the most stable during paging. Ties are broken by paperId.

Response schema:

{
  "total": 50000,
  "token": "NEXT_PAGE_TOKEN",
  "data": [ ... ]
}

Differences from relevance search:

Test with hurl¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=transformer+attention api/graph/paper-bulk-search.hurl

Change the search query via --variable. Add --json flag to output captured values (total, token, etc.) as JSON.

3.3 Paper Title Match¶

Finds the single best-matching paper for a given title. Ideal for retrieving S2 metadata when you already know the paper title.

GET /graph/v1/paper/search/match

Characteristics: - Always returns a single result (the paper with the highest match score) - Response includes a matchScore field - Returns 404 on match failure: "Title match not found"

Parameters:

Examples:

# Find paper by title
curl "https://api.semanticscholar.org/graph/v1/paper/search/match?query=Attention+Is+All+You+Need&fields=title,year,authors"

# Non-existent title → 404
curl "https://api.semanticscholar.org/graph/v1/paper/search/match?query=totalGarbageNonsense"

Response schema:

{
  "data": [
    {
      "paperId": "...",
      "title": "...",
      "matchScore": 87.5
    }
  ]
}

Wrapped in a data array but always contains 0–1 results. matchScore is the title matching confidence score.

Test with hurl¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=Attention+Is+All+You+Need api/graph/paper-title-match.hurl

Specify the paper title via --variable query=.... Add --json flag to output captured values (paper_id, match_score, etc.) as JSON.

3.4 Paper Autocomplete¶

For interactive search autocompletion. Returns minimal information (titles, etc.) quickly for partial queries.

GET /graph/v1/paper/autocomplete

Parameters:

Response schema:

{
  "matches": [
    { "id": "...", "title": "...", "authorsYear": "Beltagy et al., 2019" }
  ]
}

Test with hurl¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=attention+is+all api/graph/paper-autocomplete.hurl

Specify the partial query via --variable query=.... Add --json flag to output autocomplete results as JSON.

3.5 Snippet Search¶

Searches full-text snippets from paper bodies. Can search beyond titles/abstracts into the actual body text. Returns excerpts of approximately 500 words, excluding figure captions and bibliographies.

GET /graph/v1/snippet/search

Limitations: - query is required - Default 10 results when limit is not specified - limit max 1,000

Parameters:

authors filter details: - AND logic: authors=galileo,kepler → papers containing both authors - Fuzzy matching: matches similar names within edit distance 2 (keppler → kepler) - For OR search, perform separate searches per author - Max 10 authors, exceeding returns 400 error

fields parameter (snippet-specific):

paper and score are always returned. Use fields to control snippet subfields:

fields=snippet.text                              # text only
fields=snippet.text,snippet.snippetKind          # text + location kind
fields=snippet.annotations.sentences             # sentence annotations only

Default fields (when fields not specified): - snippet.text, snippet.snippetKind, snippet.section - snippet.snippetOffset (includes start, end) - snippet.annotations.refMentions (start, end, matchedPaperCorpusId) - snippet.annotations.sentences (start, end)

Response structure:

Each result includes:

Example:

curl "https://api.semanticscholar.org/graph/v1/snippet/search?query=The+literature+graph+is+a+property+graph&limit=1"

Test with hurl¶

hurl --variable s2_api_key=$S2_API_KEY --variable query=literature+graph+property+graph api/graph/snippet-search.hurl

Change the search query via --variable query=.... Add --json flag to output captured values (snippet text, score, etc.) as JSON.