> ## Documentation Index
> Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a heatmap

> Fetch thread counts by day of week and hour of day, in UTC, with threadHeatmapMetric.

`threadHeatmapMetric` returns a grid of 7 days by 24 hours, with the count for each hour of each weekday across the date range. It powers the [heatmaps](/docs/product/platform/heatmaps) in Insights.

<Snippet file="graphql/sdk-note.mdx" />

This query requires the `metrics:read` permission for `threads_created_count_heatmap`, and `metricsAgent:read` for `agent_messages_sent_count`. See [Permissions](/docs/graphql/reporting#permissions).

## Get a heatmap

`input` takes these fields:

* **`metricName`**: `threads_created_count_heatmap` for threads created, or `agent_messages_sent_count` for threads users sent messages on
* **`from`** and **`to`**: the date range, in UTC. The heatmap doesn't widen them
* **`mode`**: `METRIC` for counts, or `THREAD_IDS` for the threads behind a cell, row, or column
* **`filters`**: see [Filter and group reporting queries](/docs/graphql/reporting/filters). Heatmaps don't support `groupBy`. For `agent_messages_sent_count`, set `filters.userIds` to count only some users

This query returns the September heatmap of Urgent and High priority threads:

<Snippet file="graphql/get-thread-heatmap-metric.mdx" />

## Read the response

`days` has 7 entries, from Monday at index `0` to Sunday at index `6`. Each holds 24 entries for hours 0 to 23 in UTC. Every cell has a `total` and a `percentage`, which is the cell's share of the whole grid from 0 to 100. Empty cells are `0`.

`agent_messages_sent_count` counts threads, not messages: each cell counts the threads a user sent at least one message on in that hour of that weekday.

## Get the threads behind a cell

Set `mode` to `THREAD_IDS` and pass `threadIdsArgs` to pick the slice:

* **`dayOfWeek`**: `1` for Monday to `7` for Sunday
* **`hourOfDay`**: `0` to `23`, in UTC

Set both for one cell, only `dayOfWeek` for a row, or only `hourOfDay` for a column. At least one is required. `dayOfWeek` starts at `1` while `days` starts at index `0`, so add 1 to the index of the day you read from `days`.

This query returns the threads created on any Monday between 09:00 and 09:59 UTC in September:

<Snippet file="graphql/get-thread-heatmap-metric-thread-ids.mdx" />

`days` is `null` in this mode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.