NCBI Datasets API

Free NCBI Datasets v2 API with no key. Query genome assemblies, gene and taxonomy metadata for any organism and build download packages. Tested curl example and live response.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the NCBI Datasets API?

The NCBI Datasets API is a free REST interface to NCBI's genome, gene, taxonomy and virus data. It returns structured assembly reports — accession, assembly level, contig statistics, annotation release and BioProject links — and can assemble download packages of sequence and annotation files.

Datasets is NCBI's answer to a long-standing complaint: getting a genome out of NCBI used to mean navigating FTP directory trees and parsing assembly report text files. The v2 API replaces that with ordinary JSON over HTTP, keyed by things people actually have to hand — a taxon name or taxid, an assembly accession, a gene symbol.

Two details save a lot of time. First, the paired GenBank and RefSeq accessions for the same assembly are both present in a single report, along with a `manual_diff` note explaining exactly where the two copies differ, which is otherwise buried in NCBI documentation. Second, the service reports its throttle in `X-RateLimit-*` headers — the example below came back with a limit of 5 — so you can back off precisely instead of guessing. The path still carries a `v2alpha` segment; NCBI has kept it stable for years but it is worth pinning in code you do not want to revisit.

Quick facts

Base URL: https://api.ncbi.nlm.nih.gov/datasets/v2alpha
Authentication: No key required. An optional NCBI API key raises the rate limit and is sent in an `api-key` header, but every endpoint here works without one.
Rate limit: Reported live in `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Anonymous clients are throttled to a handful of requests per second; an NCBI API key roughly doubles it.
Pricing: Free. NCBI data is US government work and is not subject to copyright in the United States.
CORS: Enabled — callable directly from browser JavaScript
Official docs: Read the docs

How to use the NCBI Datasets API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch the current human genome assembly report

GET https://api.ncbi.nlm.nih.gov/datasets/v2alpha/genome/taxon/9606/dataset_report?page_size=1

curl

curl 'https://api.ncbi.nlm.nih.gov/datasets/v2alpha/genome/taxon/9606/dataset_report?page_size=1' \
  -H 'Accept: application/json'

JavaScript (fetch)

const res = await fetch("https://api.ncbi.nlm.nih.gov/datasets/v2alpha/genome/taxon/9606/dataset_report?page_size=1", {
  headers: {
    "Accept": "application/json",
  },
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);

Python (requests)

import requests

headers = {
    "Accept": "application/json",
}

res = requests.get("https://api.ncbi.nlm.nih.gov/datasets/v2alpha/genome/taxon/9606/dataset_report?page_size=1", headers=headers, timeout=20)
res.raise_for_status()
print(res.json())

Response — HTTP 200 (truncated)

{
  "reports": [
    {
      "accession": "GCA_000001405.29",
      "current_accession": "GCA_000001405.29",
      "paired_accession": "GCF_000001405.40",
      "source_database": "SOURCE_DATABASE_GENBANK",
      "organism": {
        "tax_id": 9606,
        "organism_name": "Homo sapiens",
        "common_name": "human"
      },
      "assembly_info": {
        "assembly_level": "Chromosome",
        "assembly_status": "current",
        "paired_assembly": {
          "accession": "GCF_000001405.40",
          "status": "current",
          "annotation_name": "GCF_000001405.40-RS_2025_08",
          "only_genbank": "4 unlocalized and unplaced scaffolds",
          "manual_diff": "RefSeq dropped two scaffolds that are predominantly rodent or bacterial in origin (KI270752.1/NT_187507.1 and KI270825.1/NT_187580.1), and dropped two unlocalized scaffolds that are now thought to be redundant with assembled chromosome sequence (KI270721.1/NT_187376.1 and KI270734.1/NT_187389.1)",
          "refseq_genbank_are_different": true,
          "differences": "Removed 4 unlocalized and unplaced scaffolds; RefSeq dropped two scaffolds that are predominantly rodent or bacterial in origin (KI270752.1/NT_187507.1 and KI270825.1/NT_187580.1), and dropped two unlocalized scaffolds that are now thought to be redundant with assembled chromosome sequence (KI270721.1/NT_187376.1 and KI270734.1/NT_187389.1)"
        },
        "assembly_name": "GRCh38.p14",
        "assembly_type": "haploid-with-alt-loci",
        "bioproject_lineage": [
          {
            "bioprojects": [
              {

Parameters

Parameter	Type	Required	Description
`taxon`	path segment	Optional	Taxonomy name or NCBI taxid. `9606` and `human` both resolve to Homo sapiens. `9606`
`accession`	path segment	Optional	An assembly accession, used instead of a taxon for an exact lookup. `GCF_000001405.40`
`page_size`	query	Optional	Results per page, up to 1000. Defaults to 20. `1`
`page_token`	query	Optional	Opaque cursor returned as `next_page_token`; the only supported way to page. `eyJ...`
`filters.assembly_level`	query	Optional	Restrict to assemblies of a given quality, such as `chromosome` or `complete_genome`. `chromosome`
`filters.reference_only`	query	Optional	Return only the designated reference assembly for the taxon. `true`

Response fields

reports[].accessionstring: Assembly accession. `GCA_` prefixes are GenBank submissions, `GCF_` are the RefSeq curated copies.
reports[].paired_accessionstring: The matching accession in the other database, with a `manual_diff` note describing any curation differences.
assembly_info.assembly_levelstring: `Complete Genome`, `Chromosome`, `Scaffold` or `Contig` — the single best proxy for assembly quality.
assembly_info.assembly_namestring: Human-readable build name such as `GRCh38.p14`.
organismobject: `tax_id`, `organism_name` and `common_name` for the assembly's source organism.
next_page_tokenstring: Cursor for the next page. Absent on the final page.

What you can build with the NCBI Datasets API

Look up the current reference assembly and accession for any species
Build a table of available genomes for a clade before choosing one to download
Resolve an assembly accession to its assembly level and annotation release
Automate reference-genome updates in a bioinformatics pipeline
Cross-reference GenBank and RefSeq accessions for the same assembly

Common errors and how to fix them

429

Rate limit exceeded.

Fix: Read `X-RateLimit-Remaining` on every response and pause when it approaches zero. Requesting an NCBI API key raises the ceiling.

400

Unrecognised taxon or malformed filter name.

Fix: Filters are nested query parameters written as `filters.assembly_level=chromosome`. A typo in the prefix is silently rejected as a bad request.

Empty `reports`

The taxon exists but has no assemblies matching the filters.

Fix: Drop `filters.reference_only` first — many taxa have assemblies but no designated reference.

Truncated results

Only the first page was read.

Fix: Datasets pages with an opaque `next_page_token`, not an offset. Loop until the token is absent.

NCBI Datasets API — frequently asked questions

Do I need an API key for NCBI Datasets?

No. Every endpoint works anonymously. An NCBI API key is optional and only raises the rate limit, which is reported live in the `X-RateLimit-*` response headers so you can see exactly where you stand.

What is the difference between GCA and GCF accessions?

GCA accessions are the assembly exactly as the submitter deposited it in GenBank; GCF accessions are NCBI's RefSeq copy, which may drop contaminated scaffolds or add curated annotation. The report links the two and the `manual_diff` field spells out the differences.

Can I download genome sequence files through this API?

Yes, through the separate download endpoints, which return a zip package of the requested FASTA and annotation files. The metadata endpoint documented here returns JSON reports only.

Is NCBI Datasets the same as E-utilities?

No. E-utilities is the older, general-purpose interface across all Entrez databases and returns XML by default. Datasets is a newer, narrower JSON API focused on genomes, genes, taxonomy and virus data, and is much easier to consume for those specific tasks.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

JSON to CSV Converter

Convert a JSON array of objects to CSV online. Automatic column headers from the union of all keys, delimiter choice and proper quoting — all in-browser.

CSV Viewer & Table

View CSV as a clean HTML table online. Live search filter, row and column counts, delimiter and header options — all processed locally in your browser.

NCBI Datasets is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.