API keys

We will turn on rate-limiting for all NCBI Datasets command-line tool and API requests in January 2025. Before that time, we have made a temporary rate-limited URL available for testing. We encourage you to get your own API key and test the temporary rate-limited URL with your API key today.

API keys provide enhanced access to the NCBI Datasets API and command-line tools by allowing you to exceed the default rate limits. This documentation will guide you through how to get your own API key and use it with NCBI Datasets.

Get your API key

To get your API key, follow these steps:

1. While signed in to your My NCBI account, go to your NCBI Account Settings. If you don’t have a My NCBI account, you’ll need to create one.

2. Scroll to the bottom of the page to find the “API Key Management” section.

3. Click the “Create API Key” button. A unique sequence of characters will be generated and displayed in the “API Key Management” box. This is your API key.

Use your API key with NCBI Datasets

You can use your API key with the NCBI Datasets command-line tools and API.

Use your API key with the NCBI Datasets command-line tools

To use your API key with the NCBI Datasets command-line tools, you have two options:

1. Add your API key as a parameter in each command

2. Set the API key to the NCBI_API_KEY environment variable and the command-line tool will use the API key automatically

To use your API key as a parameter in a given command, use the --api-key flag:

datasets summary genome accession --inputfile accession-list.txt --api-key <PUT_YOUR_API_KEY_HERE>

Alternatively, you can set the NCBI_API_KEY environment variable and the command-line tool will use the API key automatically. Use export to set the environment variable as follows:

export NCBI_API_KEY=<PUT_YOUR_API_KEY_HERE>

Use your API key with the NCBI Datasets API

To use your API key with the NCBI Datasets API, you have two options:

1. Specify your API key as a URL parameter

2. Pass your API key as a header

For example, this is how you would specify your API key as a URL parameter:

https://api.ncbi.nlm.nih.gov/datasets/v2/gene/accession/NM_021803.4?api_key=<PUT_YOUR_API_KEY_HERE>

Alternatively, this is how you would pass your API key as a header:

curl -X GET "https://api.ncbi.nlm.nih.gov/datasets/v2/gene/accession/NM_021803.84" \
 -H "Accept: application/json" \
 -H "api-key: <PUT_YOUR_API_KEY_HERE>"

Test the rate-limited URL with your API key

We will turn on rate-limiting for all command-line tool and API requests in January 2025. Before that time, we have made a temporary rate-limited URL available for testing. We encourage you to try the temporary URL with your API key and share your feedback using the yellow feedback button on this page.

The temporary rate-limited URL can be tested with the NCBI Datasets command-line tools and API.

Test the rate-limited URL with the NCBI Datasets command-line tools

To test the temporary rate-limited URL and your API key with the NCBI Datasets command-line tools, use the --gateway-url flag with the --api-key flag:

datasets summary genome accession --inputfile accession-list.txt --api-key <PUT_YOUR_API_KEY_HERE> --gateway-url https://api.ncbi.nlm.nih.gov/datasets/test/v2/

Test the rate-limted URL with the NCBI Datasets API

To test the temporary rate-limited URL and your API key with the NCBI Datasets API, use the test version of the desired API endpoint, with the word “test” preceding “v2”, while specifying your API key as a URL parameter or as a header.

For example, here is an example of the rate-limited test URL (note that the URL contains the word “test/” before “v2”), where your API key is specified as a URL parameter:

https://api.ncbi.nlm.nih.gov/datasets/test/v2/gene/accession/NM_021803.4?api_key=<PUT_YOUR_API_KEY_HERE>

Alternatively, this is how you pass your API key as a header with the rate-limited test URL:

curl -X GET "https://api.ncbi.nlm.nih.gov/datasets/test/v2/gene/accession/NM_021803.84" \
 -H "Accept: application/json" \
 -H "api-key: <PUT_YOUR_API_KEY_HERE>"

Have more questions about API keys?

Refer to our FAQs for answers to common questions about API keys and rate limits or contact us using the yellow feedback button on this page.