> ## Documentation Index > Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```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 ## OpenAPI ````yaml post /v1/taxonomies/{taxonomy_id}/analytics/paths openapi: 3.1.0 info: title: Mixpeek API description: >- This is the Mixpeek API, providing access to various endpoints for data processing and retrieval. termsOfService: https://mixpeek.com/terms contact: name: Mixpeek Support url: https://mixpeek.com/contact email: info@mixpeek.com version: '0.82' servers: - url: https://api.mixpeek.com description: Production security: [] paths: /v1/taxonomies/{taxonomy_id}/analytics/paths: post: tags: - Taxonomy Analytics summary: Analyze multi-step transition paths description: >- 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 operationId: >- analyze_transition_paths_v1_taxonomies__taxonomy_id__analytics_paths_post parameters: - name: taxonomy_id in: path required: true schema: type: string title: Taxonomy Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PathAnalysisRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PathAnalysisResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PathAnalysisRequest: properties: collection_id: type: string title: Collection Id description: Collection to analyze taxonomy_id: type: string title: Taxonomy Id description: Taxonomy ID from_step: type: string title: From Step description: Starting step to_step: type: string title: To Step description: Ending step max_path_length: type: integer maximum: 20 minimum: 2 title: Max Path Length description: Maximum number of steps in a path default: 10 min_support: type: integer minimum: 1 title: Min Support description: Minimum sequences required to include a path default: 5 max_window_days: anyOf: - type: integer - type: 'null' title: Max Window Days description: Maximum duration for path completion (in days) filters: anyOf: - additionalProperties: true type: object - type: 'null' title: Filters description: Optional event filters type: object required: - collection_id - taxonomy_id - from_step - to_step title: PathAnalysisRequest description: >- 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 PathAnalysisResponse: properties: from_step: type: string title: From Step to_step: type: string title: To Step total_sequences: type: integer title: Total Sequences description: Total sequences that started at from_step completed_sequences: type: integer title: Completed Sequences description: Number of sequences that reached to_step completion_rate: type: number maximum: 1 minimum: 0 title: Completion Rate description: Percentage that completed the path paths: items: $ref: '#/components/schemas/TransitionPath' type: array maxItems: 100 title: Paths description: List of paths sorted by frequency (most common first) type: object required: - from_step - to_step - total_sequences - completed_sequences - completion_rate - paths title: PathAnalysisResponse description: >- 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 } ] } ``` ErrorResponse: properties: success: type: boolean title: Success description: Always false for error responses default: false status: type: integer title: Status description: HTTP status code for this error error: $ref: '#/components/schemas/ErrorDetail' description: Error details payload type: object required: - status - error title: ErrorResponse description: Error response model. examples: - error: details: id: ns_123 resource: namespace message: Namespace not found type: NotFoundError status: 404 success: false HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TransitionPath: properties: path: items: type: string type: array minItems: 2 title: Path description: Ordered sequence of steps examples: - - inquiry - followup - closed_won - - draft - review - published count: type: integer minimum: 0 title: Count description: Number of sequences following this path percentage: type: number maximum: 100 minimum: 0 title: Percentage description: Percentage of total completing sequences avg_duration_sec: anyOf: - type: number - type: 'null' title: Avg Duration Sec description: Average time to complete this path (seconds) type: object required: - path - count - percentage title: TransitionPath description: |- Represents a multi-step path between two steps. Tracks the intermediate steps documents take when transitioning from from_step to to_step. Attributes: path: Ordered sequence of steps (e.g., ["inquiry", "followup", "proposal", "closed_won"]) count: Number of sequences that followed this exact path percentage: Percentage of all completing sequences that used this path avg_duration_sec: Average time to complete this path Example: ```python # 30% of successful conversions took this 4-step path TransitionPath( path=["inquiry", "followup", "proposal", "closed_won"], count=120, percentage=34.3, avg_duration_sec=604800.0 # 7 days average ) ``` ErrorDetail: properties: message: type: string title: Message description: Human-readable error message type: type: string title: Type description: Stable error type identifier (machine-readable) code: anyOf: - type: string - type: 'null' title: Code description: >- Fine-grained error code for programmatic handling (e.g., namespace_name_taken, feature_extractor_not_found). Present only when consumers may need to branch on a specific error condition. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: >- Optional structured details to help debugging (validation errors, IDs, etc.) type: object required: - message - type title: ErrorDetail description: Error detail model. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ````