---
title: "Compute step transition analytics"
method: POST
path: "/v1/taxonomies/{taxonomy_id}/analytics/transitions"
tags: ["Taxonomy Analytics"]
---

# Compute step transition analytics

`POST /v1/taxonomies/{taxonomy_id}/analytics/transitions`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/transitions`
- Auth: HTTP bearer and API key in header `X-Namespace`

Analyze how documents progress from one taxonomy step to another.

This endpoint computes conversion rates, duration statistics, and predictor lifts
for documents transitioning between taxonomy labels.

## Use Cases

**Email Thread Analysis:**
- Question: How long from "inquiry" to "closed_won"?
- Question: What % of inquiries result in sales?
- Question: Which sender domains have highest conversion?

**Content Workflow Tracking:**
- Question: Conversion rate from "draft" to "published"?
- Question: How long does content stay in review?
- Question: Which authors publish fastest?

**Safety Compliance Monitoring:**
- Question: Time from violation detection to resolution?
- Question: Success rate for remediation efforts?

## Requirements

- Taxonomy must have `step_analytics` configured (or provide `override_step_analytics`)
- Collection must contain documents enriched with this taxonomy
- Documents must have timestamp and sequence grouping fields configured

## Returns

**Conversion Metrics:**
- `count`: Total sequences starting at from_step
- `converted`: Number reaching to_step
- `conversion_rate`: Percentage that converted

**Duration Statistics (if converted > 0):**
- `mean`, `median`: Average and middle duration
- `p90`, `p95`: 90th and 95th percentile durations
- `std_dev`, `min`, `max`: Distribution statistics

**Top Predictors:**
- Covariates with highest impact on conversion
- Lift values (>1.0 = increases conversion, <1.0 = decreases)
- Statistical significance via minimum support threshold

## Example Request

```json
{
    "collection_id": "col_emails",
    "taxonomy_id": "tax_sales_stages",
    "from_step": "inquiry",
    "to_step": "closed_won",
    "max_window_days": 90,
    "min_support": 10
}
```

## Example Response

```json
{
    "from_step": "inquiry",
    "to_step": "closed_won",
    "count": 1000,
    "converted": 350,
    "conversion_rate": 0.35,
    "durations_sec": {
        "mean": 432000.0,
        "median": 345600.0,
        "p50": 345600.0,
        "p90": 691200.0,
        "p95": 864000.0
    },
    "top_predictors": [
        {
            "field": "Sender Domain",
            "value": "enterprise.com",
            "count": 150,
            "conversion_rate": 0.75,
            "lift": 2.14
        }
    ]
}
```

## Path parameters

- `taxonomy_id` string, required

## Request body

- StepTransitionRequest: API request model for step transition analytics. This model extends the engine query model with API-specific validation and documentation. Use this to analyze how documents transition from one taxonomy step to another, computing conversion rates, durations, and predictor lifts. Example: ```json { "collection_id": "col_emails", "taxonomy_id": "tax_sales_stages", "from_step": "inquiry", "to_step": "closed_won", "max_window_days": 90, "min_support": 10 } ``` Response includes: - Conversion rate (% reaching to_step) - Duration statistics (mean, median, p90, p95) - Top predictors (covariates with highest lift)
  - `collection_id` string, required: Collection to analyze for step transitions
  - `taxonomy_id` string, required: Taxonomy ID (each taxonomy_id is immutable, clone creates new ID)
  - `from_step` string, required: Starting step label (e.g., 'inquiry', 'draft')
  - `to_step` string, required: Ending step label (e.g., 'closed_won', 'published')
  - `max_window_days` integer, nullable: Maximum days between from_step and to_step. Sequences exceeding this are excluded.
  - `filters` object, nullable: Optional filters for events (e.g., {'metadata.region': 'US'})
  - `override_step_analytics` StepAnalyticsConfigInput: 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.
  - `min_support` integer: Minimum number of sequences required for valid analysis

## Response `200`

Successful Response

- StepTransitionResponse: API response model for step transition analytics. Contains comprehensive statistics about the A→B transition including conversion metrics, duration analysis, and predictor insights. Example Response: ```json { "from_step": "inquiry", "to_step": "closed_won", "count": 1000, "converted": 350, "conversion_rate": 0.35, "durations_sec": { "mean": 432000.0, "median": 345600.0, "p50": 345600.0, "p90": 691200.0, "p95": 864000.0, "std_dev": 172800.0, "min": 86400.0, "max": 1209600.0 }, "top_predictors": [ { "field": "Sender Domain", "value": "enterprise.com", "count": 150, "conversion_rate": 0.75, "lift": 2.14 } ], "metadata": { "collection_id": "col_emails", "taxonomy_id": "tax_sales_stages", "total_events_analyzed": 5432 } } ```
  - `from_step` string, required: Starting step
  - `to_step` string, required: Ending step
  - `count` integer, required: Total number of sequences starting at from_step
  - `converted` integer, required: Number of sequences that reached to_step
  - `conversion_rate` number, required: Percentage that converted (converted / count)
  - `durations_sec` DurationStats: Statistical distribution of durations for successful step transitions. Provides comprehensive percentile analysis to understand timing patterns. Attributes: mean: Average duration (seconds) median: Middle value (50th percentile) p50: 50th percentile (same as median, included for consistency) p90: 90th percentile (90% complete faster) p95: 95th percentile (95% complete faster) std_dev: Standard deviation (measure of spread) min: Fastest observed duration max: Slowest observed duration Example: ```python DurationStats( mean=432000.0, # 5 days average median=345600.0, # 4 days median p50=345600.0, p90=691200.0, # 8 days (90th percentile) p95=864000.0, # 10 days (95th percentile) std_dev=172800.0, # 2 days std dev min=86400.0, # 1 day minimum max=1209600.0 # 14 days maximum ) ```
    - `mean` number, required: Average duration in seconds
    - `median` number, required: Median duration in seconds
    - `p50` number, required: 50th percentile (same as median)
    - `p90` number, required: 90th percentile duration in seconds
    - `p95` number, required: 95th percentile duration in seconds
    - `std_dev` number, required: Standard deviation in seconds
    - `min` number, required: Minimum duration observed in seconds
    - `max` number, required: Maximum duration observed in seconds
  - `top_predictors` PredictorLift[]: Covariates with highest lift (sorted by absolute lift)
    - `field` string, required: Covariate field name
    - `value` string, required: Specific value or bin label
    - `count` integer, required: Number of sequences with this value
    - `conversion_rate` number, required: Conversion rate for this value
    - `lift` number, required: Lift relative to baseline (>1.0 = positive, <1.0 = negative)
  - `metadata` object: Additional metadata (collection_id, event counts, etc.)

## 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-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-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/taxonomies/:taxonomy_id/analytics/transitions/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)