---
title: "List Taxonomies"
method: POST
path: "/v1/taxonomies/list"
tags: ["Taxonomies"]
---

# List Taxonomies

`POST /v1/taxonomies/list`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/taxonomies/list`
- Auth: HTTP bearer and API key in header `X-Namespace`

List taxonomies with optional filters and pagination.

## Query parameters

- `limit` integer, nullable
- `page_size` integer, nullable
- `offset` integer, nullable
- `page` integer, nullable
- `cursor` string, nullable
- `next_cursor` string, nullable
- `after` string, nullable
- `include_total` boolean

## Request body

- ListTaxonomiesRequest: Request model to list taxonomies. Inherits body-level limit/page_size/offset/page — body values win over query pagination via merge_body_pagination.
  - `limit` integer, nullable: Page size. A body value wins over the `limit` query param.
  - `page_size` integer, nullable: Alias for `limit` (page size). If both are given, `limit` wins.
  - `offset` integer, nullable: Number of results to skip (legacy, use cursor instead). A body value wins over the `offset` query param.
  - `page` integer, nullable: 1-indexed page number. Folds to offset = (page-1) * limit. If both `page` and `offset` are given, `offset` wins.
  - `search` string, nullable: Search term for wildcard search across taxonomy_id, taxonomy_name, description, and other text fields
  - `filters` LogicalOperatorInput: Represents a logical operation (AND, OR, NOT) on filter conditions. Allows nesting with a defined depth limit. Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).
    - `AND` union[], nullable: Logical AND operation - all conditions must be true
      - union
        - LogicalOperatorInput (recursive)
        - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required: Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem.
          - `value` union, required: Value to compare against
            - DynamicValue: A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `OR` union[], nullable: Logical OR operation - at least one condition must be true
      - union
        - LogicalOperatorInput (recursive)
        - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required: Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem.
          - `value` union, required: Value to compare against
            - DynamicValue: A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `NOT` union[], nullable: Logical NOT operation - all conditions must be false
      - union
        - LogicalOperatorInput (recursive)
        - FilterCondition: Represents a single filter condition. Attributes: field: The field to filter on operator: The comparison operator value: The value to compare against
          - `field` string, required: Field name to filter on
          - `operator` 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains' | 'starts_with' | 'ends_with' | 'regex' | 'exists' | 'is_null' | 'text' | 'phrase' | 'words' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon': Supported filter operators across database implementations. `text` is a case-insensitive substring match on the MVS vector store, in the in-memory evaluator and in the collections list filter; it does not tokenize or rank. On the Mongo query translator it becomes a Mongo `$text` search, which needs a collection text index and searches every indexed field. For whole-word matching on one field use `words`: every word of the value must appear as a whole word, compared on its English stem.
          - `value` union, required: Value to compare against
            - DynamicValue: A value that should be dynamically resolved from the query request.
              - …
            - unknown
    - `case_sensitive` boolean, nullable: Whether to perform case-sensitive matching
  - `sort` SortOption: Specifies how to sort query results. Attributes: field: Field to sort by direction: Sort direction (ascending or descending)
    - `field` string, required: Field to sort by, supports dot notation for nested fields
    - `direction` 'asc' | 'desc': Sort direction options.
  - `sorts` object[], nullable: Sort configuration as a list of {field, direction} — the shape Studio datatables and the retriever list send. The first entry is the primary sort. Takes precedence over the singular `sort`.
  - `case_sensitive` boolean: If True, filters and search will be case-sensitive

## Response `200`

Successful Response

- ListTaxonomiesResponse: Response model for listing taxonomies.
  - `results` TaxonomyResponse[], required
    - `taxonomy_id` string: Unique identifier for the taxonomy
    - `version` integer: Monotonic version number of the taxonomy configuration
    - `taxonomy_name` string, required: A unique name for the taxonomy within the namespace.
    - `description` string, nullable: Optional human-readable description.
    - `retriever_id` string, nullable: Optional taxonomy-level retriever (prefer per-layer).
    - `input_mappings` InputMapping[], nullable: Optional taxonomy-level inputs (prefer per-layer).
      - `input_key` string, required: Key used in the constructed inputs payload.
      - `source_type` 'payload' | 'literal' | 'vector' | 'blob': Where the value for an input should be retrieved from.
      - `path` string, nullable: Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
      - `override` unknown
    - `config` union, required: Configuration specific to the taxonomy type.
      - FlatTaxonomyConfigOutput: Configuration for a *flat* taxonomy - single source collection with one retriever.
        - `taxonomy_type` 'flat': Discriminator identifying this as a flat taxonomy.
        - `retriever_id` string, required: The retriever to use for matching against the source collection.
        - `input_mappings` InputMapping[], required: Input mappings defining how to construct retriever inputs.
          - `input_key` string, required: Key used in the constructed inputs payload.
          - `source_type` 'payload' | 'literal' | 'vector' | 'blob': Where the value for an input should be retrieved from.
          - `path` string, nullable: Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
          - `override` unknown
        - `source_collection` SourceCollectionOutput, required: A source collection for a flat taxonomy.
          - `collection_id` string, required: The ID of the source collection for the taxonomy.
          - `enrichment_fields` EnrichmentField[], nullable: Fields to copy from matched taxonomy node when enriching (append/replace semantics). If omitted, the full payload is copied.
            - `field_path` string, required: Dot-notation path of the field to copy from the taxonomy node.
            - `target_field` string, nullable: Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style).
            - `merge_mode` 'replace' | 'append': How a field from the taxonomy node should be merged into the target doc.
        - `top_k` integer: Maximum nodes a materialized run assigns to each document, best first, as the taxonomy_enrich stage's top_k does on demand. The best match fills the _internal._taxonomy_<id>_id, _label and _score fields. Above 1, every kept match is also listed, ranked, in _internal._taxonomy_<id>_assignments, and append-mode enrichment fields collect their values from every kept match. Default 1: one node per document.
        - `step_analytics` StepAnalyticsConfigOutput: Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ```
          - `timestamp_field` string, required: Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')
          - `sequence_id_field` string, required: Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')
          - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path': Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage")
          - `step_key_field_path` string, nullable: Required if step_key_source='field_path'. Dot-notation path to step value in document.
          - `covariates` CovariateConfig[]: Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)
            - `field_path` string, required: Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')
            - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required: Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ```
            - `name` string, required: Human-readable name for this covariate in analytics results
            - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable: How to bin numeric values for lift analysis (only used for NUMERIC type)
            - `clustering_method` 'kmeans' | 'hdbscan', nullable: Clustering algorithm for embedding analysis (only used for EMBEDDING type)
            - `n_clusters` integer, nullable: Number of clusters for embedding-based predictors (only used for EMBEDDING type)
          - `max_sequence_duration_days` integer, nullable: Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.
      - HierarchicalTaxonomyConfigOutput: Hybrid hierarchical taxonomy configuration supporting inference with manual additions. All hierarchical taxonomies are hybrid: - Base hierarchy can be inferred via schema, clustering, or LLM - Additional collections can be explicitly added with specific retrievers - Supports mixing inference strategies with manual additions/overrides Examples: 1. Pure inference: Set inference_strategy + inference_collections 2. Pure manual: Set hierarchical_nodes only 3. Hybrid: Set inference_strategy + inference_collections + hierarchical_nodes (infers base from collections, adds/overrides with explicit nodes)
        - `taxonomy_type` 'hierarchical': Discriminator identifying this as a hierarchical taxonomy.
        - `retriever_id` string, nullable: Default retriever to use for all nodes unless overridden per-node.
        - `input_mappings` InputMapping[], nullable: Default input mappings for all nodes unless overridden per-node.
          - `input_key` string, required: Key used in the constructed inputs payload.
          - `source_type` 'payload' | 'literal' | 'vector' | 'blob': Where the value for an input should be retrieved from.
          - `path` string, nullable: Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
          - `override` unknown
        - `inference_strategy` 'schema' | 'cluster' | 'llm': Strategy for inferring the base hierarchy structure. Can be combined with manual overrides via hierarchical_nodes for hybrid configuration: - SCHEMA: Infer based on overlapping collection schemas - CLUSTER: Infer based on clustering algorithms and overlap detection - LLM: Infer using AI/language models
        - `inference_collections` string[], nullable: Collection IDs to use for hierarchy inference. The inference_strategy will analyze these collections to discover relationships. Can be combined with hierarchical_nodes for hybrid configuration.
        - `llm_provider` 'openai_chat_v1', nullable: LLM provider to use for hierarchy inference (default openai_chat_v1)
        - `llm_model` string, nullable: LLM model name (e.g., gpt-4o-mini)
        - `llm_prompt_template` string, nullable: Optional prompt template. Variables available: {collection_id}, {collection_name}.
        - `llm_sample_size` integer: Optional number of sample docs to include in prompts (0 = disabled).
        - `cluster_ids` string[], nullable: Cluster IDs to use for CLUSTER inference strategy
        - `cluster_overlap_threshold` number: Minimum overlap ratio to establish parent-child relationship between clusters
        - `hierarchical_nodes` HierarchicalNodeOutput[], nullable: Explicit node definitions that either: 1) Define the entire hierarchy (when inference_strategy is None), 2) Add additional nodes to an inferred hierarchy, or 3) Override specific relationships in an inferred hierarchy. Supports true hybrid: infer from some collections, manually add others.
          - `collection_id` string, required: REQUIRED. Collection ID representing this node in the hierarchy. Must reference an existing collection containing documents for this hierarchy level. Format: 'col_' prefix followed by alphanumeric/underscore characters. Used to: Match documents against this level, identify node in path, store enrichment data. Example: 'col_executives' for executive level, 'col_products_phones' for phones category.
          - `parent_collection_id` string, nullable: OPTIONAL. Collection ID of the parent node in the hierarchy. When None: This is a root node (top of hierarchy). When set: References parent node's collection_id, creating parent-child relationship. Format: Same as collection_id ('col_' prefix). Used to: Build hierarchy tree, determine inheritance order, construct path arrays. Example: 'col_managers' is parent of 'col_executives', 'col_products' is parent of 'col_electronics'. Validation: Must reference a valid collection_id from another node in same taxonomy.
          - `label` string, nullable: OPTIONAL. Human-readable display name for this hierarchy node. Used in UI, visualizations, and taxonomy assignment results. NOT REQUIRED - When None: collection name or auto-generated label may be used. Format: Free text, typically title case, 2-50 characters. Examples: 'Executive Leadership', 'Mobile Phones', 'Engineering Team'. Can be LLM-generated or manually specified during taxonomy creation.
          - `summary` string, nullable: OPTIONAL. Brief description of this hierarchy level and its contents. Used for: Documentation, UI tooltips, understanding hierarchy structure. NOT REQUIRED - When None: no summary available for this node. Format: Free text, typically 1-3 sentences, up to 500 characters. Can be LLM-generated or manually provided.
          - `keywords` string[], nullable: OPTIONAL. Keywords or tags describing this hierarchy level. Used for: Search, filtering, categorization, LLM understanding. NOT REQUIRED - When None: no keywords defined for this node. Format: List of strings, typically 3-10 keywords per node. Can be LLM-generated from collection contents or manually specified.
          - `retriever_id` string, nullable: OPTIONAL. Retriever to use for matching documents at this hierarchy level. When None: Uses taxonomy-level retriever_id (inheritance from parent config). When set: Overrides taxonomy-level retriever for this specific node. Format: 'ret_' prefix followed by alphanumeric characters. Use for: Specialized matching at certain levels (e.g., face recognition for employees, semantic search for products). Must reference an existing RetrieverModel.
          - `enrichment_fields` EnrichmentField[], nullable: OPTIONAL. Fields to enrich into documents when they match this hierarchy level. Specifies which properties from node collection to copy to matched documents. When None: No field-level enrichment (only taxonomy assignment recorded). Format: List of EnrichmentField objects with field_path and merge_mode. Inheritance: Child nodes inherit all parent enrichment_fields plus their own. Example: executives node adds 'executive_level' on top of inherited 'employee_id', 'department'.
            - `field_path` string, required: Dot-notation path of the field to copy from the taxonomy node.
            - `target_field` string, nullable: Optional target field name in the enriched document. If specified, the source field will be renamed to this name. If not specified, the field_path is used as the target name. Use this to rename fields during enrichment (e.g., label → visual_style).
            - `merge_mode` 'replace' | 'append': How a field from the taxonomy node should be merged into the target doc.
          - `input_mappings` InputMapping[], nullable: OPTIONAL. Custom input mappings for the retriever at this hierarchy level. Specifies how to construct retriever inputs from document features. When None: Uses taxonomy-level input_mappings (inheritance). When set: Overrides taxonomy-level mappings for this specific node. Format: List of InputMapping objects specifying input_key, source_type, path. Use for: Different matching strategies at different levels (e.g., face at employee level, text at department level).
            - `input_key` string, required: Key used in the constructed inputs payload.
            - `source_type` 'payload' | 'literal' | 'vector' | 'blob': Where the value for an input should be retrieved from.
            - `path` string, nullable: Dot-notation path when source_type is PAYLOAD or VECTOR. PAYLOAD paths resolve from the document's ROOT fields — each document/source_document dict IS the payload (e.g. path 'text' reads {'text': ...}); a {'payload': {...}} envelope is also accepted as a fallback.
            - `override` unknown
        - `step_analytics` StepAnalyticsConfigOutput: Configuration for step-by-step transition analytics on taxonomy assignments. Enables analysis of how documents progress through taxonomy labels as a temporal sequence, answering questions like: - How long from "inquiry" to "closed_won"? - What % of "inquiry" emails reach "proposal"? - Which sender domains correlate with faster progression? Use Cases: 1. Email Thread Analysis: - Track progression: inquiry → followup → proposal → closed_won - Identify which subject lines correlate with faster closure 2. Content Workflow Tracking: - Monitor: draft → review → approved → published - Find bottlenecks and optimization opportunities 3. Safety Compliance Monitoring: - Trace: violation_detected → investigated → resolved - Track resolution times and success rates Attributes: timestamp_field: Document field containing event timestamp sequence_id_field: Field that groups related documents into sequences step_key_source: How to extract the step identifier (label/node_id/custom field) step_key_field_path: Required if step_key_source='field_path' covariates: List of predictor variables to analyze for conversion lift max_sequence_duration_days: Filter out sequences longer than this (data quality) Example: ```python # Email thread analysis configuration StepAnalyticsConfig( timestamp_field="Date", # Email timestamp sequence_id_field="Thread-Index", # Groups emails in same thread step_key_source="assignment_label", # Use taxonomy label as step covariates=[ CovariateConfig( field_path="sender_domain", covariate_type="categorical", name="Sender Domain" ), CovariateConfig( field_path="word_count", covariate_type="numeric", name="Email Length" ) ], max_sequence_duration_days=90 # Ignore threads >90 days ) ```
          - `timestamp_field` string, required: Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')
          - `sequence_id_field` string, required: Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')
          - `step_key_source` 'assignment_label' | 'assignment_node_id' | 'field_path': Defines how to extract the step key from documents for sequence analysis. The step key identifies which stage/state a document is in for transition analytics. Examples: ASSIGNMENT_LABEL: Use the taxonomy's assigned label (e.g., "inquiry", "proposal") ASSIGNMENT_NODE_ID: Use the taxonomy node ID (e.g., "node_sales_inquiry") FIELD_PATH: Use a custom document field (e.g., "metadata.workflow_stage")
          - `step_key_field_path` string, nullable: Required if step_key_source='field_path'. Dot-notation path to step value in document.
          - `covariates` CovariateConfig[]: Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)
            - `field_path` string, required: Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')
            - `covariate_type` 'categorical' | 'numeric' | 'embedding' | 'cluster_id', required: Type of covariate/predictor variable for conversion analysis. Different types enable different analysis strategies: - CATEGORICAL: String values, analyzed via grouping (e.g., sender_domain, priority) - NUMERIC: Continuous values, binned into quartiles/deciles (e.g., word_count, price) - EMBEDDING: Dense vectors, clustered for semantic analysis (e.g., CLIP embeddings) - CLUSTER_ID: Pre-computed cluster identifiers (e.g., topic_cluster, visual_cluster) Examples: ```python # Categorical: Which email domains convert better? CovariateConfig(field_path="sender_domain", covariate_type="categorical") # Numeric: Do longer emails convert faster? CovariateConfig(field_path="word_count", covariate_type="numeric") # Embedding: Do visually similar images follow similar paths? CovariateConfig(field_path="features.clip", covariate_type="embedding") # Cluster: Which topic clusters have highest conversion? CovariateConfig(field_path="metadata.topic_id", covariate_type="cluster_id") ```
            - `name` string, required: Human-readable name for this covariate in analytics results
            - `binning_strategy` 'quartiles' | 'deciles' | 'custom', nullable: How to bin numeric values for lift analysis (only used for NUMERIC type)
            - `clustering_method` 'kmeans' | 'hdbscan', nullable: Clustering algorithm for embedding analysis (only used for EMBEDDING type)
            - `n_clusters` integer, nullable: Number of clusters for embedding-based predictors (only used for EMBEDDING type)
          - `max_sequence_duration_days` integer, nullable: Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.
        - `path_field` string, nullable: Build the hierarchy from a field each document already carries, instead of from node collections or inference. The field holds the document's path: a delimited string ('footage/2024/q3', split on path_separator) or a list of ancestor ids, root first (['col_a', 'col_b']). One node exists per distinct prefix, with its parent; a document is assigned the deepest node its path names and inherits the nodes above it. Dot paths reach nested fields ('metadata.folder'). Not combined with hierarchical_nodes or inference_strategy.
        - `path_separator` string: Separator for a string path_field. Ignored for list values.
    - `nodes` TaxonomyPathNode[], nullable: For a hierarchy built from config.path_field: one node per distinct path prefix seen in enriched documents, with its parent. Grows as enrichment meets new paths. None for other taxonomies.
      - `node_id` string, required: Stable id derived from the path.
      - `label` string, required: The prefix's last segment.
      - `path` string[], required: The segments from the root to here.
      - `parent_id` string, nullable: node_id of the parent prefix; None at the root.
      - `level` integer, required: Depth; 0 at the root.
    - `ready` boolean: Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.
    - `created_at` string, date-time: Creation timestamp for this taxonomy record
    - `metadata` object: Additional user-defined metadata for the taxonomy
  - `pagination` object, required
  - `total_count` integer, required
  - `stats` TaxonomyListStats: Aggregate statistics for a list of taxonomies.
    - `total_taxonomies` integer: Total number of taxonomies in the result
    - `flat_taxonomies` integer: Number of flat taxonomies
    - `hierarchical_taxonomies` integer: Number of hierarchical taxonomies
    - `taxonomies_with_retrievers` integer: Number of taxonomies with retriever configured

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-18** `62302d591b8e`: 1 info
  - added the optional property `results/items/config/oneOf[subschema #1: FlatTaxonomyConfig]/top_k` to the response with the `200` status
- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-10-04** `38e0822db900`: 3 info
  - added the optional property `results/items/config/oneOf[subschema #2: HierarchicalTaxonomyConfig]/path_field` to the response with the `200` status
  - added the optional property `results/items/config/oneOf[subschema #2: HierarchicalTaxonomyConfig]/path_separator` to the response with the `200` status
  - added the optional property `results/items/nodes` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/taxonomies/list/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)