--- title: "Analyze multi-step transition paths" method: POST path: "/v1/taxonomies/{taxonomy_id}/analytics/paths" tags: ["Taxonomy Analytics"] --- # Analyze multi-step transition paths `POST /v1/taxonomies/{taxonomy_id}/analytics/paths` ## Request - Base URL: `https://api.mixpeek.com` - URL: `https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/paths` - Auth: HTTP bearer and API key in header `X-Namespace` Discover the most common multi-step paths documents take between two taxonomy steps. Unlike the `/transitions` endpoint which only analyzes direct A→B transitions, this endpoint reveals the intermediate steps documents actually take. ## Use Cases **Email Thread Analysis:** - Question: What paths do emails take from "inquiry" to "closed_won"? - Discover: Some go inquiry → followup → proposal → closed_won - Discover: Others skip steps: inquiry → proposal → closed_won - Discover: Fast track: inquiry → closed_won **Content Editorial Paths:** - Question: Common paths from "draft" to "published"? - Discover: draft → review → edit → review → published - Discover: draft → review → published (expedited) - Discover: Paths that loop back (draft → review → draft → review) **Compliance Resolution Paths:** - Question: How do violations get resolved? - Discover: violation → investigated → remediated → resolved - Discover: violation → false_positive → closed - Discover: Escalation paths: violation → escalated → legal_review → resolved ## Requirements - Taxonomy must have `step_analytics` configured - Collection must contain documents with timestamp and sequence_id fields ## Returns **Completion Metrics:** - `total_sequences`: Sequences starting at from_step - `completed_sequences`: Number reaching to_step - `completion_rate`: Percentage that completed **Paths (sorted by frequency):** - `path`: Ordered sequence of steps - `count`: Number of sequences following this path - `percentage`: Percentage of completing sequences - `avg_duration_sec`: Average time for this path ## Example Request ```json { "collection_id": "col_emails", "taxonomy_id": "tax_sales_stages", "from_step": "inquiry", "to_step": "closed_won", "max_path_length": 10, "min_support": 5 } ``` ## Example Response ```json { "from_step": "inquiry", "to_step": "closed_won", "total_sequences": 1000, "completed_sequences": 350, "completion_rate": 0.35, "paths": [ { "path": ["inquiry", "followup", "proposal", "closed_won"], "count": 120, "percentage": 34.3, "avg_duration_sec": 604800.0 }, { "path": ["inquiry", "proposal", "closed_won"], "count": 90, "percentage": 25.7, "avg_duration_sec": 432000.0 }, { "path": ["inquiry", "closed_won"], "count": 70, "percentage": 20.0, "avg_duration_sec": 172800.0 } ] } ``` ## Path Interpretation **Length Analysis:** - Shorter paths indicate efficient progression - Longer paths may indicate complexity or bottlenecks - Loops (repeated steps) indicate rework or revisions **Duration Analysis:** - Compare avg_duration_sec across paths - Shorter paths may not always be faster - Identify optimization opportunities **Frequency Analysis:** - High-percentage paths are "happy paths" - Low-percentage paths may be edge cases or exceptions - Missing expected paths indicate drop-off points ## Path parameters - `taxonomy_id` string, required ## Request body - PathAnalysisRequest: API request model for multi-step path analysis. Discovers the most common sequences of intermediate steps documents take when progressing from from_step to to_step. Unlike the transitions endpoint which only analyzes direct A→B progressions, this endpoint reveals the actual paths taken (e.g., A → X → Y → B). Example: ```json { "collection_id": "col_emails", "taxonomy_id": "tax_sales_stages", "from_step": "inquiry", "to_step": "closed_won", "max_path_length": 10, "min_support": 5 } ``` Response includes: - Most common paths sorted by frequency - Count and percentage for each path - Average duration per path - `collection_id` string, required: Collection to analyze - `taxonomy_id` string, required: Taxonomy ID - `from_step` string, required: Starting step - `to_step` string, required: Ending step - `max_path_length` integer: Maximum number of steps in a path - `min_support` integer: Minimum sequences required to include a path - `max_window_days` integer, nullable: Maximum duration for path completion (in days) - `filters` object, nullable: Optional event filters ## Response `200` Successful Response - PathAnalysisResponse: API response model for multi-step path analysis. Contains discovered transition paths with frequency and duration statistics. Example Response: ```json { "from_step": "inquiry", "to_step": "closed_won", "total_sequences": 1000, "completed_sequences": 350, "completion_rate": 0.35, "paths": [ { "path": ["inquiry", "followup", "proposal", "closed_won"], "count": 120, "percentage": 34.3, "avg_duration_sec": 604800.0 }, { "path": ["inquiry", "proposal", "closed_won"], "count": 90, "percentage": 25.7, "avg_duration_sec": 432000.0 }, { "path": ["inquiry", "closed_won"], "count": 70, "percentage": 20.0, "avg_duration_sec": 172800.0 } ] } ``` - `from_step` string, required - `to_step` string, required - `total_sequences` integer, required: Total sequences that started at from_step - `completed_sequences` integer, required: Number of sequences that reached to_step - `completion_rate` number, required: Percentage that completed the path - `paths` TransitionPath[], required: List of paths sorted by frequency (most common first) - `path` string[], required: Ordered sequence of steps - `count` integer, required: Number of sequences following this path - `percentage` number, required: Percentage of total completing sequences - `avg_duration_sec` number, nullable: Average time to complete this path (seconds) ## 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/paths/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)