Analyze multi-step transition 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

{
    "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

{
    "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

taxonomy_idstring required

Request body

collection_idstring required

Collection to analyze

taxonomy_idstring required

Taxonomy ID

from_stepstring required

Starting step

to_stepstring required

Ending step

max_path_lengthinteger

Maximum number of steps in a path

min_supportinteger

Minimum sequences required to include a path

max_window_daysinteger nullable

Maximum duration for path completion (in days)

filtersobject nullable

Optional event filters

Response

Successful Response

from_stepstring required

to_stepstring required

total_sequencesinteger required

Total sequences that started at from_step

completed_sequencesinteger required

Number of sequences that reached to_step

completion_ratenumber required

Percentage that completed the path

Example response

{
  "paths": [
    {
      "path": [
        "inquiry",
        "followup",
        "closed_won"
      ]
    }
  ]
}

v5