GET
/
api
/
v1
/
classifications
/
{id}
/
results
{
  "host_tax_ids": [],
  "n_reads": 2,
  "table": []
}

Return the results of a classification as JSON. The returned JSON has the following top-level structure:

PropertyDescription
n_reads integerThe total number of reads (or FASTA contigs/records) in sample.
host_tax_ids array of stringsAn array of the taxonomy ID for all known hosts in the sample. Filtering out the host_tax_ids and any non-unique mappings (e.g., those to “root” and “cellular organisms”) can be used to produce a table of exclusively microbial taxa.
table objectThe results in a tabular format. Results will typically be sorted by readcount_w_children (descending). See below for more details.

The table object has the results for all taxa in the sample and the following fields:

PropertyDescription
tax_id stringA taxonomy ID. Currently, these are NCBI taxonomy IDs and strictly versioned as part of the job. tax_id should be handled as a string in part to support future compatibility with non-NCBI taxonomies.
name stringThe name of the taxon. This is provided strictly for convenience and names for a given taxa are not guaranteed to remain identical over time. Use tax_id when comparing equality across different taxa.
rank stringThe taxonomic rank. This is also provided for convenience and guaranteed to be consistent for a given job but may change over time as, e.g., previously poorly characterized organisms are better characterized and taxonomically re-labeled.
parent_tax_id stringThe immediate parent of the taxon. Guaranteed to be consistent for all classifications using a given job.
readcount integerThe number of reads (or records or contigs for FASTA files) classified at the given taxon.
readcount_w_children integerThe number of reads classified at the given taxon and all of its children. E.g., if 50 reads map to Enterobacteriaceae in a sample and 50 reads map to E. coli, readcount would be 50 for Enterobacteriaceae and readcount_w_children would be 100.
abundance numberAn estimated relative microbial abundance for the organism. Currently, this will only be provided for classifications using the One Codex database and will only include estimates at the species level (example). Where available, this field should provide substantially improved relative abundance estimates over read-based summaries. See our announcement on relative abundance for more detail on this functionality.
abundance_w_children numberAn estimated, cumulative relative microbial abundance of all of the children of a given taxon. E.g., the abundance_w_children for Escherichia is the sum of the abundances for all species in the Escherichia genus.

Note on future changes: We do likely plan to add additional top-level fields to the returned JSON, e.g., whether the analysis contains abundance estimates or other similar metrics and descriptive features. We do not anticipate removing any top-level fields or fields in the table of results provided.

Path Parameters

​
id
string
required

Response

200 - application/json
Successful operation
​
host_tax_ids
string[]
​
n_reads
integer
Required range: x >= 1
​
table
object[]