OpenAlex API: Building a Metrics Dashboard

The OpenAlex API is a free, fully open REST interface to a catalogue of hundreds of millions of scholarly works, authors, institutions and funders, and it is the most practical data source for building an in-house institutional research metrics dashboard without a subscription. Query the /works endpoint with an institution filter, aggregate with group_by, and you have publication counts, open-access share and citation-percentile data in a single JSON response.

OpenAlex is an open, CC0-licensed catalogue of the global research system — works, authors, institutions, sources, funders and topics — built and maintained by the non-profit OurResearch as a successor to the discontinued Microsoft Academic Graph. Because every record and the API itself are free to query, research offices can build metrics dashboards without licensing a commercial bibliometrics platform, provided they understand the filter syntax, pagination limits and the metric gaps this guide covers.

• What is the OpenAlex API and what does it cover?
• How do you query the Works endpoint for institutional metrics?
• How do you approximate field-weighted citation impact with OpenAlex data?
• What are the authentication, rate-limit and pricing rules?
• Common developer questions
• Implications for institutional research offices

What is the OpenAlex API and what does it cover?

The OpenAlex API exposes entity endpoints — Works, Authors, Institutions, Sources, Topics, Funders and Awards — each accessed at https://api.openalex.org/{entity}. Every entity supports four operations: list, get (by ID), filter, and group_by (server-side aggregation), which together are the building blocks of a dashboard.

Each entity carries a persistent OpenAlex ID and, for institutions, a cross-walked ROR identifier — the Research Organization Registry ID also used by ORCID, Crossref and DataCite. Filtering on an institution’s ROR-linked OpenAlex ID, rather than a free-text name match, is what keeps a dashboard’s institutional attribution stable as an organisation’s name or subsidiary structure changes.

How do you query the Works endpoint for institutional metrics?

Every institution-level query starts with the authorships.institutions.id filter set to the institution’s OpenAlex ID, which you resolve once via /institutions?filter=ror:https://ror.org/{your-ror-id}. From there, combine filters with commas (AND logic) and pipes (OR logic), and add group_by to turn a list query into an aggregation query in one request — no client-side loop required.

• Publication trend: /works?filter=authorships.institutions.id:I123...,publication_year:2020-2026&group_by=publication_year
• Open-access share: add &group_by=oa_status to the same filter to split output into gold, green, hybrid, bronze and closed counts.
• Field distribution: &group_by=primary_topic.field.id reveals subject concentration across an institution’s output.
• Collaboration mapping: &group_by=authorships.institutions.id returns co-publishing partner institutions ranked by shared-work count.

Use the select parameter to strip unused fields from large responses, and switch from offset-based page/per_page pagination to cursor pagination once a query’s meta.count exceeds roughly 10,000 results — offset pagination is capped and will silently stop returning new pages beyond that depth.

How do you approximate field-weighted citation impact with OpenAlex data?

Field-weighted citation impact (FWCI) is a proprietary metric popularised by Elsevier’s SciVal and Scopus products, calculated by comparing a work’s citations to the average for same-year, same-subject, same-document-type publications; OpenAlex does not expose a field literally called “FWCI”, and no open API replicates the Scopus subject-classification baseline it is normalised against.

OpenAlex’s nearest open equivalent is the cited_by_percentile_year object returned on every work record, which gives a min/max percentile rank of that work’s citation count against all works of the same publication year and type. Aggregating this field across an institution’s output — for example, the share of works in the top decile (percentile ≥ 90) per year — produces a transparent, reproducible citation-impact proxy that a dashboard can compute without a commercial licence, though it is not interchangeable with SciVal’s FWCI for benchmarking against institutions that report the Scopus figure.

For most dashboards the honest approach is to present both: raw citation counts (context-dependent, not comparable across fields) and the percentile-year proxy (comparable within OpenAlex’s corpus), clearly labelled as distinct from any vendor-reported FWCI value cited in external reports.

What are the authentication, rate-limit and pricing rules?

OpenAlex’s underlying dataset, website and API are free and the data is CC0-licensed, so no purchase is required to query or redistribute results. Every request should still include a contact identifier — either a mailto query parameter with your email address or a registered api_key — to enter the “polite pool”, which OurResearch prioritises over anonymous traffic for faster, more consistent response times.

Requests without a mailto parameter or API key are routed to a slower, lower-priority pool and are more likely to be throttled during peak load; this single parameter is the most common fix for intermittent 429 or timeout errors reported by developers building batch-harvesting scripts. Dashboard builders scheduling nightly refresh jobs should always set mailto or an API key rather than relying on the anonymous pool.

Common developer questions

Is the OpenAlex API free?

Yes. OpenAlex is free to query, and the underlying data is licensed under CC0, meaning it can be reused and redistributed without royalties. Registering an email via the mailto parameter or an API key gives access to the faster “polite pool” but does not change the underlying no-cost model.

Does OpenAlex have an API for institutional data?

Yes. The Institutions endpoint returns disambiguated organisation records cross-walked to ROR identifiers, and the Works endpoint accepts an authorships.institutions.id filter, which is the standard way to scope any query to a single institution’s publication output for a dashboard.

What is OpenAlex used for in research administration?

Research offices use OpenAlex to track publication trends, open-access compliance, collaboration networks and topic concentration without paying for a commercial bibliometrics subscription. Its open licence also makes it suitable for public-facing institutional reporting, since results can be republished without redistribution restrictions.

Implications for institutional research offices

A dashboard built directly on the OpenAlex API gives research administration teams a free, auditable alternative to proprietary bibliometrics tools for routine reporting — publication counts, open-access compliance tracking and collaboration mapping — while reserving paid platforms for tasks that genuinely require vendor-normalised metrics such as reported FWCI. The trade-off is that teams take on the engineering work themselves: handling pagination beyond 10,000 results, keeping institution ID mappings current as ROR records change, and documenting clearly that a percentile-based proxy is not the same figure a funder or ranking body may expect from Scopus.

As OpenAlex’s topic classification and percentile fields mature, the gap between what a free, transparent API can deliver and what a paid platform delivers continues to narrow for most day-to-day institutional reporting needs, making a well-built in-house dashboard an increasingly credible default rather than a stopgap.