---
title: "List taxonomy analytics run history"
method: GET
path: "/v1/taxonomies/{taxonomy_id}/analytics/runs"
tags: ["Taxonomy Analytics"]
---

# List taxonomy analytics run history

`GET /v1/taxonomies/{taxonomy_id}/analytics/runs`

## Request

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

List previously executed step-analytics runs (transitions and paths) for a taxonomy, newest-executed first. Runs are de-duplicated by their parameters, so re-running the same analysis updates the existing entry and bumps its run_count instead of creating a duplicate.

## Path parameters

- `taxonomy_id` string, required

## Query parameters

- `analysis_type` 'transitions' | 'paths': Kind of taxonomy step-analytics computed for a persisted run. Attributes: TRANSITIONS: Direct A→B transition analytics (conversion rate, durations, predictor lifts) produced by the ``/analytics/transitions`` endpoint. PATHS: Multi-step path discovery produced by the ``/analytics/paths`` endpoint.
- `collection_id` string, nullable: Filter by collection ID
- `page` integer: Page number (1-indexed)
- `page_size` integer: Items per page

## Response `200`

Successful Response

- TaxonomyAnalyticsRunListResponse: Paginated list of persisted taxonomy analytics runs. Attributes: runs: The runs on this page (sorted newest-executed first). total: Total number of runs matching the filters. page: 1-indexed page number. page_size: Number of runs per page.
  - `runs` TaxonomyAnalyticsRun[], required: Runs on this page
    - `run_id` string, required: Stable run identifier (taxrun_...)
    - `taxonomy_id` string, required: Taxonomy analyzed
    - `collection_id` string, required: Collection analyzed
    - `analysis_type` 'transitions' | 'paths', required: Kind of taxonomy step-analytics computed for a persisted run. Attributes: TRANSITIONS: Direct A→B transition analytics (conversion rate, durations, predictor lifts) produced by the ``/analytics/transitions`` endpoint. PATHS: Multi-step path discovery produced by the ``/analytics/paths`` endpoint.
    - `params` object: Request params used for the run
    - `params_hash` string, required: De-dup hash of the normalized params
    - `from_step` string, required: Starting step
    - `to_step` string, required: Ending step
    - `name` string, nullable: Optional run label
    - `result` object, nullable: Computed analytics result
    - `status` string: Run status
    - `error_message` string, nullable: Error message if the run failed
    - `run_count` integer: Number of times these params have been executed
    - `namespace_id` string: Tenant namespace
    - `internal_id` string: Tenant/org id
    - `created_at` string, date-time, nullable: First persisted at
    - `updated_at` string, date-time, nullable: Last (re-)executed at
  - `total` integer, required: Total matching runs
  - `page` integer, required: 1-indexed page number
  - `page_size` integer, required: Runs per page

## 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/runs/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)