Repositories
If you run a repository, OpenAlex is probably already harvesting it, and there’s a lot you can do to make your records show up more completely and accurately. This page is the recipes. The mechanism (how harvesting, matching, and full-text detection actually work) lives in the Repositories reference.
Two words to keep straight: your endpoint is the OAI-PMH URL you run, and your source is the OpenAlex record we mint for your repository (openalex.org/sources/S…). You own the endpoint; we own the source. Fixes happen at the endpoint; results show up on the source.
Everything on this page ends the same way: if what you see doesn’t explain itself, file a support ticket and we’ll take it from there. There’s no form to fill in and no validator to run.
How do I get my repository harvested by OpenAlex?
First, check whether we already harvest you. Search our repository sources for your repository’s name. If it’s there, open it and click the Harvest tab: it shows the endpoint we have on file and when we last received records from it. If the endpoint is right and the status is healthy, you’re in, and we’ll keep checking you daily.
If you’re not listed, or the tab says we have no endpoint on file, email support@openalex.org (or use openalex.org/contact) with:
Subject: Add my repository
Repository name:
OAI-PMH endpoint URL: https://…/oai (the base URL, not your homepage)
Set (only if the endpoint serves several collections):
Three or four example DOIs of open-access articles in the repository:
That’s the whole registration. We verify the endpoint, add it, and reply. If we need something else (a set name, a metadata prefix, an allowlist entry on your side) we’ll ask; you don’t need to validate anything before writing. Your receipt is the Harvest tab on your new source: once the endpoint is on file it appears there, and the first harvest pulls your whole back catalog, which can take a few days for a large or slow repository.
Running a journal on OJS? A journal belongs in Crossref, not here, but OJS’s built-in OAI-PMH endpoint can also be registered the same way. See Getting indexed for which path fits.
Is my endpoint harvestable?
Most registration failures are the endpoint’s own OAI-PMH quirks, and you can check all of them yourself in a browser before writing to us:
- Give us the OAI-PMH base URL, not your homepage. Test it:
https://your-endpoint/oai?verb=Identifyshould return XML with your repository’s name in it, and…?verb=ListRecords&metadataPrefix=oai_dcshould return records. If either returns a web page or an error, that’s not the URL we need. Typical shapes:/oai/request(DSpace),/cgi/oai2(EPrints),/do/oai/(Digital Commons),/index.php/<journal>/oai(OJS). - No login, API key, or IP restriction on the feed. We fetch it anonymously. If you run a firewall or a bot-blocker in front of it, allowlist us.
- A well-formed
earliestDatestampin yourIdentifyresponse. We read its format to decide whether to send dates with or without times. Your first harvest asks for every record with no start date, so a wrong date there doesn’t cut off your back catalog, but other harvesters may still trust it. - Answer within 15 seconds per request. That’s our timeout. If your platform takes longer to warm up from cold, the first request of the day fails and we try again tomorrow. We make at most three requests to any host at once.
- Serve
oai_dc. That is the metadata format we read. Records with an empty<metadata>element are skipped, not fatal. - A DOI and a title in each record, so we can match it. Details in Making your records match better.
If everything above passes and you’re still not harvested, report it; include the Identify URL and we’ll look at the rest.
How do I check OpenAlex’s harvest of my repository?
Open your source on openalex.org and click Harvest (or go straight to https://openalex.org/sources/S<id>?tab=harvest). It is the live record of what we have from you and how the last attempt went. The tab is marked beta; the data is real.
Harvest status. Last new records received is the date we last stored a record we didn’t already have. It only moves when your repository gives us something new, so a stable repository shows an old date and that’s fine. Next harvest counts down to our next daily check.
What we’ve harvested. Three numbers, and they are different on purpose:
- records (locations) harvested from this source: every harvested record that parsed cleanly, one location each. The API icon beside it opens the raw list:
api.openalex.org/locations?filter=source_id:S<id>. This is the number to compare with your repository’s own record count. - works include this source as a location: how many works have at least one of your copies attached. Lower than the first number when several of your records describe the same paper.
- works have this source as their primary location: works where your copy is the main one, which usually means we found no publisher version. Lower still. See Records are not works for why these diverge.
Harvest history. New records received per month since our first harvest. Early bars are large because the first harvests pull the back catalog. There’s a CSV download.
Endpoints on file. The OAI-PMH URL (and set, and metadata prefix) we harvest, with two links: Identify opens your endpoint’s Identify response, and recent records opens the same ListRecords request we send. If those links don’t work in your browser, they don’t work for us either. Under each endpoint is a health line: a green dot and last harvest OK, or a red dot with the status and the error your server returned, verbatim.
If the tab says We don’t have an OAI-PMH endpoint on file for this source, we know the repository (usually from records that arrived some other way) but aren’t harvesting it: register the endpoint.
What does my endpoint’s harvest status mean?
The health line under each endpoint shows one of six statuses from our last attempt. The error text next to it is whatever your server or the protocol library said, unedited. We retry every failing endpoint the next day, so a fix on your side needs no re-registration; just watch the line turn green.
| Status | What happened | What to do |
|---|---|---|
last harvest OK | We fetched the feed successfully. 0 records here just means nothing changed in the date range we asked for; that’s still OK. | Nothing. If records are missing anyway, see records not showing up. |
blocked | Your server answered 401 or 403. A firewall, WAF, or bot-blocker refused us. | Allowlist our IP and User-Agent. |
timeout | No response within 15 seconds. Cold-start delays, huge ListRecords pages, or an overloaded server. | Check the recent records link responds quickly. Keep the endpoint warm or shrink your page size. |
connection_error | We couldn’t reach the host, or it returned another HTTP error (404, 500, 502…). Includes a moved or retired URL. | Confirm the endpoint URL in your browser. If it changed, tell us the new one. |
malformed | The response wasn’t valid XML, often an HTML error page or a truncated response. | Open the recent records link and check it’s XML all the way down. |
oai_error | Your server returned an OAI-PMH protocol error such as badArgument, noSetHierarchy, or cannotDisseminateFormat. The message names it. | Fix the thing it names: the set doesn’t exist, oai_dc isn’t served, or the date format we sent (derived from your earliestDatestamp) doesn’t match what you accept. |
Anything else, or a status that stays red after you’ve fixed the cause, is a ticket: report it with the status and the error text.
Why are only some of my repository’s records showing up?
Because a repository record isn’t an OpenAlex work. When your record matches a paper we already know (from Crossref, DataCite, PubMed, another repository), it becomes a location on that existing work rather than a new work of its own. Your source’s work count is therefore the number of works that have you as a location, never a mirror of your record count. The full explanation is Records are not works in the reference.
Matching also depends on metadata: records without a cleanly reported DOI, or a matchable title and first author, can fail to match, and a record whose only DOI is one your repository minted looks like a different paper to us. See Why a repository seems to be missing most of its works.
To see exactly what we hold from you, use the records (locations) count on your Harvest tab and its API link: api.openalex.org/locations?filter=source_id:S<id>. Every record we harvested and kept is there, whether or not it matched.
If items you can see in your repository aren’t in that count at all, check your own feed next: we can only harvest what your endpoint’s ListRecords returns. On DSpace 7 and later (including DSpace-CRIS), the OAI-PMH feed is served from a separate OAI index, which only changes when [dspace]/bin/dspace oai import runs, usually from a nightly cron job. If that job stops, new items never reach the feed, and edited ones keep their old datestamps. The signs: your newest deposits are missing from ListRecords, and the feed’s newest datestamp is months old. Running the import, and scheduling it, fixes it; our next daily harvest picks the items up.
How do I see my repository’s unmatched records?
Unmatched repository records aren’t gone. Any record with a DOI or a usable title is minted as a work of its own, with your repository as its only source, and it sits in the core corpus like any other work. The exception is the backlog swept in at the November 2025 Walden cutover: those were minted into the expansion corpus, which is excluded from API results by default. To include them, add corpus=all to your query:
api.openalex.org/works?filter=locations.source.id:S4306402521&corpus=all
For many repositories this changes the count dramatically. (Data quality in the expansion corpus is lower on average and improving.)
Why did my repository’s work count go down?
Usually because coverage got better, not worse. A work counts toward works have this source as their primary location only while your copy is the main one. When we later find the publisher’s version of record, your copy stays on the work as its green-OA location but stops being primary, and the primary count drops. Nothing was removed. Compare the two queries:
api.openalex.org/works?filter=locations.source.id:S<id> # every work with your copy
api.openalex.org/works?filter=primary_location.source.id:S<id> # works where your copy is primary
If the first number dropped, or the records (locations) count on your Harvest tab did, that’s a real loss and we want to hear about it: report it with both numbers and the date you noticed.
We changed platforms or our endpoint URL moved
Email us the old URL and the new one (plus a set name, if the new endpoint needs one), and we’ll swap it on your source. Until we do, your Harvest tab will show the old endpoint going red with connection_error; after the swap, the next daily run picks up from where the old one stopped. Platform migrations often restamp every record’s datestamp, which makes your whole catalog look new to us: that’s fine, we re-fetch it and dedupe against what we already have. Watch the Harvest tab for the first green line on the new endpoint.
How do I allowlist OpenAlex’s harvester?
Our OAI-PMH harvester runs from a single static IP address that OpenAlex owns, and identifies itself in every request:
IP address: 44.208.99.237
User-Agent: OpenAlex/1.0 (+https://help.openalex.org/how-to/repositories/; mailto:support@openalex.org)
The address is also published as a plain-text list at /harvester-ips.txt. One exception: the few endpoints that challenge every automated request are fetched through a third-party service (Zyte) from its own addresses, with the same User-Agent.
Until November 2026 we harvested from a proxy provider’s shared address; we no longer use it. If you allowlisted that address, replace it with 44.208.99.237. Until 21 November 2026 the harvester called itself OpenAlexHarvester/1.0 (+https://help.openalex.org/how-to/repositories/; mailto:support@openalex.org); if you allowlisted that name, add the new one.
Allowlist the IP, or the User-Agent, or both. On its own that covers OAI-PMH harvesting. We fetch record pages and files separately, from rotating addresses unless your repository is on our list, so read how to let our page checks through before you restrict anything to the IP above: blocking those fetches costs you open-access detection. When we first verify a newly registered endpoint we may probe it once from a different address with a User-Agent that also starts with OpenAlex; if your firewall logs a block during registration, that’s what it was.
How do I let OpenAlex’s page checks through?
Besides harvesting your OAI-PMH feed, we look at the page or file each new record points to, to confirm there’s a free copy and read its license. That check is what makes your records count as open access in OpenAlex and Unpaywall, so a bot wall in front of your record pages (a Cloudflare challenge, Anubis, a “confirm you are human” page) makes your open copies look closed.
How much we ask for, measured over the 30 days to 17 November 2026 across about 8,000 repositories:
- Each new or changed record once: its page, and its file when the record lists one. A fetch that fails for a passing reason (a timeout, a 429) is retried at most three times over a week.
- Runs every four hours, at most 3,000 of your pages per run and never more than 10 at once.
- Half of repositories get under one page request a day from us; 95% get fewer than about 60. A repository that adds or re-dates many records at once sees more for a few days.
By default these checks go through a third-party service (Zyte), from addresses we can’t name. If you allowlist our harvester’s IP and User-Agent (above) for your record and file pages too and tell us, we put your repository on our list and fetch its pages from 44.208.99.237 with that User-Agent. If a page from that address is still challenged, we fall back to the usual route, so allowlisting can only help. To get on the list, reply to our email or write to support@openalex.org with your repository’s address.
How often do you harvest, and how long until a new deposit shows up?
Daily. One run checks every registered endpoint for records changed since its last successful harvest (re-overlapping by a day so nothing at the boundary is missed). A deposit made today is normally in OpenAlex within a day or two of harvest, once it has been parsed and matched. A newly registered repository’s first run fetches the entire back catalog in one pass; for a large or slow endpoint that can take days. If your Harvest tab’s last new records received date doesn’t move after you deposit, check that the record’s datestamp actually changed: we ask for records by from date, so a deposit stamped in the past isn’t new to us.
How can I make my records match better?
Three metadata habits make the biggest difference:
- Report DOIs cleanly. A record with the published version’s DOI matches reliably; without one, matching falls back to title + first author. If you also mint your own DOI for a deposit, keep the publisher’s DOI in the record too.
- Put the license in the record. A
dc:rightselement with a license URL beats hoping we detect the license from the full text. See License reporting for the exact format. - Report the version when you’ve verified it.
publishedVersion,acceptedVersion, orsubmittedVersionin adc:typeelement, see Version reporting. This one has funder-compliance stakes: a paper reported assubmittedVersionwhen you hold the accepted manuscript can look non-compliant downstream. If you haven’t verified the version, leave it out and we’ll determine it automatically.
How do I make my records count as open access?
For ordinary oai_dc records, you can help OpenAlex establish that your copy is open access in two ways:
- Put a recognized license or access statement in
dc:rights. - Provide a document URL where we can find qualifying full-text or license evidence.
A recognized open license or access statement can establish OA without a successful fetch. Your record still needs a usable URL after parsing; otherwise this ingest path drops it. We can sometimes derive one from dc:relation or a PubMed Central id, but don’t rely on that. Give both.
The license
Put your license in dc:rights, as its URL or name. The ordinary oai_dc parser doesn’t read dc:license, dcterms:license, dcterms:accessRights or oaire:licenseCondition for this purpose. These values establish OA for records that pass the other ingest checks:
In dc:rights | Normalized metadata license |
|---|---|
https://creativecommons.org/licenses/by/4.0/ or CC BY 4.0 | cc-by |
https://creativecommons.org/licenses/by-sa/4.0/ or CC BY-SA 4.0 | cc-by-sa |
https://creativecommons.org/licenses/by-nd/4.0/ or CC BY-ND 4.0 | cc-by-nd |
https://creativecommons.org/licenses/by-nc/4.0/ or CC BY-NC 4.0 | cc-by-nc |
https://creativecommons.org/licenses/by-nc-sa/4.0/ or CC BY-NC-SA 4.0 | cc-by-nc-sa |
https://creativecommons.org/licenses/by-nc-nd/4.0/ or CC BY-NC-ND 4.0 | cc-by-nc-nd |
https://creativecommons.org/publicdomain/zero/1.0/ (the URL; a bare CC0 isn’t recognised) | public-domain |
https://creativecommons.org/publicdomain/mark/1.0/ or Public domain | public-domain |
info:eu-repo/semantics/openAccess | other-oa (open, without a specific license) |
The CC BY examples also work with versions 3.0 and 2.0. When normalizing the selected value, we ignore case, spaces and hyphens. If you supply several dc:rights elements, we select the first containing the exact lowercase text creativecommons.org; otherwise we select the first value, so put the license before any copyright line. Your repository’s name, a bare copyright statement, or a license in any other field doesn’t count.
The URL
Put your landing page, PDF, or both in separate dc:identifier elements. A DOI link alone doesn’t count as your repository copy. A successfully fetched, valid article PDF can establish OA; a URL that merely looks like a PDF cannot. HTML pages can supply license evidence or links to PDFs; see Locating the full-text document. Make your document accessible without logging in, from outside your network.
Example metadata fields:
<dc:title>A study of coastal biodiversity</dc:title>
<dc:creator>Martin, Alex</dc:creator>
<dc:identifier>https://repository.example/items/123</dc:identifier>
<dc:identifier>https://repository.example/files/123.pdf</dc:identifier>
<dc:rights>https://creativecommons.org/licenses/by/4.0/</dc:rights>
<dc:type>acceptedVersion</dc:type>
Two notes. This establishes the status of your copy; the work’s overall OA category also depends on its other locations. A recognized open license or access statement doesn’t stop us fetching the document when we can; it means your copy’s OA status doesn’t depend on that fetch.
See also License reporting and Version reporting on the data page.
How do I report a repository problem?
Email support@openalex.org or use openalex.org/contact. Before you write, spend two minutes on the Harvest tab: it answers most “are you harvesting us?” questions, and its error text is the first thing we’d ask for.
A report we can act on has five things. The one that matters most is several examples: one record can be a coincidence, five is a pattern we can fix.
Subject: Repository problem: <one line, e.g. "accepted manuscripts showing as submittedVersion">
OpenAlex source: https://openalex.org/sources/S<id>
OAI-PMH endpoint: https://…/oai (the base URL, not your homepage)
Harvest tab status + error text, if any:
What's wrong:
What we expected:
Examples (3–5, ideally both a case that works and cases that don't):
https://openalex.org/W… DOI 10.… OAI record id oai:… what's wrong with this one
…
If it's about counts: which number, from where, and what you expected instead.
Paste evidence into the message rather than attaching a screenshot; we read the text, and links we can click are worth more than pictures of them. If a record is wrong in OpenAlex but right in your repository, say so, and include the OAI record identifier so we can look at what your endpoint served us.
Things to check first, because they’re the usual answers:
- Is it a count question? Read why only some records show up and why the count went down.
- Is it an OA status or license question on a specific work? That’s a data-error report, not a harvest problem: see How do I fix a work’s open-access status?. Check the PDF is reachable from outside your campus network first.
- Is it a harvest failure? The status table above says what each one means and what fixes it.
Whatever it is, if it isn’t explained by the time you’ve looked, write to us. We’d rather read a ticket than have you guess.
Last updated
View as Markdown