---
title: "Get a creative's counts"
method: GET
path: "/api/v3/creatives/{creativeId}/stats"
tags: ["V3 Creatives"]
---

# Get a creative's counts

`GET /api/v3/creatives/{creativeId}/stats`

## Request

- Base URL: `https://app.formbricks.com`
- URL: `https://app.formbricks.com/api/v3/creatives/{creativeId}/stats`
- Auth: one of:
  - API key in cookie `next-auth.session-token`
  - API key in header `x-api-key`
  - HTTP bearer

Returns a creative's Impressions and Clicks per UTC day from `from` to `to` (both inclusive), their totals and Click rate, and, with `groupBy`, the same counts by page or by device type. Read access to the creative's workspace; an unknown or inaccessible `creativeId` answers **403**.

Counts are kept per day, not per event. The web SDK reports what visitors see, and a background job adds it here about once a minute, so a count can lag by up to a minute. An instance running without its BullMQ worker never adds counts. Archived creatives keep their counts, deleting a creative deletes them, and a duplicate starts with none.

**400** when `from` is after `to`, or the range spans more than 366 days.

## Path parameters

- `creativeId` string, cuid2, required

## Query parameters

- `from` string, date
- `to` string, date
- `groupBy` 'page' | 'device'

## Response `200`

Counts retrieved successfully

- object
  - `data` CreativeStats, required: A creative's Impressions and Clicks over a range of UTC days. An **Impression** is one page view on which the creative showed (showing it again on the same page adds none; a new page, a single-page-app route change included, does). A **Click** is one press that opened its Destination; dismissing a banner, or pressing while its survey is already open, isn't one. `clickRate` is Clicks divided by Impressions, as a fraction (`0.05` is 5 %), or `null` without Impressions. `totals` and every breakdown count the same events, so `days`, `pages` and `devices` each add up to `totals`.
    - `creativeId` string, cuid2, required
    - `from` string, date, required: First UTC day counted, inclusive.
    - `to` string, date, required: Last UTC day counted, inclusive.
    - `groupBy` 'page' | 'device' | 'null', nullable, required: The breakdown requested, which adds `pages` or `devices`; `null` for none.
    - `totals` CreativeStatsCounts, required: Impressions, Clicks and Click rate (Clicks divided by Impressions; `null` without Impressions).
      - `impressions` integer, required
      - `clicks` integer, required
      - `clickRate` number, nullable, required
    - `days` CreativeStatsDay[], required: One entry per UTC day from `from` to `to`, oldest first, days without counts included.
      - `date` string, date, required
      - `impressions` integer, required
      - `clicks` integer, required
      - `clickRate` number, nullable, required
    - `pages` CreativeStatsPage[]: Only with `groupBy=page`. Where the Impressions and Clicks happened, most Impressions first, at most 100 pages. `(other)` sums every page not listed, including pages beyond the 1000 a creative counts per day; it comes last and only when it has counts.
      - `page` string, required: Host and path, without query string or hash (`example.com/pricing`), or `(other)` for every page not listed.
      - `impressions` integer, required
      - `clicks` integer, required
      - `clickRate` number, nullable, required
    - `devices` CreativeStatsDevice[]: Only with `groupBy=device`. The counts per device type, always `phone`, `tablet` and `desktop`, in that order.
      - `deviceType` 'phone' | 'tablet' | 'desktop', required: The device type the SDK detected, as in the Show when `deviceType` condition.
      - `impressions` integer, required
      - `clicks` integer, required
      - `clickRate` number, nullable, required

## Other responses

- `400`: Bad Request — malformed JSON, invalid query/body/params, duplicate name, or unsupported field.
- `401`: Not authenticated (no valid session or API key).
- `403`: Forbidden, one of two codes. `forbidden`: the caller lacks the workspace access the operation needs, or the creative does not exist (404 is not used, so creative ids cannot be probed for existence). `creatives_not_entitled`: Creatives is not available on this instance (Formbricks Cloud, or a self-hosted license that does not include it). It is checked only after the caller's own access, so it says nothing about a workspace the caller cannot see. A workspace that still has creatives is in wind-down: listing, reading, stats, a PATCH that sets nothing but `status` to `paused` or `completed`, pausing a survey's creatives (`POST /api/v3/creatives/pause`), and DELETE keep working, and everything else answers this. A workspace without creatives answers it on every operation.
- `429`: Rate limit exceeded.
- `500`: Internal Server Error.

## Changes

- **2026-10-28** `84820a01e550`: 15 warning
  - added the new `chart_in_use` enum value to the `code` response property for the response status `400`
  - added the new `chart_in_use` enum value to the `code` response property for the response status `401`
  - added the new `chart_in_use` enum value to the `code` response property for the response status `403`
  - added the new `chart_in_use` enum value to the `code` response property for the response status `429`
  - …11 more
- **2026-10-27** `aad5dc1d8236`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/creatives/:creativeId/stats/get.md)

---

[API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) - [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/formbricks/apis/formbricks-api-v3/revisions/25335c959a13?raw)