Skip to content

Tools Reference

This MCP server provides tools for accessing Altmetric data across two APIs. Your AI agent discovers these tools and their parameters automatically via the MCP protocol - this document is for human reference.

Details Page API Tools

get_citation_counts (Free Tier)

Retrieve attention metrics and mention counts across various platforms for research outputs using DOI, PubMed ID, arXiv ID, or other identifiers.

Parameters: - identifier (required): The research output identifier (e.g., "10.1038/nature12373") - identifier_type (optional): Type of identifier - "doi", "pmid", "arxiv", "id", "ads", "handle", "nct_id", "repec", "urn", "uri", "isbn", "ssrn", or "dimensions_publication_id" (default: "doi")

Example: 

{
  "identifier": "10.1038/nature12373",
  "identifier_type": "doi"
}

get_citation_details (Commercial Tier)

Retrieve detailed mention information including full text of posts, author details, and complete metadata for how research is being discussed online. Posts from X are the exception: see X mentions below. The returned citation block includes authors_details, pairing each author name with its Dimensions Researcher ID where available.

Parameters: - identifier (required): The research output identifier - identifier_type (optional): "doi" or "id" (default: "doi") - include_sources (optional): Comma-separated sources to keep, e.g. "news,blogs". Names must match exactly; an unrecognised name returns no posts rather than an error - exclude_sources (optional): Comma-separated sources to drop, e.g. "twitter,facebook" - post_types (optional): Only "original_tweets", which excludes retweets - include_sections (optional): Comma-separated response sections to keep - counts, citation, altmetric_score, demographics, posts, images

This endpoint returns everything at once and has no pagination; use include_sources and include_sections to keep responses small.

Example: 

{
  "identifier": "10.1038/nature12373",
  "identifier_type": "doi",
  "include_sources": "news,blogs"
}

search_citations (Free Tier)

Search aggregated attention data across all tracked research outputs for a specific timeframe.

Parameters: - timeframe (required): "1d", "2d", "3d", "4d", "5d", "6d", "1w", "1m", "3m", "6m", "1y", or "at" (all-time) - citation_type (optional): Filter by the type of the research output - "article", "book", "chapter", "clinical_trial_study_record", "dataset", "generic", "news". This is the output's own type, not where it was mentioned - cited_in (optional): Only return outputs mentioned in these sources, comma-separated (e.g. "news,policy") - nlmid (optional): Filter by journal NLM ID - issns (optional): Filter by journal ISSN(s), comma-separated - subject (optional): Filter by Scopus subject area - num_results (optional): Number of results to return - page (optional): Page number for pagination

Example: 

{
  "timeframe": "1w",
  "cited_in": "news",
  "num_results": 50
}

Explorer API Tools (Institutional)

All Explorer tools require institutional credentials (both ALTMETRIC_EXPLORER_API_KEY and ALTMETRIC_EXPLORER_API_SECRET).

All six Explorer tools share a common set of filters. In addition to the per-tool parameters below, every Explorer tool accepts:

  • researcher_id: Filter by Dimensions Researcher ID(s), e.g. ["ur.015071462574.28"]
  • grant_id: Filter by Dimensions grant ID(s), e.g. ["grant.13864430"]
  • identifier_list_id: Scope the query to an existing identifier list (created in the Explorer UI or via the Identifier Lists API)
  • identifiers: Scope the query to a raw list of scholarly identifiers (DOI, Handle, ISBN, URI, URN, PubMed ID, arXiv ID, ADS Bibcode, RePEc ID, NCT ID, Altmetric ID). The server creates (or finds) an identifier list from these and applies it automatically, so you don't need to obtain an identifier_list_id first. Prefix Altmetric IDs with altmetric: to disambiguate them from PubMed IDs. Up to 25,000 identifiers; mutually exclusive with identifier_list_id.

explore_research_outputs

Search and filter research outputs within your institutional Altmetric Explorer instance. Supports filtering by author, department, journal, publication date, research type, and more. Each result includes sentiment-analysis-totals, a breakdown of its mentions across seven sentiment categories (computed for X and Bluesky mentions; absent if your organization has AI features restricted).

The altmetric-score on these results is rounded up to a whole number, which is how Altmetric displays a score everywhere: on a details page, on a badge and in the Explorer. A research output scoring 0.25 and one scoring 0.5 both report 1. The Details Page API tools return the same score unrounded, so a mean of one set is not the same figure as a mean of the other. Either is defensible; say which you used, and round up if the numbers have to agree with what a customer sees elsewhere in Altmetric.

Key Parameters: - q: Search query for title, author, or journal - scope: "all" or "institution" - type: Filter by research output type (e.g., ["article", "dataset"]) - timeframe: Filter by attention timeframe - page_number, page_size: Pagination controls

explore_attention_summary

Get aggregated attention metrics for research outputs matching your query, broken down by source (news, Twitter, policy documents, etc.) and date.

Key Parameters: - q: Search query - timeframe: Attention timeframe - type: Filter by research output type

explore_mentions

Retrieve individual mentions of research outputs with detailed information about each mention including author, URL, timestamp, and platform. Mentions from X carry no account name: see X mentions below. Scored mentions also carry a sentiment-analysis attribute (one sentiment per research output the mention references; computed for X and Bluesky only, absent if your organization has AI features restricted).

Key Parameters: - q: Search query - mention_types: Only return mentions of these types, e.g. ["msm"] for news, ["tweet","bluesky"] for X and Bluesky. The API's names: news is msm, Reddit is rdt, Facebook is fbwall, YouTube is video - mentioned_after/mentioned_before: Date range filters - countries: Filter by country codes - page_number, page_size: Pagination controls - include_related: Embed related objects (the mention author profile, journal, and the full mentioned research-output records). Defaults to false to keep responses small. Setting it true is heavy — for every mention it embeds the full referenced research-output records (titles, mention-count breakdowns, scores, sentiment totals) plus author/journal objects, and can exceed client size limits on busy queries. Leave it off unless you specifically need that related data.

explore_demographics

Get demographic information about the audiences engaging with research outputs. Analyze geographic distribution, demographic patterns, and audience characteristics.

Key Parameters: - q: Search query - scope: "all" or "institution" - timeframe: Attention timeframe - type, journal_id, author_id: Filter by research attributes

explore_mention_sources

Get information about the sources of mentions for research outputs. Analyze which platforms, channels, and outlets are mentioning research with source credibility and reach data. X accounts come back unnamed: see X mentions below.

Key Parameters: - q: Search query - mention_types: Only return sources of these types, e.g. ["msm"] for news outlets. Patents, peer reviews, Wikipedia, F1000, Q&A, video and Pinterest have no source profiles and cannot be filtered here; use explore_mentions for those - mentioned_after/mentioned_before: Date range filters. This endpoint serves at most a year at a time: mentioned_before requires mentioned_after, and mentioned_after on its own runs to today, so it must itself fall within the last year - countries: Filter by country codes - page_number, page_size: Pagination controls - include_related: Embed related objects (author profiles, journals, full mentioned research-output records). Defaults to false to keep responses small; setting it true is heavy and can exceed client size limits. Leave it off unless you specifically need that related data.

explore_journals

Get aggregated mention data by journal — journal names, ISSNs, and mention counts broken down by source type.

Single-page endpoint — no pagination. It does not honor page[size], so a broad query aggregates every matching journal into one response (e.g. q=cancer returns ~12,000 journals), which the server's size guard then truncates. Narrow the query to keep the result complete — there is no result-count limit, so filtering is the only control.

Key Parameters: - q: Search query (title, author, journal) - journal_id: Filter by specific journal IDs - type: Filter by research output type - timeframe, published_after/published_before: Time filters - identifiers / identifier_list_id: Scope to a specific set of outputs

list_departments

List the institutional departments configured in your Explorer instance — each with its id and name.

The id is the value to pass to the department_id filter on the other Explorer tools (e.g. explore_research_outputs). Only available to institutions with a data integration; those without one get an empty list. Takes no arguments and fetches every page for you, returning the full department set.

X mentions

Under Altmetric's licence with X, mentions from X expose only numeric identifiers. There is no account handle, display name or post text, at any tier and on either API:

  • get_citation_details returns tweet_id and author.tweeter_id.
  • explore_mentions returns the post id as external-id and the account id under author.
  • explore_mention_sources returns X accounts with an id and no name.

Every other source is named. News outlets, blogs, Bluesky, Reddit, podcasts, policy sources and the rest carry an author name, and usually a summary of the mention. So a question like "which accounts are talking about this paper" is answerable for those sources and not for X, where only counts, ids and aggregate demographics are available.

A numeric post id and account id can be turned back into a URL (https://twitter.com/{account_id}/status/{post_id}), and hydrated into a full post through X's own API, which requires a paid X plan. See https://docs.altmetric.com/details-page-api/x-data/.