How to access Scopus

To access Scopus via its API, you need two things. First, your institution needs to be a subscriber (not only to Scopus, but really to its API); second, you need to register API keys at For each profile, you may register 10 keys.

The Scopus API recognizes you as a member of your institution via IP range. For working from home, Scopus can also grant InstTokens. Thus one of three things needs to happen:

  1. You are in your instition’s network

  2. You use your instition’s VPN

  3. You use an InstToken

Option 1 is easy and the most common.

Option 2 might require you to additionally set a proxy. You can do so in the configuration file.

Option 3 is rare. If you have an InstToken, please provide it during the setup when pybliometrics prompts you for it. Alternatively, add it to the configuration file manually.

There are only three Scopus APIs that you can access without your institution subscribing to it: The Abstract Retrieval API, Scopus Search API and the Subject Classifications API.

As a non-subscriber, use view=META in the AbstractRetrieval() class. You get more information with other views that only subscribers are entitled too. To search for for documents via the Scopus Search API as a non-subscriber, set subscriber=False in the ScopusSearch(). This retrieve but a subset of the information a subscriber has access to. The Subject Classifications API is the same for subscribers and non-subscribers.

API Key quotas and 429 error

Each API key has a certain usage limit for different Scopus APIs. See for the list; for example, a key allows for 5,000 retrieval requests, or 20,000 search requests via the Scopus Search API.

One week after the first usage, Scopus resets the key.

pybliometrics will use all the keys provided in the configuration file when one key exceeded its quota for the given API. Be sure to put all keys in the config.ini.

When the last key has been depleted as well, pybliometrics throws an a pybliometrics.scopus.exception.Scopus429Error. In this case you need to restart the application one week after it has been started.

Error messages

pybliometrics raises exceptions if download status is not ok. In this case, no information gets cached. To allow for error-specific handling, pybliometrics defines the following exceptions:


Base class for the following exceptions.


When a search query returns more results than specified or allowed (Scoups allows 5000 results maximum). Change the query such that less than or equal to 5000 results are returned.


Base class for the following exceptions raised through the requests package.

pybliometrics.scopus.exception.Scopus400Error: BAD REQUEST

Usually an invalid search query, such as a missing parenthesis. Verify that your query works in Advanced Search.

pybliometrics.scopus.exception.Scopus401Error: UNAUTHORIZED

Either the provided key is not correct, in which case you should change it in ~/.scopus/config.ini, or you are outside the network that provides you access to the Scopus database (e.g. your university network). Remember that you need both to access Scopus.

pybliometrics.scopus.exception.Scopus404Error: NOT FOUND

The entity you are looking for does not exist. Check that your identifier is still pointing to the item you are looking for.

pybliometrics.scopus.exception.Scopus414Error: TOO LARGE

The query string you are using is too long. Break it up in smaller pieces.

pybliometrics.scopus.exception.Scopus429Error: QUOTA EXCEEDED

Your provided API key’s weekly quota has been depleted. If you provided multiple keys in your configuration file, this means all your keys are depleted. In this case, wait up to week until your API key’s quota has been reset.

pybliometrics.scopus.exception.Scopus500Error: INTERNAL SERVER ERROR

Formally, the server does not respond, for various reasons. A common reason in searches is that you use a fieldname that does not exist. Verify that your query works in Scopus’ Advanced Search.

pybliometrics.scopus.exception.Scopus502Error: BAD GATEWAY

Formally, the server does not respond, for various reasons.

If queries break for other reasons, exceptions of type requests.exceptions are raised, such as:

requests.exceptions.TooManyRedirects: Exceeded 30 redirects.

The entity you are looking for was not properly merged with another one entity in the sense that it is not forwarding. Happens rarely when Scopus Author profiles are merged. May also occur less often with Abstract EIDs and Affiliation IDs.