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

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/taxonomies/{taxonomy_id}/analytics/available-steps`
- Auth: HTTP bearer and API key in header `X-Namespace`

Get all available steps for a taxonomy and collection.

This endpoint discovers what steps exist in your analytics data by querying
the taxonomy_events analytics collection. 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 the analytics store

## 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`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/taxonomies/:taxonomy_id/analytics/available-steps/get.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)