GnistAI GnistAI
Log in

Getting Started with OpenAlex

Open scholarly metadata — works, authors, institutions, and citation networks.

All Tutorials   |   Overview   |   Playground   |   MCP   |   REST API   |   Home
Science

Data source: OpenAlex

Overview

OpenAlex wraps OpenAlex, handling authentication, pagination, and rate limits for you. This tutorial covers all 6 tools with working code examples you can copy and run.

Prerequisites

  1. Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
  2. Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config 
{
  "mcpServers": {
    "gnist-openalex": {
      "url": "https://context.gnist.ai/mcp/openalex/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (6)

search_papers

Search scholarly papers by keyword across 250M+ works from OpenAlex. Args: query: Search terms (e.g. "transformer attention mechanisms", "CRISPR gene editing"). year_from: Filter to papers published from this year onward (e.g. 2020). Optional. year_to: Filter to papers published up to this year (e.g. 2024). Optional. field_of_study: Filter by research field (e.g. "machine learning", "biology"). Optional. max_results: Number of results to return (1–25, default 10). Returns: Dictionary with count and papers list (id, doi, title, year, venue, cited_by_count, open_access flag, authors up to 5, top 5 concepts).

ParameterTypeRequiredDescription
querystringrequiredSearch terms (e.g. "transformer attention mechanisms", "CRISPR gene editing").
year_fromanyoptionalFilter to papers published from this year onward (e.g. 2020). Optional.
year_toanyoptionalFilter to papers published up to this year (e.g. 2024). Optional.
field_of_studyanyoptionalFilter by research field (e.g. "machine learning", "biology"). Optional.
max_resultsintegeroptionalNumber of results to return (1–25, default 10). (default: 10)
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_papers", "arguments": {"query": "transformer attention mechanisms"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'transformer attention mechanisms'},
            'name': 'search_papers'}},
)
print(resp.json())

get_paper

Get full details for a specific paper including abstract and citation count. Args: paper_id: OpenAlex ID (e.g. "W2741809807"), DOI (e.g. "10.1038/s41586-021-03819-2"), or full URL (e.g. "https://openalex.org/W2741809807"). Returns: Full paper record: id, doi, title, publication_year, venue, abstract, authors, concepts, cited_by_count, references_count, open_access.

ParameterTypeRequiredDescription
paper_idstringrequiredOpenAlex ID (e.g. "W2741809807"), DOI (e.g. "10.1038/s41586-021-03819-2"), or full URL (e.g. "https://openalex.org/W2741809807").
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_paper", "arguments": {"paper_id": "W2741809807"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'paper_id': 'W2741809807'}, 'name': 'get_paper'}},
)
print(resp.json())

get_author_profile

Get a researcher's profile — works, citations, h-index, and affiliations. Args: author_id: OpenAlex author ID (e.g. "A5023888391"), ORCID (e.g. "0000-0001-6187-6610"), or full ORCID URL. Returns: Author profile: id, display_name, orcid, works_count, cited_by_count, h_index, and affiliations (up to 3 recent institutions).

ParameterTypeRequiredDescription
author_idstringrequiredOpenAlex author ID (e.g. "A5023888391"), ORCID (e.g. "0000-0001-6187-6610"), or full ORCID URL.
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_author_profile", "arguments": {"author_id": "A5023888391"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'author_id': 'A5023888391'},
            'name': 'get_author_profile'}},
)
print(resp.json())

list_citations

List papers that cite or are referenced by a given paper. Args: paper_id: OpenAlex ID, DOI, or full URL of the paper. direction: "cited_by" for papers that cite this one (default), or "references" for papers this paper cites. max_results: Number of results to return (1–25, default 20). Returns: Dictionary with count and papers list (id, doi, title, year, cited_by_count, authors).

ParameterTypeRequiredDescription
paper_idstringrequiredOpenAlex ID, DOI, or full URL of the paper.
directionstringoptional"cited_by" for papers that cite this one (default), or "references" for papers this paper cites. (default: cited_by)
max_resultsintegeroptionalNumber of results to return (1–25, default 20). (default: 20)
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_citations", "arguments": {"paper_id": "12345"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'paper_id': '12345'}, 'name': 'list_citations'}},
)
print(resp.json())

get_trending_papers

Get recently published high-impact papers in a research field. Args: field: Research field to search (e.g. "machine learning", "immunology", "climate change"). days: Look back this many days for recent papers (default 30). max_results: Number of results to return (1–25, default 10). Returns: Dictionary with count and recent papers ranked by citation count.

ParameterTypeRequiredDescription
fieldstringrequiredResearch field to search (e.g. "machine learning", "immunology", "climate change").
daysintegeroptionalLook back this many days for recent papers (default 30). (default: 30)
max_resultsintegeroptionalNumber of results to return (1–25, default 10). (default: 10)
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_trending_papers", "arguments": {"field": "machine learning"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'field': 'machine learning'},
            'name': 'get_trending_papers'}},
)
print(resp.json())

report_feedback

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

ParameterTypeRequiredDescription
feedbackstringrequired
feedback_typestringoptional (default: general)
curl -X POST "https://context.gnist.ai/mcp/openalex/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'
import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/openalex/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_papers to find items, then get_paper to get full details. This two-step pattern is common for exploring data before drilling down.
Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does OpenAlex provide?

Open scholarly metadata — works, authors, institutions, and citation networks. It exposes 6 tools: search_papers, get_paper, get_author_profile, list_citations, get_trending_papers, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the OpenAlex API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.

Next Steps

Interactive Playground
Try tools in your browser — no setup required.
Full Reference
Complete docs for all 6 tools.

Related Tutorials

Academic Research
Tutorial
Health Research
Tutorial
Environmental Monitoring
Tutorial
Research Funding
Tutorial
arXiv
Tutorial
ClinicalTrials.gov
Tutorial