---
title: "Get Available Steps"
method: GET
path: "/v1/taxonomies/{taxonomy_id}/analytics/available-steps"
tags: ["Taxonomy Analytics"]
---

# Get Available Steps

`GET /v1/taxonomies/{taxonomy_id}/analytics/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:**
```python
# 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

## Path parameters

- `taxonomy_id` string, required

## Query parameters

- `collection_id` string, required — Collection ID to analyze

## Response `200`

Successful Response

- AvailableStepsResponse — Response containing all available steps for a taxonomy/collection. This endpoint helps users discover what steps exist in their analytics data before querying transitions or paths. Example Response: ```json { "taxonomy_id": "tax_sales_stages", "collection_id": "col_emails", "total_events": 5432, "total_sequences": 1000, "steps": [ { "step_key": "inquiry", "event_count": 1000, "sequence_count": 1000, "first_seen": "2025-11-01T00:00:00Z", "last_seen": "2025-12-07T00:00:00Z" }, { "step_key": "followup", "event_count": 450, "sequence_count": 450, "first_seen": "2025-11-02T00:00:00Z", "last_seen": "2025-12-06T00:00:00Z" }, { "step_key": "closed_won", "event_count": 350, "sequence_count": 350, "first_seen": "2025-11-05T00:00:00Z", "last_seen": "2025-12-07T00:00:00Z" } ] } ```
  - `taxonomy_id` string, required — Taxonomy ID
  - `collection_id` string, required — Collection ID
  - `total_events` integer, required — Total events in dataset
  - `total_sequences` integer, required — Total unique sequences
  - `steps` StepInfo[], required — Available steps sorted by count
    - `step_key` string, required — Step identifier
    - `event_count` integer, required — Total events for this step
    - `sequence_count` integer, required — Unique sequences with this step
    - `first_seen` string, required — Earliest event timestamp (ISO format)
    - `last_seen` string, required — Most recent event timestamp (ISO format)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)