---
title: "Get a filtered taxonomic subtree by taxon"
method: POST
path: "/taxonomy/filtered_subtree"
tags: ["Taxonomy"]
---

# Get a filtered taxonomic subtree by taxon

`POST /taxonomy/filtered_subtree`

Get a filtered taxonomic subtree, including parent and child nodes, in JSON format.

## Request body

- V2TaxonomyFilteredSubtreeRequest
  - `taxons` string[]
  - `specified_limit` boolean
  - `exclude_extinct` boolean
  - `levels` integer
  - `rank_limits` V2reportsRankType[]
  - `include_incertae_sedis` boolean

## Response `200`

A successful response

- V2TaxonomyFilteredSubtreeResponse
  - `root_nodes` integer[]
  - `edges` V2TaxonomyFilteredSubtreeResponseEdgesEntry — A map.
    - `default` V2TaxonomyFilteredSubtreeResponseEdge
      - `visible_children` integer[]
      - `children_status` 'UNSPECIFIED' | 'HAS_MORE_CHILDREN' | 'NO_VISIBLE_CHILDREN' | 'ONLY_UNSPECIFIED_CHILDREN'
      - `rank` 'NO_RANK' | 'SUPERKINGDOM' | 'DOMAIN' | 'REALM' | 'KINGDOM' | 'SUBKINGDOM' | 'SUPERPHYLUM' | 'SUBPHYLUM' | 'PHYLUM' | 'CLADE' | 'SUPERCLASS' | 'CLASS' | 'SUBCLASS' | 'INFRACLASS' | 'COHORT' | 'SUBCOHORT' | 'SUPERORDER' | 'ORDER' | 'SUBORDER' | 'INFRAORDER' | 'PARVORDER' | 'SUPERFAMILY' | 'FAMILY' | 'SUBFAMILY' | 'GENUS' | 'SUBGENUS' | 'SPECIES_GROUP' | 'SPECIES_SUBGROUP' | 'SPECIES' | 'SUBSPECIES' | 'TRIBE' | 'SUBTRIBE' | 'FORMA' | 'VARIETAS' | 'STRAIN' | 'SECTION' | 'SUBSECTION' | 'PATHOGROUP' | 'SUBVARIETY' | 'GENOTYPE' | 'SEROTYPE' | 'ISOLATE' | 'MORPH' | 'SERIES' | 'FORMA_SPECIALIS' | 'SEROGROUP' | 'BIOTYPE' | 'ACELLULAR_ROOT' | 'CELLULAR_ROOT'
      - `scientific_name` string
      - `curator_common_name` string
      - `assembly_count` integer
  - `warnings` V2reportsWarning[]
    - `gene_warning_code` 'UNKNOWN_GENE_WARNING_CODE' | 'ACCESSION_VERSION_MISMATCH' | 'REPLACED_GENE_ID' | 'DISCONTINUED_GENE_ID' | 'UNRECOGNIZED_GENE_ID' | 'UNRECOGNIZED_GENE_SYMBOL' | 'UNRECOGNIZED_ACCESSION' | 'UNRECOGNIZED_TAX_TOKEN' | 'NO_GENE_ANNOTATION_FOUND' | 'ABOVE_SPECIES_TAXON'
    - `reason` string
    - `message` string
    - `replaced_id` V2reportsWarningReplacedId
      - `requested` string
      - `returned` string
    - `unrecognized_identifier` string
  - `errors` V2reportsError[]
    - `assembly_error_code` 'UNKNOWN_ASSEMBLY_ERROR_CODE' | 'INVALID_BIOPROJECT_IDS' | 'NO_ASSEMBLIES_FOR_BIOPROJECTS' | 'INVALID_TAXON' | 'MISSING_SEARCH_FIELD' | 'INVALID_BIOSAMPLE_IDS' | 'NO_ASSEMBLIES_FOR_BIOSAMPLE_IDS' | 'NO_ASSEMBLIES_FOR_ASSEMBLY_NAMES' | 'INVALID_WGS_ACCESSIONS' | 'NO_ASSEMBLIES_FOR_WGS_ACCESSIONS'
    - `gene_error_code` 'UNKNOWN_GENE_ERROR_CODE' | 'INCOMPLETE_LOOKUP_SYMBOL' | 'INVALID_TAXON_GENE_ARGUMENT'
    - `organelle_error_code` 'UNKNOWN_ORGANELLE_ERROR_CODE' | 'INVALID_ORGANELLE_TAXON' | 'NO_ORGANELLES_FOR_ACCESSION'
    - `virus_error_code` 'UNKNOWN_VIRUS_ERROR_CODE'
    - `taxonomy_error_code` 'UNKNOWN_TAXONOMY_ERROR_CODE' | 'INVALID_TAXONOMY_TAXON'
    - `sequence_error_code` 'UNKNOWN_SEQUENCE_ERROR_CODE' | 'INVALID_SEQUENCE_ACCESSION'
    - `reason` string
    - `message` string
    - `invalid_identifiers` string[]

## Other responses

- `default` — An unexpected error response.

---

[API](https://skmtc.dev/ncats/apis/ncbi-datasets-api.md) · [All operations](https://skmtc.dev/ncats/apis/ncbi-datasets-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ncats/ncbi-datasets-api/revisions/c6fcf8559d4a/schema)