---
title: "Get today's highlights"
method: GET
path: "/api/projects/{project_id}/today/highlights/"
tags: ["today"]
---

# Get today's highlights

`GET /api/projects/{project_id}/today/highlights/`

## Request

- Base URL: `https://us.posthog.com`
- URL: `https://us.posthog.com/api/projects/{project_id}/today/highlights/`
- Auth: HTTP bearer

The project's key metrics and up to 6 ranked items, each labeled risk or opportunity. Queries, rules and copy templates make every item; no AI is used. The highlights are computed in the background and stay fresh for 15 minutes per person, or 1 minute when a source failed. The call never waits: while they are computed, it returns `computing` with the last ready highlights of the day, so poll every 2 seconds until the status is `ready` or `failed`. 404 when the person does not have the new navigation. A scoped key needs query:read as well, because every highlight runs a query.

## Path parameters

- `project_id` string, required

## Response `200`

- Highlights
  - `status` 'computing' | 'ready' | 'failed', required: * `computing` - Computing * `ready` - Ready * `failed` - Failed
  - `generated_at` string, date-time, nullable, required: When the content was computed. Null when no highlights were computed yet today.
  - `day` string, date, required: The day the highlights are for, in the project's timezone.
  - `refresh_at` string, date-time, required: Midnight at the end of `day` in the project's timezone, when the next day's highlights start. Load them again then.
  - `pulse` HighlightMetric[], required: Key metrics of the project from its settings.
    - `key` string, required: Stable key of the metric: a key metric setting such as signup_event, or insight:<short_id>.
    - `name` string, required: Name of the key metric or of the insight, for example Sign-ups.
    - `value` number, double, required: Value for the last complete period: the last 7 complete days, or the last complete week or month.
    - `unit` 'events' | 'people' | 'number', required: * `events` - Events * `people` - People * `number` - Number
    - `change_pct` number, double, nullable, required: Change against the period before, in percent. Null when the period before is 0.
    - `series` number[], required: Values oldest first: daily for the last 28 complete days, or one value per week or month.
    - `interval` 'day' | 'week' | 'month', required: * `day` - Day * `week` - Week * `month` - Month
    - `url` string, nullable, required: Path of the insight the metric comes from. For a key metric, a new trends insight of the same days.
    - `value_format` HighlightValueFormat, required
      - `format` string, nullable, required: Number format of the insight, for example numeric, percentage or currency.
      - `prefix` string, nullable, required: Text the insight shows before each value.
      - `postfix` string, nullable, required: Text the insight shows after each value.
      - `decimal_places` integer, nullable, required: Most decimal places the insight shows.
    - `period_starts` string[], required: The first day of the period each value in `series` covers, in the project's timezone. Same length and order as `series`.
    - `reason` union, required: Why the pulse suggests the metric: `routine` for an insight the person opens often, `dashboard` for a tile of a dashboard they open often, `key_metric` for a key metric of the project. Null for a number the person pinned, which `pins` lists, and for metrics computed before this field existed. * `routine` - You open this often * `dashboard` - On a dashboard you open often * `key_metric` - Project key metric
      - 'routine' | 'dashboard' | 'key_metric': * `routine` - You open this often * `dashboard` - On a dashboard you open often * `key_metric` - Project key metric
      - unknown
    - `dashboard_name` string, nullable, required: Name of the dashboard the tile comes from when `reason` is `dashboard`, else null.
    - `dashboard_id` integer, nullable, required: Id of the dashboard the tile comes from, with its filters applied. Pass it when pinning the tile. Null otherwise.
    - `opened_days` integer, nullable, required: On how many of the last 14 days the person opened the insight, or the dashboard of the tile. Null for a key metric.
    - `last_opened` string, date, nullable, required: The last day the person opened the insight, or the dashboard of the tile, in the project's timezone. Null for a key metric.
    - `previous_value` number, double, nullable, required: Value for the period before the last complete one, the base of `change_pct`. Null when unknown.
    - `movers` HighlightMover[], required: For an insight with several series, the series that changed most last period, biggest change first. Empty otherwise.
      - `label` string, required: Name of one series of the insight, for example a breakdown value.
      - `value` number, double, required: Value of the series for the last complete period.
      - `change_pct` number, double, nullable, required: Change of the series against the period before, in percent. Null when the period before is 0.
  - `items` HighlightItem[], required: Up to 6 items, the highest scores across sources, in display order: by `priority`, then by `score`, highest first.
    - `key` string, required: Stable key of the item for this person and day.
    - `label` 'risk' | 'opportunity', required: * `risk` - Risk * `opportunity` - Opportunity
    - `priority` 'P1' | 'P2' | 'P3' | 'P4', required: * `P1` - P1 * `P2` - P2 * `P3` - P3 * `P4` - P4
    - `title` string, required: One sentence that says what happened, with numbers.
    - `detail` string, required: One or two short sentences with the comparison and the next action.
    - `url` string, nullable, required: Path in the app to open, relative to the project.
    - `series` number[], nullable, required: Values behind the item for a small trend line, oldest first. Null when the item has no trend.
    - `score` number, double, required: Importance weighted by relevance, from 0 to 1.
    - `source` string, required: Name of the highlight source that found the item, for example alerts.
  - `pins` HighlightPin[], required: The numbers the person keeps, in their order, with the state of each one. Pinned numbers lead `pulse`.
    - `key` string, required: Key of a number the person keeps on their home.
    - `status` 'ready' | 'unavailable', required: * `ready` - Ready * `unavailable` - Unavailable

## Changes

> 52 revisions in range; 1 not diffed.

- **2026-10-21** `e263ffc38ef5`: 2 info
  - added the required property `pins` to the response with the `200` status
  - added the required property `pulse/items/dashboard_id` to the response with the `200` status
- **2026-10-15** `1abab9893be9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/posthog/apis/posthog-api/changes/api/projects/:project_id/today/highlights/get.md)

---

[API](https://skmtc.dev/posthog/apis/posthog-api.md) · [All operations](https://skmtc.dev/posthog/apis/posthog-api/llms.txt) · [OpenAPI document](https://skmtc.dev/posthog/apis/posthog-api/revisions/71e64193672d?raw)