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

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` — 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/220a3b263fda/schema)