# NCBI Datasets

> Look up genes, genomes, taxa and viruses in NCBI's databases from a workflow. Find genes by ID, symbol or accession, search an organism's genes, and list a gene's orthologs, transcripts and tissue expression; look up and search genome assemblies, list the genes and chromosomes of one and its versions; read a taxon's lineage, search taxon names and list the taxa within one; search and read virus genome sequences, BioSamples and organelle genomes. A trigger starts a workflow when NCBI releases a new genome assembly for a taxon. No account or API key required.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/ncbi-datasets

## Actions

### Find genes by accession

Find the gene behind RefSeq transcript, protein or genomic accessions, such as NM_007294.4 or NP_009225.1, and get its full gene record.

**Inputs**

- RefSeq accessions (`accessions`, text, required): One or more RefSeq accessions, separated by commas, such as NM_007294.4 (a transcript) or NP_009225.1 (a protein). Up to 100.

**Outputs**

- `count` (number): How many are listed here.
- `genes` (list): The genes found.
- `not_found` (list): What was asked for that NCBI has no record of.

**Example output**

```json
{
  "count": 1,
  "genes": [
    {
      "assembly": "GRCh38.p14",
      "assembly_accession": "GCF_000001405.40",
      "biological_processes": [
        "DNA damage response",
        "DNA damage tolerance",
        "DNA repair"
      ],
      "cellular_components": [
        "BRCA1-A complex",
        "BRCA1-B complex",
        "BRCA1-BARD1 complex"
      ],
      "chromosomes": [
        "17"
      ],
      "common_name": "human",
      "end": 43170327,
      "ensembl_gene_ids": [
        "ENSG00000012048"
      ],
      "gene_id": "672",
      "map_location": "17q21.31",
      "molecular_functions": [
        "DNA binding",
        "RNA binding",
        "RNA polymerase binding"
      ],
      "name": "BRCA1 DNA repair associated",
      "nomenclature_id": "HGNC:1100",
      "omim_ids": [
        "113705"
      ],
      "organism": "Homo sapiens",
      "orientation": "minus",
      "other_names": [
        "BRCA1/BRCA2-containing complex, subunit 1",
        "Fanconi anemia, complementation group S"
      ],
      "protein_count": 368,
      "sequence_accession": "NC_000017.11",
      "start": 43044295,
      "summary": "This gene encodes a 190 kD nuclear phosphoprotein that plays a role in maintaining genomic stability, and it also acts as a tumor suppressor. The BRCA1 gene contains 22 exons spanning about 110 kb of DNA.",
      "swiss_prot_accessions": [
        "P38398"
      ],
      "symbol": "BRCA1",
      "synonyms": [
        "IRIS",
        "PSCP",
        "BRCAI"
      ],
      "tax_id": 9606,
      "transcript_count": 368,
      "type": "Protein coding",
      "url": "https://www.ncbi.nlm.nih.gov/gene/672"
    }
  ],
  "not_found": []
}
```

### Find genes by symbol

Find genes by their official symbol, such as BRCA1 or TP53, in one organism, and get the full gene record for each, Gene ID included. Symbols NCBI does not have are listed as not found.

**Inputs**

- Gene symbols (`symbols`, text, required): One or more gene symbols, separated by commas, such as BRCA1 or BRCA1, TP53. Up to 100.
- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.

**Outputs**

- `count` (number): How many are listed here.
- `genes` (list): The genes found.
- `not_found` (list): What was asked for that NCBI has no record of.
- `taxon` (object): The taxon searched, as NCBI names it.

**Example output**

```json
{
  "count": 1,
  "genes": [
    {
      "assembly": "GRCh38.p14",
      "assembly_accession": "GCF_000001405.40",
      "biological_processes": [
        "DNA damage response",
        "DNA damage tolerance",
        "DNA repair"
      ],
      "cellular_components": [
        "BRCA1-A complex",
        "BRCA1-B complex",
        "BRCA1-BARD1 complex"
      ],
      "chromosomes": [
        "17"
      ],
      "common_name": "human",
      "end": 43170327,
      "ensembl_gene_ids": [
        "ENSG00000012048"
      ],
      "gene_id": "672",
      "map_location": "17q21.31",
      "molecular_functions": [
        "DNA binding",
        "RNA binding",
        "RNA polymerase binding"
      ],
      "name": "BRCA1 DNA repair associated",
      "nomenclature_id": "HGNC:1100",
      "omim_ids": [
        "113705"
      ],
      "organism": "Homo sapiens",
      "orientation": "minus",
      "other_names": [
        "BRCA1/BRCA2-containing complex, subunit 1",
        "Fanconi anemia, complementation group S"
      ],
      "protein_count": 368,
      "sequence_accession": "NC_000017.11",
      "start": 43044295,
      "summary": "This gene encodes a 190 kD nuclear phosphoprotein that plays a role in maintaining genomic stability, and it also acts as a tumor suppressor. The BRCA1 gene contains 22 exons spanning about 110 kb of DNA.",
      "swiss_prot_accessions": [
        "P38398"
      ],
      "symbol": "BRCA1",
      "synonyms": [
        "IRIS",
        "PSCP",
        "BRCAI"
      ],
      "tax_id": 9606,
      "transcript_count": 368,
      "type": "Protein coding",
      "url": "https://www.ncbi.nlm.nih.gov/gene/672"
    }
  ],
  "not_found": [
    "NOPE1"
  ],
  "taxon": {
    "common_name": "human",
    "name": "Homo sapiens",
    "rank": "Species",
    "tax_id": 9606
  }
}
```

### Find genome by sequence

Find the genome assembly a chromosome or other sequence accession belongs to, such as NC_000001.11, and get that assembly's record.

**Inputs**

- Sequence accession (`sequence_accession`, text, required): A chromosome, scaffold or contig accession, such as NC_000001.11 (human chromosome 1).

**Outputs**

- `count` (number): How many are listed here.
- `genomes` (list): The assemblies that contain it.
- `sequence_accession` (text): The sequence looked up.

**Example output**

```json
{
  "count": 1,
  "genomes": [
    {
      "accession": "GCF_000001405.40",
      "annotation_date": "2025-08-01",
      "annotation_name": "GCF_000001405.40-RS_2025_08",
      "annotation_provider": "NCBI RefSeq",
      "assembly_level": "Chromosome",
      "assembly_method": "",
      "assembly_name": "GRCh38.p14",
      "assembly_status": "current",
      "bioproject": "PRJNA31257",
      "biosample": "",
      "busco_complete_percent": 98.9,
      "checkm_completeness": null,
      "checkm_contamination": null,
      "chromosome_count": 24,
      "common_name": "human",
      "contig_count": 996,
      "contig_n50": 57879411,
      "description": "Genome Reference Consortium Human Build 38 patch release 14 (GRCh38.p14)",
      "gc_percent": 41.0,
      "gene_count": 59792,
      "is_reference": true,
      "organism": "Homo sapiens",
      "paired_accession": "GCA_000001405.29",
      "protein_coding_gene_count": 20076,
      "release_date": "2022-02-03",
      "scaffold_count": 470,
      "scaffold_n50": 67794873,
      "sequencing_technology": "",
      "source": "RefSeq",
      "strain": "",
      "submitter": "Genome Reference Consortium",
      "tax_id": 9606,
      "total_length": 3099441038,
      "ungapped_length": 2948318359,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/genome/GCF_000001405.40/"
    }
  ],
  "sequence_accession": "NC_000001.11"
}
```

### Get a taxon

Get a taxon from NCBI Taxonomy by ID or name: its scientific and common names, rank, lineage from domain to species, parent and children, genetic code, and how many genome assemblies and genes NCBI holds for it.

**Inputs**

- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.

**Outputs**

- `authority` (text): Who named it, and when, e.g. 'Linnaeus, 1758'.
- `child_tax_ids` (list): The taxa directly below it.
- `classification` (object): Its place in the main ranks, from domain to species.
- `common_name` (text): The common name NCBI gives it, e.g. 'human'.
- `gene_count` (number): How many gene records NCBI holds for it.
- `genetic_code` (text): Its genetic code, e.g. 'Standard'.
- `genome_count` (number): How many genome assemblies NCBI holds for it.
- `group` (text): The broad group NCBI files it under, e.g. 'primates'.
- `lineage_tax_ids` (list): Every taxon above it, from the root down.
- `mitochondrial_genetic_code` (text): Its mitochondrial genetic code.
- `name` (text): The scientific name, e.g. 'Homo sapiens'.
- `parent_tax_id` (number): The Taxonomy ID of the taxon directly above it.
- `protein_coding_gene_count` (number): How many of those genes are protein coding.
- `rank` (text): The rank, e.g. 'Species' or 'Order'. Empty when it has none.
- `tax_id` (number): The NCBI Taxonomy ID, e.g. 9606 for human.
- `url` (text): The taxon's page on NCBI Datasets.

**Example output**

```json
{
  "authority": "Linnaeus, 1758",
  "child_tax_ids": [
    741158,
    63221
  ],
  "classification": {
    "class": "Mammalia",
    "domain": "Eukaryota",
    "family": "Hominidae",
    "genus": "Homo",
    "kingdom": "Metazoa",
    "order": "Primates",
    "phylum": "Chordata",
    "species": "Homo sapiens"
  },
  "common_name": "human",
  "gene_count": 194025,
  "genetic_code": "Standard",
  "genome_count": 2587,
  "group": "primates",
  "lineage_tax_ids": [
    1,
    131567,
    2759,
    33154
  ],
  "mitochondrial_genetic_code": "Vertebrate Mitochondrial",
  "name": "Homo sapiens",
  "parent_tax_id": 9605,
  "protein_coding_gene_count": 20601,
  "rank": "Species",
  "tax_id": 9606,
  "url": "https://www.ncbi.nlm.nih.gov/datasets/taxonomy/9606/"
}
```

### Get BioSamples

Look up BioSample records by accession and get each sample's organism, owner, dates, BioProjects, where and when it was collected, and every attribute its submitter recorded.

**Inputs**

- BioSample accessions (`accessions`, text, required): One or more BioSample accessions, separated by commas, such as SAMN15960293. Up to 100.

**Outputs**

- `biosamples` (list): The BioSamples found, in the order asked.
- `count` (number): How many are listed here.
- `not_found` (list): What was asked for that NCBI has no record of.

**Example output**

```json
{
  "biosamples": [
    {
      "accession": "SAMN15960293",
      "attributes": [
        {
          "name": "isolate",
          "value": "bGalGal1"
        },
        {
          "name": "age",
          "value": "35 days"
        },
        {
          "name": "sex",
          "value": "female"
        },
        {
          "name": "tissue",
          "value": "Blood"
        }
      ],
      "bioprojects": [],
      "collection_date": "2019-05-20",
      "comment": "The chicken has been the most studied bird. It serves as a model organism for basic and biomedical science, and is one of the most commonly consumed food sources for humans.",
      "host": "",
      "isolate": "bGalGal1",
      "last_updated": "2024-08-20",
      "location": "USA:Fayetteville, Arkansas",
      "organism": "Gallus gallus",
      "owner": "G10K",
      "package": "Model.organism.animal.1.0",
      "publication_date": "2020-09-01",
      "sample_name": "Chicken sample for VGP-GRC reference genome child of trio",
      "sex": "female",
      "sra_id": "SRS22402101",
      "status": "live",
      "strain": "",
      "submission_date": "2020-09-01",
      "tax_id": 9031,
      "tissue": "Blood",
      "title": "Animal sample from Gallus gallus (bGalGal3)",
      "url": "https://www.ncbi.nlm.nih.gov/biosample/SAMN15960293"
    }
  ],
  "count": 1,
  "not_found": []
}
```

### Get gene expression by tissue

Get how strongly a gene is expressed in each tissue, in transcripts per million, from the RNA-seq studies NCBI summarises. NCBI holds this for human genes; for others the list is empty.

**Inputs**

- Gene ID (`gene_id`, text, required): The gene's NCBI Gene ID, such as 672 for human BRCA1. Find one with Find genes by symbol or Search genes in an organism.

**Outputs**

- `count` (number): How many are listed here.
- `gene_id` (text): The gene's NCBI Gene ID.
- `release` (text): The annotation release the values were computed on.
- `tissues` (list): One row per study and tissue, highest expression first.
- `unit` (text): The unit of the values, e.g. 'TPM' (transcripts per million).

**Example output**

```json
{
  "count": 2,
  "gene_id": "672",
  "release": "GCF_000001405.40-RS_2023_10",
  "tissues": [
    {
      "bioproject": "PRJEB4337",
      "mean": 20.393333,
      "sample_count": 4,
      "standard_deviation": 11.454346,
      "study": "HPA RNA-seq normal tissues",
      "tissue": "Thyroid"
    },
    {
      "bioproject": "PRJEB4337",
      "mean": 20.0575,
      "sample_count": 7,
      "standard_deviation": 2.954923,
      "study": "HPA RNA-seq normal tissues",
      "tissue": "Testis"
    }
  ],
  "unit": "TPM"
}
```

### Get genes

Look up one or more genes by NCBI Gene ID and get each one's symbol, full name, organism, chromosome and position on the reference genome, RefSeq summary, synonyms, matching Ensembl, OMIM and UniProt IDs, transcript and protein counts, and Gene Ontology terms.

**Inputs**

- Gene IDs (`gene_ids`, text, required): One or more NCBI Gene IDs, separated by commas, such as 672 or 672, 7157. Up to 100.

**Outputs**

- `count` (number): How many are listed here.
- `genes` (list): The genes found.
- `not_found` (list): What was asked for that NCBI has no record of.

**Example output**

```json
{
  "count": 1,
  "genes": [
    {
      "assembly": "GRCh38.p14",
      "assembly_accession": "GCF_000001405.40",
      "biological_processes": [
        "DNA damage response",
        "DNA damage tolerance",
        "DNA repair"
      ],
      "cellular_components": [
        "BRCA1-A complex",
        "BRCA1-B complex",
        "BRCA1-BARD1 complex"
      ],
      "chromosomes": [
        "17"
      ],
      "common_name": "human",
      "end": 43170327,
      "ensembl_gene_ids": [
        "ENSG00000012048"
      ],
      "gene_id": "672",
      "map_location": "17q21.31",
      "molecular_functions": [
        "DNA binding",
        "RNA binding",
        "RNA polymerase binding"
      ],
      "name": "BRCA1 DNA repair associated",
      "nomenclature_id": "HGNC:1100",
      "omim_ids": [
        "113705"
      ],
      "organism": "Homo sapiens",
      "orientation": "minus",
      "other_names": [
        "BRCA1/BRCA2-containing complex, subunit 1",
        "Fanconi anemia, complementation group S"
      ],
      "protein_count": 368,
      "sequence_accession": "NC_000017.11",
      "start": 43044295,
      "summary": "This gene encodes a 190 kD nuclear phosphoprotein that plays a role in maintaining genomic stability, and it also acts as a tumor suppressor. The BRCA1 gene contains 22 exons spanning about 110 kb of DNA.",
      "swiss_prot_accessions": [
        "P38398"
      ],
      "symbol": "BRCA1",
      "synonyms": [
        "IRIS",
        "PSCP",
        "BRCAI"
      ],
      "tax_id": 9606,
      "transcript_count": 368,
      "type": "Protein coding",
      "url": "https://www.ncbi.nlm.nih.gov/gene/672"
    }
  ],
  "not_found": []
}
```

### Get genome assemblies

Look up genome assemblies by accession and get each one's organism, assembly name and level, whether it is the reference genome, release date, submitter, size, GC content, contig and scaffold N50, gene annotation counts and quality scores.

**Inputs**

- Genome assembly accessions (`accessions`, text, required): One or more assembly accessions, starting GCF_ or GCA_, separated by commas, such as GCF_000001405.40. Without a version number, the current version is read. Up to 100.

**Outputs**

- `count` (number): How many are listed here.
- `genomes` (list): The assemblies found, in the order asked.
- `not_found` (list): What was asked for that NCBI has no record of.

**Example output**

```json
{
  "count": 1,
  "genomes": [
    {
      "accession": "GCF_000001405.40",
      "annotation_date": "2025-08-01",
      "annotation_name": "GCF_000001405.40-RS_2025_08",
      "annotation_provider": "NCBI RefSeq",
      "assembly_level": "Chromosome",
      "assembly_method": "",
      "assembly_name": "GRCh38.p14",
      "assembly_status": "current",
      "bioproject": "PRJNA31257",
      "biosample": "",
      "busco_complete_percent": 98.9,
      "checkm_completeness": null,
      "checkm_contamination": null,
      "chromosome_count": 24,
      "common_name": "human",
      "contig_count": 996,
      "contig_n50": 57879411,
      "description": "Genome Reference Consortium Human Build 38 patch release 14 (GRCh38.p14)",
      "gc_percent": 41.0,
      "gene_count": 59792,
      "is_reference": true,
      "organism": "Homo sapiens",
      "paired_accession": "GCA_000001405.29",
      "protein_coding_gene_count": 20076,
      "release_date": "2022-02-03",
      "scaffold_count": 470,
      "scaffold_n50": 67794873,
      "sequencing_technology": "",
      "source": "RefSeq",
      "strain": "",
      "submitter": "Genome Reference Consortium",
      "tax_id": 9606,
      "total_length": 3099441038,
      "ungapped_length": 2948318359,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/genome/GCF_000001405.40/"
    }
  ],
  "not_found": []
}
```

### Get genome assembly history

List every version of a genome assembly, newest first, with its name, GenBank and RefSeq accessions and release date.

**Inputs**

- Genome assembly accession (`accession`, text, required): The assembly's accession, starting GCF_ (RefSeq) or GCA_ (GenBank), such as GCF_000001405.40 for the human reference genome.

**Outputs**

- `accession` (text): The genome assembly asked about.
- `count` (number): How many are listed here.
- `revisions` (list): Every version, newest first.

**Example output**

```json
{
  "accession": "GCF_000001405.40",
  "count": 2,
  "revisions": [
    {
      "assembly_name": "GRCh38.p14",
      "genbank_accession": "GCA_000001405.29",
      "refseq_accession": "GCF_000001405.40",
      "release_date": "2022-02-03",
      "same_as_previous": false
    },
    {
      "assembly_name": "GRCh38.p13",
      "genbank_accession": "GCA_000001405.28",
      "refseq_accession": "GCF_000001405.39",
      "release_date": "2019-02-28",
      "same_as_previous": false
    }
  ]
}
```

### Get virus genomes

Look up virus genome sequences by GenBank or RefSeq accession and get each one's virus, isolate, host, place and date of collection, lineage, length and submitter.

**Inputs**

- Nucleotide accessions (`accessions`, text, required): One or more virus sequence accessions, separated by commas, such as NC_045512.2. Up to 100.

**Outputs**

- `count` (number): How many are listed here.
- `genomes` (list): The virus genomes found, in the order asked.
- `not_found` (list): What was asked for that NCBI has no record of.

**Example output**

```json
{
  "count": 1,
  "genomes": [
    {
      "accession": "NC_045512.2",
      "bioprojects": [
        "PRJNA485481"
      ],
      "biosample": "",
      "collection_date": "2019-12",
      "completeness": "Complete",
      "gene_count": 11,
      "host": "Homo sapiens",
      "host_tax_id": 9606,
      "is_annotated": true,
      "isolate": "Wuhan-Hu-1",
      "length": 29903,
      "lineage": "B",
      "location": "China",
      "protein_count": 12,
      "region": "Asia",
      "release_date": "2020-01-13",
      "segment": "",
      "source": "RefSeq",
      "submitter": "National Center for Biotechnology Information, NIH",
      "submitter_country": "USA",
      "update_date": "2020-07-18",
      "url": "https://www.ncbi.nlm.nih.gov/nuccore/NC_045512.2",
      "virus": "Severe acute respiratory syndrome coronavirus 2",
      "virus_tax_id": 2697049
    }
  ],
  "not_found": []
}
```

### List gene orthologs

List the genes in other species that NCBI groups as orthologs of a gene (the same gene, inherited from a common ancestor), optionally only within a group such as mammals or primates.

**Inputs**

- Gene ID (`gene_id`, text, required): The gene's NCBI Gene ID, such as 672 for human BRCA1. Find one with Find genes by symbol or Search genes in an organism.
- Only within (`taxon`, text): Only orthologs in this taxon: pick an organism or type any NCBI Taxonomy ID or name, such as mammals, primates or Vertebrata. Leave empty for every species.
- How many to return (`limit`, number): How many orthologs to return, 1 to 1,000. Defaults to 100; the total says how many there are. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many are listed here.
- `gene_id` (text): The gene whose orthologs these are.
- `orthologs` (list): The orthologs, the gene itself included.
- `taxon` (object): The group the orthologs were limited to, or null.
- `total_count` (number): How many orthologs there are in all.

**Example output**

```json
{
  "count": 1,
  "gene_id": "672",
  "orthologs": [
    {
      "chromosomes": [
        "17"
      ],
      "common_name": "human",
      "gene_id": "672",
      "name": "BRCA1 DNA repair associated",
      "organism": "Homo sapiens",
      "symbol": "BRCA1",
      "tax_id": 9606,
      "url": "https://www.ncbi.nlm.nih.gov/gene/672"
    }
  ],
  "taxon": {
    "common_name": "primates",
    "name": "Primates",
    "rank": "Order",
    "tax_id": 9443
  },
  "total_count": 35
}
```

### List gene transcripts and proteins

List a gene's RefSeq transcripts and the proteins they encode, the MANE Select transcript first, with lengths, isoforms, matching Ensembl IDs and where each sits on the genome.

**Inputs**

- Gene ID (`gene_id`, text, required): The gene's NCBI Gene ID, such as 672 for human BRCA1. Find one with Find genes by symbol or Search genes in an organism.
- How many to return (`limit`, number): How many transcripts to return, 1 to 1,000. Defaults to 100; the total says how many there are. From 1 to 1000. Default: `100`.

**Outputs**

- `count` (number): How many are listed here.
- `gene_id` (text): The gene's NCBI Gene ID.
- `name` (text): The gene's full name.
- `organism` (text): The organism's scientific name.
- `protein_count` (number): How many proteins the gene encodes.
- `symbol` (text): The gene's symbol.
- `total_count` (number): How many transcripts the gene has in all.
- `transcripts` (list): Its transcripts, MANE Select first.

**Example output**

```json
{
  "count": 1,
  "gene_id": "672",
  "name": "BRCA1 DNA repair associated",
  "organism": "Homo sapiens",
  "protein_count": 368,
  "symbol": "BRCA1",
  "total_count": 368,
  "transcripts": [
    {
      "accession": "NM_007294.4",
      "cds_end": 5705,
      "cds_start": 114,
      "end": 43125364,
      "ensembl_protein": "ENSP00000350283.3",
      "ensembl_transcript": "ENST00000357654.9",
      "exon_count": 23,
      "is_mane_select": true,
      "isoform": "isoform 1",
      "length": 7088,
      "name": "transcript variant 1",
      "orientation": "minus",
      "protein_accession": "NP_009225.1",
      "protein_length": 1863,
      "protein_name": "breast cancer type 1 susceptibility protein",
      "sequence_accession": "NC_000017.11",
      "start": 43044295,
      "type": "Protein coding",
      "url": "https://www.ncbi.nlm.nih.gov/nuccore/NM_007294.4"
    }
  ]
}
```

### List genes in a genome

List the genes annotated on a genome assembly, in genome order, optionally only those matching a name, of one kind, or within a region of a chromosome, with each gene's position and the proteins it encodes.

**Inputs**

- Genome assembly accession (`accession`, text, required): The assembly's accession, starting GCF_ (RefSeq) or GCA_ (GenBank), such as GCF_000001405.40 for the human reference genome.
- Search for (`search_text`, text): Only genes whose symbol, name or protein name matches, such as BRCA1 or kinase.
- Gene type (`gene_type`, text): Only genes of this kind, as the genome's annotation names it, such as protein-coding, lncRNA or tRNA.
- Chromosome (`sequence`, text): Only genes on this chromosome. Pick one of the genome's chromosomes, or type any of its sequence accessions.
- From position (`start`, number): With a chromosome, only genes overlapping the region from this base pair. At least 1.
- To position (`end`, number): With a chromosome, only genes overlapping the region up to this base pair. At least 1.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000. Default: `20`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `accession` (text): The genome assembly searched.
- `count` (number): How many are listed here.
- `genes` (list): The genes on this page, in genome order.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `total_count` (number): How many NCBI holds in all for this search.

**Example output**

```json
{
  "accession": "GCF_000005845.2",
  "count": 1,
  "genes": [
    {
      "end": 255,
      "gene_id": "944742",
      "locus_tag": "b0001",
      "name": "thr operon leader peptide",
      "orientation": "plus",
      "protein_accessions": [
        "NP_414542.1"
      ],
      "sequence_accession": "NC_000913.3",
      "start": 190,
      "symbol": "thrL",
      "type": "protein-coding",
      "url": "https://www.ncbi.nlm.nih.gov/gene/944742"
    }
  ],
  "next_page_token": "eNrjYo42jgUAAhcA-Q",
  "total_count": 4651
}
```

### List genome chromosomes

List the chromosomes and other sequences a genome assembly is made of, with their RefSeq, GenBank and UCSC names, lengths and GC content.

**Inputs**

- Genome assembly accession (`accession`, text, required): The assembly's accession, starting GCF_ (RefSeq) or GCA_ (GenBank), such as GCF_000001405.40 for the human reference genome.
- Chromosomes (`chromosome`, text): Only these chromosomes, by name, separated by commas, such as 17 or X, Y, MT. Leave empty for all.
- Kind of sequence (`role`, text): Only sequences of this kind. Leave empty for all, scaffolds and patches included. One of: `assembled-molecule` (Chromosomes and other assembled molecules), `unlocalized-scaffold` (Unlocalized scaffolds), `unplaced-scaffold` (Unplaced scaffolds), `alt-scaffold` (Alternate locus scaffolds), `fix-patch` (Fix patches), `novel-patch` (Novel patches).
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000. Default: `100`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `accession` (text): The genome assembly.
- `count` (number): How many are listed here.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `sequences` (list): Its sequences on this page, in order.

**Example output**

```json
{
  "accession": "GCF_000001405.40",
  "count": 1,
  "next_page_token": "",
  "sequences": [
    {
      "assembly_unit": "Primary Assembly",
      "chromosome": "17",
      "gc_percent": 45.5,
      "genbank_accession": "CM000679.2",
      "length": 83257441,
      "location_type": "Chromosome",
      "refseq_accession": "NC_000017.11",
      "role": "assembled-molecule",
      "sequence_name": "17",
      "ucsc_name": "chr17"
    }
  ]
}
```

### List taxa within a taxon

List the taxa below a taxon, such as the genera of a family or the species of a genus, at every rank or only the ranks chosen.

**Inputs**

- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.
- Ranks (`ranks`, list): Only taxa of these ranks. Leave empty for every rank below. One or more of: `KINGDOM`, `PHYLUM`, `CLASS`, `ORDER`, `FAMILY`, `GENUS`, `SPECIES`, `SUBSPECIES`, `STRAIN`.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 50. From 1 to 1000. Default: `50`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `count` (number): How many are listed here.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `taxa` (list): The taxa below it on this page.
- `taxon` (object): The taxon whose children these are.

**Example output**

```json
{
  "count": 1,
  "next_page_token": "EM3B3AE=",
  "taxa": [
    {
      "common_name": "",
      "group": "primates",
      "name": "Pongo",
      "parent_tax_id": 607660,
      "rank": "Genus",
      "tax_id": 9599,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/taxonomy/9599/"
    }
  ],
  "taxon": {
    "common_name": "great apes",
    "name": "Hominidae",
    "rank": "Family",
    "tax_id": 9604
  }
}
```

### Search genes in an organism

List an organism's genes, optionally only those whose symbol, name, alias or protein name matches some words and only of some kinds, such as protein coding genes or pseudogenes. Returns a page at a time with the total found.

**Inputs**

- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.
- Search for (`query`, text): Words to match against gene symbols, names, aliases, locus tags and protein names. Leave empty for every gene.
- Gene types (`gene_types`, list): Only genes of these kinds. Leave empty for all. One or more of: `PROTEIN_CODING` (Protein coding), `ncRNA` (Non-coding RNA), `PSEUDO` (Pseudogene), `tRNA` (Transfer RNA (tRNA)), `rRNA` (Ribosomal RNA (rRNA)), `snRNA` (Small nuclear RNA (snRNA)), `snoRNA` (Small nucleolar RNA (snoRNA)), `scRNA` (Small cytoplasmic RNA (scRNA)), `miscRNA` (Other RNA), `TRANSPOSON`, `BIOLOGICAL_REGION` (Biological region), `OTHER`.
- Include lower taxa (`include_lower_taxa`, true/false): Also include genes of the taxa below the one chosen, such as every species of a genus. Default: `false`.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000. Default: `20`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `count` (number): How many are listed here.
- `genes` (list): The genes on this page, in NCBI's order.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `query` (text): The words searched for, empty when none.
- `taxon` (object): The taxon searched, as NCBI names it.
- `total_count` (number): How many NCBI holds in all for this search.

**Example output**

```json
{
  "count": 1,
  "genes": [
    {
      "assembly": "GRCh38.p14",
      "assembly_accession": "GCF_000001405.40",
      "biological_processes": [
        "Ras protein signal transduction",
        "activation of protein kinase B activity",
        "bone mineralization involved in bone maturation"
      ],
      "cellular_components": [
        "alphav-beta3 integrin-IGF-1-IGF1R complex",
        "exocytic vesicle",
        "extracellular region"
      ],
      "chromosomes": [
        "12"
      ],
      "common_name": "human",
      "end": 102481839,
      "ensembl_gene_ids": [
        "ENSG00000017427"
      ],
      "gene_id": "3479",
      "map_location": "12q23.2",
      "molecular_functions": [
        "growth factor activity",
        "hormone activity",
        "insulin receptor binding"
      ],
      "name": "insulin like growth factor 1",
      "nomenclature_id": "HGNC:5464",
      "omim_ids": [
        "147440"
      ],
      "organism": "Homo sapiens",
      "orientation": "minus",
      "other_names": [
        "insulin-like growth factor 1",
        "insulin-like growth factor 1 (somatomedin C)"
      ],
      "protein_count": 13,
      "sequence_accession": "NC_000012.12",
      "start": 102395874,
      "summary": "The protein encoded by this gene is similar to insulin in function and structure and is a member of a family of proteins involved in mediating growth and development. The encoded protein is processed from a precursor, bound by a specific receptor, and secreted.",
      "swiss_prot_accessions": [
        "P05019"
      ],
      "symbol": "IGF1",
      "synonyms": [
        "IGF",
        "MGF",
        "IGFI"
      ],
      "tax_id": 9606,
      "transcript_count": 13,
      "type": "Protein coding",
      "url": "https://www.ncbi.nlm.nih.gov/gene/3479"
    }
  ],
  "next_page_token": "eNrj4os2NDM3NrPQUTA2MbeMBQAYuQMz",
  "query": "insulin",
  "taxon": {
    "common_name": "human",
    "name": "Homo sapiens",
    "rank": "Species",
    "tax_id": 9606
  },
  "total_count": 39
}
```

### Search genome assemblies

List the genome assemblies of a species or any wider group, newest first, filtered to reference genomes, RefSeq or GenBank, assembly levels, annotated assemblies and a release date range. Returns a page at a time with the total found.

**Inputs**

- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.
- Reference genomes only (`reference_only`, true/false): Only the reference genome NCBI chose for each species. Default: `false`.
- Database (`source`, text): RefSeq holds NCBI's curated copies; GenBank holds what submitters deposited. Defaults to both. One of: `all` (RefSeq and GenBank), `refseq` (RefSeq only (accessions starting GCF_)), `genbank` (GenBank only (accessions starting GCA_)). Default: `all`.
- Assembly levels (`assembly_levels`, list): Only assemblies this complete. Leave empty for every level. One or more of: `complete_genome` (Complete genome), `chromosome`, `scaffold`, `contig`.
- Annotated only (`annotated_only`, true/false): Only assemblies with gene annotation. Default: `false`.
- Released on or after (`released_after`, date): Only those NCBI released on or after this date.
- Released on or before (`released_before`, date): Only those NCBI released on or before this date.
- This taxon only (`exact_taxon`, true/false): Only assemblies of exactly this taxon, leaving out its subspecies and strains. Default: `false`.
- Sort by (`sort`, text): The order to list them in. Defaults to newest first. One of: `newest` (Newest first (by release date)), `oldest` (Oldest first (by release date)), `contig_n50` (Most contiguous first (by contig N50)). Default: `newest`.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000. Default: `20`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `count` (number): How many are listed here.
- `genomes` (list): The assemblies on this page.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `taxon` (object): The taxon searched, as NCBI names it.
- `total_count` (number): How many NCBI holds in all for this search.

**Example output**

```json
{
  "count": 1,
  "genomes": [
    {
      "accession": "GCF_000008865.2",
      "annotation_date": "2021-02-12",
      "annotation_name": "Annotation submitted by NCBI RefSeq",
      "annotation_provider": "NCBI RefSeq",
      "assembly_level": "Complete Genome",
      "assembly_method": "",
      "assembly_name": "ASM886v2",
      "assembly_status": "current",
      "bioproject": "PRJNA226",
      "biosample": "SAMN01911278",
      "busco_complete_percent": null,
      "checkm_completeness": 99.51,
      "checkm_contamination": 0.15,
      "chromosome_count": 3,
      "common_name": "",
      "contig_count": 3,
      "contig_n50": 5498578,
      "description": "",
      "gc_percent": 50.5,
      "gene_count": 5417,
      "is_reference": true,
      "organism": "Escherichia coli O157:H7 str. Sakai",
      "paired_accession": "GCA_000008865.2",
      "protein_coding_gene_count": 5155,
      "release_date": "2018-06-08",
      "scaffold_count": 3,
      "scaffold_n50": 5498578,
      "sequencing_technology": "",
      "source": "RefSeq",
      "strain": "Sakai substr. RIMD 0509952",
      "submitter": "GIRC",
      "tax_id": 386585,
      "total_length": 5594605,
      "ungapped_length": 5594605,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/genome/GCF_000008865.2/"
    }
  ],
  "next_page_token": "eNrjUoo2NDWyMDE0MwADHQUld2e3eDDbwsLMVM9IKRYAg3QHWg",
  "taxon": {
    "common_name": "",
    "name": "Escherichia coli",
    "rank": "Species",
    "tax_id": 562
  },
  "total_count": 2
}
```

### Search organelle genomes

List the mitochondrial, chloroplast and other organelle genomes of a taxon, with their accessions, lengths, shapes and gene counts, optionally only some organelles or a release date range.

**Inputs**

- Organism or taxon (`taxon`, text, required): Pick an organism, or type any NCBI Taxonomy ID or name, scientific or common, such as 9606, Homo sapiens or human. A group such as Mammalia or Bacteria works too.
- Organelles (`organelle_types`, list): Only these organelles. Leave empty for all. One or more of: `Mitochondrion`, `Chloroplast`, `Plastid`, `Kinetoplast`, `Apicoplast`, `Chromatophore`, `Cyanelle`.
- Released on or after (`released_after`, date): Only those NCBI released on or after this date.
- Released on or before (`released_before`, date): Only those NCBI released on or before this date.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000. Default: `20`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `count` (number): How many are listed here.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `organelles` (list): The organelle genomes on this page.
- `taxon` (object): The taxon searched, as NCBI names it.
- `total_count` (number): How many NCBI holds in all for this search.

**Example output**

```json
{
  "count": 1,
  "next_page_token": "eNrj4o9W8nOONzA0NDQ21zNUigUAHrQDkg",
  "organelles": [
    {
      "common_name": "Neandertal",
      "genbank_accession": "AM948965.1",
      "gene_count": 37,
      "length": 16565,
      "organelle": "Mitochondrion",
      "organism": "Homo sapiens neanderthalensis",
      "refseq_accession": "NC_011137.1",
      "submission_date": "2008-08-14",
      "submitter": "National Center for Biotechnology Information, NIH",
      "tax_id": 63221,
      "topology": "Circular",
      "url": "https://www.ncbi.nlm.nih.gov/nuccore/NC_011137.1"
    }
  ],
  "taxon": {
    "common_name": "human",
    "name": "Homo sapiens",
    "rank": "Species",
    "tax_id": 9606
  },
  "total_count": 3
}
```

### Search taxa by name

Find taxa whose scientific or common names start with some text, as NCBI's search box suggests them, to get the Taxonomy ID for a species, strain or wider group.

**Inputs**

- Name starts with (`text`, text, required): The start of a scientific or common name, such as homo or zebra.
- Ranks (`scope`, text): Which ranks to suggest. Defaults to species and below. One of: `species` (Species and below), `higher_taxon` (Any rank, genus and family included). Default: `species`.
- With data (`data_filter`, text): Only taxa NCBI holds this kind of record for. Defaults to any taxon. One of: `all` (Any taxon), `genome` (Only taxa with genome assemblies), `gene` (Only taxa with gene records), `organelle` (Only taxa with organelle genomes). Default: `all`.
- Exact name only (`exact_match`, true/false): Only taxa whose name is exactly the text. Default: `false`.

**Outputs**

- `count` (number): How many are listed here.
- `taxa` (list): The matching taxa, best match first.
- `text` (text): The text searched for.

**Example output**

```json
{
  "count": 2,
  "taxa": [
    {
      "common_name": "human",
      "group": "primates",
      "matched_term": "Homo sapiens",
      "name": "Homo sapiens",
      "rank": "Species",
      "tax_id": 9606,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/taxonomy/9606/"
    },
    {
      "common_name": "Neandertal",
      "group": "primates",
      "matched_term": "Homo sapiens neanderthalensis",
      "name": "Homo sapiens neanderthalensis",
      "rank": "Subspecies",
      "tax_id": 63221,
      "url": "https://www.ncbi.nlm.nih.gov/datasets/taxonomy/63221/"
    }
  ],
  "text": "homo"
}
```

### Search virus genomes

List the genome sequences of a virus, such as SARS-CoV-2 or influenza A, filtered by host, where they were collected, Pango lineage, completeness and release date, with each one's isolate, collection date, length and submitter.

**Inputs**

- Virus (`taxon`, text, required): Pick a virus, or type any NCBI Taxonomy ID or name, such as 2697049 or Zika virus.
- Host (`host`, text): Only sequences taken from this host, by Taxonomy ID or name, such as human or Gallus gallus.
- Collected in (`location`, text): Only sequences collected in this country or region, such as USA, Brazil or Africa.
- Pango lineage (`lineage`, text): For SARS-CoV-2, only this Pango lineage, such as XFG.
- Complete genomes only (`complete_only`, true/false): Only sequences the submitter marked complete. Default: `false`.
- RefSeq only (`refseq_only`, true/false): Only NCBI's curated RefSeq reference sequences. Default: `false`.
- Annotated only (`annotated_only`, true/false): Only sequences with gene annotation. Default: `false`.
- Released on or after (`released_after`, date): Only those NCBI released on or after this date.
- Page size (`limit`, number): How many to return, 1 to 1,000. Defaults to 20. From 1 to 1000. Default: `20`.
- Page token (`page_token`, text): The next page token from an earlier step running the same search, to get the page after it. Leave empty for the first page.

**Outputs**

- `count` (number): How many are listed here.
- `genomes` (list): The virus genomes on this page.
- `next_page_token` (text): Pass this as the page token to get the next page. Empty on the last page.
- `taxon` (object): The taxon searched, as NCBI names it.
- `total_count` (number): How many NCBI holds in all for this search.

**Example output**

```json
{
  "count": 1,
  "genomes": [
    {
      "accession": "NC_045512.2",
      "bioprojects": [
        "PRJNA485481"
      ],
      "biosample": "",
      "collection_date": "2019-12",
      "completeness": "Complete",
      "gene_count": 11,
      "host": "Homo sapiens",
      "host_tax_id": 9606,
      "is_annotated": true,
      "isolate": "Wuhan-Hu-1",
      "length": 29903,
      "lineage": "B",
      "location": "China",
      "protein_count": 12,
      "region": "Asia",
      "release_date": "2020-01-13",
      "segment": "",
      "source": "RefSeq",
      "submitter": "National Center for Biotechnology Information, NIH",
      "submitter_country": "USA",
      "update_date": "2020-07-18",
      "url": "https://www.ncbi.nlm.nih.gov/nuccore/NC_045512.2",
      "virus": "Severe acute respiratory syndrome coronavirus 2",
      "virus_tax_id": 2697049
    }
  ],
  "next_page_token": "",
  "taxon": {
    "common_name": "",
    "name": "Severe acute respiratory syndrome coronavirus 2",
    "rank": "",
    "tax_id": 2697049
  },
  "total_count": 1
}
```
