Get Available Steps

Get all available steps for a taxonomy and collection.

This endpoint discovers what steps exist in your analytics data by querying the ClickHouse taxonomy_events table. Use this before querying transitions or paths to understand what step values you can use.

Use Cases:

• Discover available steps before querying analytics
• Validate step names (avoid typos in from_step/to_step)
• See which steps have the most events
• Check data freshness (first_seen/last_seen timestamps)

Example Usage:

# 1. Get available steps
GET /v1/taxonomies/tax_sales/analytics/available-steps?collection_id=col_emails

# Response:
{
    "taxonomy_id": "tax_sales",
    "collection_id": "col_emails",
    "total_events": 5432,
    "total_sequences": 1000,
    "steps": [
        {"step_key": "inquiry", "event_count": 1000, ...},
        {"step_key": "followup", "event_count": 450, ...},
        {"step_key": "closed_won", "event_count": 350, ...}
    ]
}

# 2. Use discovered steps in transition query
POST /v1/taxonomies/tax_sales/analytics/transitions
{
    "collection_id": "col_emails",
    "from_step": "inquiry",      # From available steps
    "to_step": "closed_won"      # From available steps
}

Args: request: FastAPI request object (contains tenant context) taxonomy_id: Taxonomy ID to query collection_id: Collection ID for filtering events

Returns: AvailableStepsResponse with all steps sorted by event count (descending)

Raises: NotFoundError: If taxonomy not found ValidationError: If unable to query ClickHouse