--- title: "List taxonomies (GET alias for POST /list)." method: GET path: "/v1/taxonomies" tags: ["Taxonomies"] --- # List taxonomies (GET alias for POST /list). `GET /v1/taxonomies` 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 (BACKE-2846) — 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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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' | 'geo_radius' | 'geo_bounding_box' | 'geo_polygon' — Supported filter operators across database implementations. - `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. - `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. - `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` — Validation Error - `500` — Internal Server Error --- [API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/1c7f31821424/schema)