Compute step transition analytics

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

POST /v1/taxonomies/{taxonomy_id}/analytics/transitions

Compute step transition analytics

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/transitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "collection_id": "<string>",
  "taxonomy_id": "<string>",
  "from_step": "inquiry",
  "to_step": "closed_won",
  "max_window_days": 183,
  "filters": {},
  "override_step_analytics": {
    "timestamp_field": "Date",
    "sequence_id_field": "Thread-Index",
    "step_key_source": "assignment_label",
    "step_key_field_path": "metadata.workflow_stage",
    "covariates": [
      {
        "field_path": "sender_domain",
        "name": "Sender Domain",
        "binning_strategy": "quartiles",
        "clustering_method": "kmeans",
        "n_clusters": 10
      }
    ],
    "max_sequence_duration_days": 183
  },
  "min_support": 10
}
'

200

{
  "from_step": "<string>",
  "to_step": "<string>",
  "count": 1,
  "converted": 1,
  "conversion_rate": 0.5,
  "durations_sec": {
    "mean": 123,
    "median": 123,
    "p50": 123,
    "p90": 123,
    "p95": 123,
    "std_dev": 123,
    "min": 123,
    "max": 123
  },
  "top_predictors": [
    {
      "field": "<string>",
      "value": "<string>",
      "count": 1,
      "conversion_rate": 0.5,
      "lift": 123
    }
  ],
  "metadata": {}
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

taxonomy_id · string · required

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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')

Examples:

"inquiry"

"draft"

"violation_detected"

to_step · string · required

Ending step label (e.g., 'closed_won', 'published')

Examples:

"closed_won"

"published"

"resolved"

max_window_days · integer | null

Maximum days between from_step and to_step. Sequences exceeding this are excluded.

Required range: 1 <= x <= 365

filters · Filters · object | null

Optional filters for events (e.g., {'metadata.region': 'US'})

override_step_analytics · StepAnalyticsConfig · object | null

Override taxonomy's default step_analytics config for this query

Show child attributes

min_support · integer · default: 10

Minimum number of sequences required for valid analysis

Required range: x >= 1

Response

200

application/json

Successful Response

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

Required range: x >= 0

converted · integer · required

Number of sequences that reached to_step

Required range: x >= 0

conversion_rate · number · required

Percentage that converted (converted / count)

Required range: 0 <= x <= 1

durations_sec · DurationStats · object | null

Duration statistics (None if no conversions)

Show child attributes

top_predictors · PredictorLift · object[]

Covariates with highest lift (sorted by absolute lift)

Maximum array length: 50

Show child attributes

metadata · Metadata · object

Additional metadata (collection_id, event counts, etc.)