By the fastCRW team · Catalogue figures checked 2026-11-05 against GET /v1/data · Verify independently before relying on any figure.
A citation graph has papers as nodes and "cites" relationships as edges. You can build one from OpenAlex alone, because each work lists the works it references. The hard parts are the traversal (which papers to expand), the deduplication (the same paper can arrive under more than one ID) and the enrichment (Crossref can say which registry issued a DOI). This guide builds a small graph in Python through the Pergamon catalogue, with one fastCRW API key for OpenAlex, Crossref, DataCite and Europe PMC.
The graph model
Each node is a work. Its key is the DOI when it has one, and its OpenAlex ID when it does not. Each edge is a pair (citing, cited). A work's references give you its outgoing edges. The papers that cite a work come from a reverse filter, cites:, which gives you the incoming edges.
Seed a work and read its references
Start from one OpenAlex work. Ask only for the fields the graph needs, because a full work record is large. This call returns the title and the list of works it cites:
curl "https://api.fastcrw.com/v1/data/openalex/work?id=W2741809807&select=id,title,referenced_works" \
-H "Authorization: Bearer $CRW_API_KEY"
In our run the seed returned 46 referenced works. Each reference is a full OpenAlex URL, so strip it to its short ID before you use it as a key.
Find the papers that cite a work
The works capability with a cites: filter returns the papers that cite a given work. Use it for the reverse direction. Highly cited works have very long lists, so cap the expansion instead of pulling every citer:
curl "https://api.fastcrw.com/v1/data/openalex/works?filter=cites:W2100837269&select=id,title" \
-H "Authorization: Bearer $CRW_API_KEY"
In our run the meta.count for that work was 248263 citing papers. A page holds 25 results by default, and the page option moves through them. Expanding every citer is almost never what a graph needs.
The traversal script
This script walks outward from the seed through references, breadth first, to a depth of 2 and at most 50 fetched works. It skips any work OpenAlex does not return, keys nodes by DOI where one exists, and keeps only the edges between works it fetched:
# pip install crw
from collections import deque
from crw import CrwClient
from crw.exceptions import CrwApiError
client = CrwClient() # reads CRW_API_KEY
SEED = "W2741809807"
MAX_DEPTH = 2
MAX_NODES = 50
def short_id(openalex_url: str) -> str:
return openalex_url.rsplit("/", 1)[-1]
def node_key(work: dict) -> str:
doi = (work.get("doi") or "").lower().replace("https://doi.org/", "")
return f"doi:{doi}" if doi else f"openalex:{short_id(work['id'])}"
def fetch_work(work_id: str) -> dict | None:
try:
res = client.get_data("openalex", "work", {"id": work_id, "select": "id,title,doi,referenced_works"})
except CrwApiError as exc:
print("skipped", work_id, exc)
return None
return res["data"]
def crawl(seed_id: str) -> tuple[dict, set]:
nodes: dict[str, dict] = {}
edges: set[tuple[str, str]] = set()
seen = {seed_id}
queue: deque[tuple[str, int]] = deque([(seed_id, 0)])
while queue and len(nodes) < MAX_NODES:
work_id, depth = queue.popleft()
work = fetch_work(work_id)
if work is None:
continue
nodes[work_id] = {"key": node_key(work), "title": work.get("title")}
for ref_url in work.get("referenced_works") or []:
ref = short_id(ref_url)
edges.add((work_id, ref))
if depth < MAX_DEPTH and ref not in seen:
seen.add(ref)
queue.append((ref, depth + 1))
return nodes, edges
if __name__ == "__main__":
nodes, edges = crawl(SEED)
kept = {(a, b) for a, b in edges if a in nodes and b in nodes}
keys = {v["key"] for v in nodes.values()}
key_edges = {(nodes[a]["key"], nodes[b]["key"]) for a, b in kept}
print(f"fetched works: {len(nodes)}, unique keys after DOI dedupe: {len(keys)}, edges: {len(key_edges)}")
Output from our run. The whole script took about 50 seconds:
skipped W2611818942 OpenAlex returned 404 for this request
skipped W6640061894 OpenAlex returned 404 for this request
fetched works: 50, unique keys after DOI dedupe: 50, edges: 164
The two 404s are referenced works that OpenAlex did not return. The script logs them and moves on instead of stopping the crawl.
Enrich with Crossref and DataCite
Crossref can tell you which registration agency issued a DOI, and that decides where the record lives. Zenodo DOIs are issued through DataCite, not Crossref, so ask Crossref first and then query the right source:
curl "https://api.fastcrw.com/v1/data/crossref/agency?doi=10.5281/zenodo.1422871" \
-H "Authorization: Bearer $CRW_API_KEY"
{"status":"ok","message-type":"work-agency","message":{"DOI":"10.5281/zenodo.1422871","agency":{"id":"datacite","label":"DataCite"}}}
The agency is DataCite, so query the datacite provider for the record:
curl "https://api.fastcrw.com/v1/data/datacite/doi?doi=10.5281/zenodo.1422871" \
-H "Authorization: Bearer $CRW_API_KEY"
In our run the title in the response was "citation-network: First release of citation network R code".
Biomedical citations from Europe PMC
For a biomedical paper, Europe PMC keeps its own citation list. Pass the source and the record ID:
curl "https://api.fastcrw.com/v1/data/europepmc/citations?source=MED&id=31378106" \
-H "Authorization: Bearer $CRW_API_KEY"
The response has citationList and hitCount. In our run the hit count was 30. Add these edges with the same key rule, so a paper seen in Europe PMC and OpenAlex lands on one node when both records share a DOI.
What the dedupe step did in this run
The key rule merges two records only when they share a DOI. In this run all 50 works already had distinct keys, so the dedupe step removed nothing. It earns its place when the same paper arrives under two OpenAlex IDs, or when two sources agree on a DOI. Records with no DOI on either side stay separate, and that is the correct behaviour, not a bug to hide.
Store the graph
For exploration, load the key_edges set into NetworkX as a directed graph. For a larger graph, write the edges to a Postgres table with two text columns and an index on each, then run traversals in SQL. Either way the traversal logic stays the same.
Cost
Each successful call costs 1 credit. The script above made 52 work calls: 50 returned data, and the 2 that returned 404 are not billed. The reverse citer query costs 1 credit per page. Budget a crawl as nodes times calls per node, and set MAX_NODES before you start, not after the bill arrives. Find calls are free. See pricing for plan prices.
What this does not do
- Missing edges are not proof. An edge comes from the reference list of each work. A citation that a source does not list is not confirmed to be absent.
- Some works have no references in the data. For example, W4391876620 has an empty
referenced_workslist. The script treats that as zero outgoing edges, not as an error. - The DOI key merges only exact matches. Two records for the same paper with different DOIs, or with a DOI on one side only, stay as two nodes.
- Metadata is not full text. This guide computes over metadata. Check each source's terms before you redistribute records or abstracts.
Read the SDK response shape
The Python SDK returns the same data with camelCase keys, while the REST envelope keeps the snake_case names. In our run the SDK result carried creditsUsed, and its provenance block carried attributionText. The data field is the OpenAlex work object itself, so res["data"]["referenced_works"] is the list the script walks. Keep the two shapes apart in your code, and do not mix REST and SDK keys in one parser.
Why the caps matter
A breadth-first crawl grows fast. Each fetched work can add dozens of outgoing edges, and each new node costs a call. The script stops at 50 fetched works, and it stops expanding at depth 2. In our run the crawl hit the 50-work cap, so the cap, not the citation structure, set the size of the sample.
Citers are a bigger risk than references. The paper W2100837269 had 248263 citing works in our run. If the crawl followed every citer of every node, a single famous paper would dominate the budget. Cap citers per node, sort them if the source supports it, and record how many you skipped so the graph reports its own truncation.
Check the crawl before you trust it
A crawl can finish and still be wrong. Four numbers tell you whether it did what you meant:
- Skipped works. Our run skipped 2 works that OpenAlex returned 404 for. A large skip count means the seed or the cap needs a second look.
- Empty reference lists. Some works have an empty
referenced_workslist. Count them. An empty list means the source gives no outgoing edges for that work, which is not proof that the paper cites nothing. - Distinct keys against nodes. If the number of unique keys is lower than the number of nodes, the DOI rule merged records. In our run the two numbers matched at 50.
- Edges that point outside the graph. The script drops edges whose ends it did not fetch. Count how many it dropped. Those are the references the cap cut off.
Read the sample, not the field
The in-degree of a node inside your sample is the number of sampled works that cite it. It is not the global citation count for that paper. For the global number, use the meta.count of the cites: filter, as the reverse query above shows. Report the sample figure and the source figure as two separate numbers, with the sample size next to them.
Budget the crawl before you run it
The sample run made 52 work calls and took about 50 seconds. The time grows with the number of calls, so budget about a second per call and one credit per successful call before you start a larger crawl. Set the node cap first, then the depth, and only then the citer cap for the highly cited nodes.
Errors in the crawl
The script catches only CrwApiError, so a bad key or a network fault still stops the run loudly. A work that OpenAlex does not return raises an upstream error, which the script prints as a skip. The errorCode on that response is upstream_error, and a failed call is not billed.
Sources
- OpenAlex Works API documentation
- Crossref REST API documentation
- DataCite REST API documentation
- Europe PMC REST API documentation
- Zenodo developer documentation
Related: OpenAlex API in Python · Build a knowledge graph from web data · Public data API for AI agents · OpenAlex on Pergamon
