---
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`

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` — 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/04b379bdbb7c/schema)