---
title: "Get Metric Detail"
method: GET
path: "/v2/analytics/{metric}/detail"
---

# Get Metric Detail

`GET /v2/analytics/{metric}/detail`

## Request

- Base URL: `https://api.traversal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.traversal.com/v2/analytics/{metric}/detail`
- Auth: none declared

Return a metric's detail view — a ranked table for every metric that has one today.

Requires organization admin role or higher. A metric with no detail view is a 404
(``ANALYTICS_METRIC_HAS_NO_DETAIL``) rather than an empty table.

## Path parameters

- `metric` 'active_users' | 'new_users' | 'session_starters' | 'sessions' | 'sessions_and_users' | 'sessions_per_user' | 'activity_heatmap' | 'top_users' | 'top_channels' | 'top_sessions' | 'investigators', required: Stable, public metric ids. Append-only — never rename or repurpose.

## Query parameters

- `start_time` string, date-time, nullable: Start timestamp (inclusive), ISO 8601 with timezone. Defaults to 30 days ago.
- `end_time` string, date-time, nullable: End timestamp (exclusive), ISO 8601 with timezone. Defaults to now.
- `page` integer, nullable: 1-indexed page number. Ignored unless `limit` is also set; defaults to 1.
- `limit` integer, nullable: Rows per page. Omit to return every row in the window (the original, unpaginated behavior).
- `query` string, nullable: Case-insensitive substring match against the session title or the creator's email. Blank is treated as no search; otherwise must be at least 3 non-whitespace characters.
- `actor_type` 'user' | 'service_account'

## Response `200`

Successful Response

- MetricDetailResponse: A metric's detail view, fetched on demand rather than inlined. ``data`` is named for the payload, not its shape: every detail view is a ranked table today, so only the field's type would change if one isn't. It is the same ``RankedTableData`` the inlined tables carry, so clients reuse their table component. ``count``/``prev``/``next``/``total`` are unset unless the request paginated (matching ``GET /sessions``'s envelope) — a client that never sends ``page``/``limit`` keeps getting every row in ``data.rows`` with no pagination metadata, exactly as before.
  - `metric` 'active_users' | 'new_users' | 'session_starters' | 'sessions' | 'sessions_and_users' | 'sessions_per_user' | 'activity_heatmap' | 'top_users' | 'top_channels' | 'top_sessions' | 'investigators', required: Stable, public metric ids. Append-only — never rename or repurpose.
  - `window` AnalyticsWindowResponse, required: The selected range and how the payload's figures were bucketed — the granularity and the timezone whose day boundaries were used. A day bucket is only meaningful relative to a zone, so ``timezone`` says which one: render every date and DATETIME cell in it, and label them with it. UTC for every org today; if bucketing ever moves to a per-org local day, this field carries that zone and rendering follows with no client change.
    - `start` string, date-time, required
    - `end` string, date-time, required
    - `granularity` 'day', required
    - `timezone` string, required: IANA timezone whose day boundaries the buckets use, and which every date and DATETIME cell in the payload should be rendered in (e.g. 'UTC')
  - `data` RankedTableData, required: A ranked leaderboard table (e.g. top users / channels by session count). Rows are pre-sorted (row index + 1 is the rank); every row's ``cells`` keys match ``columns``, so the table can carry any number of columns. **A compact rendering takes each row's headline number from the first COUNT column.** That is how the leaderboard card picks its progress-bar value, so a table rendered that way carries exactly one COUNT column: the value it ranks by. Tables only ever rendered in full may carry several, in whatever order reads best, and there ``sort`` alone says what the rows are ranked by.
    - `columns` RankedTableColumn[], required
      - `key` string, required
      - `label` string, required
      - `format` 'count' | 'text' | 'datetime' | 'actor', required: How the FE renders a column's cells — alignment and display intent in one flag, so it never has to sniff a value (append-only; the FE keys off these). COUNT: right-aligned, locale-formatted. The only numeric format, so also what marks a column as a ranking value (see ``RankedTableData``). TEXT: left-aligned, verbatim. DATETIME: ISO 8601, rendered in ``AnalyticsWindowResponse.timezone`` so a row's timestamp can't disagree with the day bucket the charts count it in. ACTOR: left-aligned text naming a person or service account; the FE marks the row's ``actor_type`` beside it.
      - `link_href_template` string, nullable
    - `rows` RankedTableRow[], required
      - `cells` object, required
      - `entity_id` string, nullable
      - `actor_type` 'user' | 'service_account', required
    - `sort` RankedTableSort: Which column ``RankedTableData.rows`` are pre-sorted by and in which direction, so the FE can render the sort indicator on that column (and default any client-side re-sort to match). ``column`` is a ``RankedTableColumn.key``.
      - `column` string, required
      - `order` 'asc' | 'desc': Sort direction for a ranked table (append-only; the FE keys off these values).
    - `hide_search_bar` boolean
  - `count` integer, nullable: Rows in this page; None when the response is unpaginated.
  - `prev` integer, nullable: Previous page number, if any.
  - `next` integer, nullable: Next page number, if any.
  - `total` integer, nullable: Total rows matching the window/search across all pages; None when unpaginated.

## Other responses

- `422`: Validation Error

## Changes

> 66 revisions in range; 9 not diffed.

- **2026-09-30** `4fa2a4911e01`: 1 warning, 2 info
  - added the new `actor` enum value to the `data/columns/items/format` response property for the response status `200`
  - added the new optional `query` request parameter `actor_type`
  - added the required property `data/rows/items/actor_type` to the response with the `200` status

[Operation history](https://skmtc.dev/traversal/apis/traversal-api/changes/v2/analytics/:metric/detail/get.md)

---

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