Compute step transition analytics

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/transitions \
  --header 'Content-Type: application/json' \
  --data '
{
  "collection_id": "<string>",
  "taxonomy_id": "<string>",
  "from_step": "<string>",
  "to_step": "<string>",
  "max_window_days": 183,
  "filters": {},
  "override_step_analytics": {
    "timestamp_field": "<string>",
    "sequence_id_field": "<string>",
    "step_key_source": "assignment_label",
    "step_key_field_path": "metadata.workflow_stage",
    "covariates": [
      {
        "field_path": "<string>",
        "covariate_type": "categorical",
        "name": "<string>",
        "binning_strategy": "quartiles",
        "clustering_method": "kmeans",
        "n_clusters": 10
      }
    ],
    "max_sequence_duration_days": 183
  },
  "min_support": 10
}
'

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

Analytics

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

taxonomies

{taxonomy_id}

analytics

transitions

Compute step transition analytics

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/transitions \
  --header 'Content-Type: application/json' \
  --data '
{
  "collection_id": "<string>",
  "taxonomy_id": "<string>",
  "from_step": "<string>",
  "to_step": "<string>",
  "max_window_days": 183,
  "filters": {},
  "override_step_analytics": {
    "timestamp_field": "<string>",
    "sequence_id_field": "<string>",
    "step_key_source": "assignment_label",
    "step_key_field_path": "metadata.workflow_stage",
    "covariates": [
      {
        "field_path": "<string>",
        "covariate_type": "categorical",
        "name": "<string>",
        "binning_strategy": "quartiles",
        "clustering_method": "kmeans",
        "n_clusters": 10
      }
    ],
    "max_sequence_duration_days": 183
  },
  "min_support": 10
}
'

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

Headers

Authorization

string

REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.

X-Namespace

string

REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'

Path Parameters

taxonomy_id

string

required

Body

application/json

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

to_step

string

required

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

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

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

override_step_analytics

StepAnalyticsConfig · object

Override taxonomy's default step_analytics config for this query

Show child attributes

override_step_analytics.timestamp_field

string

required

Document field containing event timestamp (e.g., 'Date', 'created_at', 'metadata.timestamp')

override_step_analytics.sequence_id_field

string

required

Document field that groups related items into a sequence (e.g., 'Thread-Index', 'session_id', 'user_id')

override_step_analytics.step_key_source

enum<string>

default:assignment_label

How to determine the 'step' for each document (label, node_id, or custom field)

Available options:

assignment_label,

assignment_node_id,

field_path

override_step_analytics.step_key_field_path

string | null

Required if step_key_source='field_path'. Dot-notation path to step value in document.

Example:

"metadata.workflow_stage"

override_step_analytics.covariates

CovariateConfig · object[]

Predictor fields to analyze for conversion lift (categorical, numeric, embedding, cluster)

Maximum array length: 20

Show child attributes

override_step_analytics.covariates.field_path

string

required

Dot-notation path to covariate field (e.g., 'sender_domain', 'metadata.priority')

override_step_analytics.covariates.covariate_type

enum<string>

required

Type of covariate determines analysis strategy (categorical/numeric/embedding/cluster)

Available options:

categorical,

numeric,

embedding,

cluster_id

override_step_analytics.covariates.name

string

required

Human-readable name for this covariate in analytics results

Required string length: 1 - 100

override_step_analytics.covariates.binning_strategy

enum<string> | null

default:quartiles

How to bin numeric values for lift analysis (only used for NUMERIC type)

Available options:

quartiles,

deciles,

custom

override_step_analytics.covariates.clustering_method

enum<string> | null

default:kmeans

Clustering algorithm for embedding analysis (only used for EMBEDDING type)

Available options:

kmeans,

hdbscan

override_step_analytics.covariates.n_clusters

integer | null

default:10

Number of clusters for embedding-based predictors (only used for EMBEDDING type)

Required range: 2 <= x <= 100

override_step_analytics.max_sequence_duration_days

integer | null

Maximum allowed duration for a sequence. Sequences beyond this are flagged as data quality issues.

Required range: 1 <= x <= 365

min_support

integer

default:10

Minimum number of sequences required for valid analysis

Required range: x >= 1

Response

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

Duration statistics (None if no conversions)

Show child attributes

durations_sec.mean

number

required

Average duration in seconds

durations_sec.median

number

required

Median duration in seconds

durations_sec.p50

number

required

50th percentile (same as median)

durations_sec.p90

number

required

90th percentile duration in seconds

durations_sec.p95

number

required

95th percentile duration in seconds

durations_sec.std_dev

number

required

Standard deviation in seconds

durations_sec.min

number

required

Minimum duration observed in seconds

durations_sec.max

number

required

Maximum duration observed in seconds

top_predictors

PredictorLift · object[]

Covariates with highest lift (sorted by absolute lift)

Maximum array length: 50

Show child attributes

top_predictors.field

string

required

Covariate field name

top_predictors.value

string

required

Specific value or bin label

top_predictors.count

integer

required

Number of sequences with this value

Required range: x >= 0

top_predictors.conversion_rate

number

required

Conversion rate for this value

Required range: 0 <= x <= 1

top_predictors.lift

number

required

Lift relative to baseline (>1.0 = positive, <1.0 = negative)

metadata

Metadata · object

Additional metadata (collection_id, event counts, etc.)

Delete Taxonomy Analyze multi-step transition paths

⌘I

Health

Organizations

Namespaces

Buckets

Feature Extractors

Collections

Retrievers

Taxonomies

Clusters

Templates

Analytics

Resource Search

Inference

Agent Sessions

Tasks

Webhooks

Notifications

Triggers

Compute step transition analytics

Headers

Path Parameters

Body

Response