Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomy 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

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

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

Path parameters

taxonomy_idstring required

Request body

collection_idstring required

Collection to analyze for step transitions

taxonomy_idstring required

Taxonomy ID (each taxonomy_id is immutable, clone creates new ID)

from_stepstring required

Starting step label (e.g., 'inquiry', 'draft')

to_stepstring required

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

max_window_daysinteger nullable

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

filtersobject nullable

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

min_supportinteger

Minimum number of sequences required for valid analysis

Example request

{
  "from_step": "inquiry",
  "to_step": "closed_won",
  "override_step_analytics": {
    "timestamp_field": "Date",
    "sequence_id_field": "Thread-Index",
    "step_key_field_path": "metadata.workflow_stage",
    "covariates": [
      {
        "field_path": "sender_domain",
        "name": "Sender Domain"
      }
    ]
  }
}

Response

Successful Response

from_stepstring required

Starting step

to_stepstring required

Ending step

countinteger required

Total number of sequences starting at from_step

convertedinteger required

Number of sequences that reached to_step

conversion_ratenumber required

Percentage that converted (converted / count)

metadataobject

Additional metadata (collection_id, event counts, etc.)