---
title: "Count responses"
method: GET
path: "/api/v3/responses/count"
tags: ["V3 Responses"]
---

# Count responses

`GET /api/v3/responses/count`

## Request

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

Returns how many responses match a scope and filter set, without fetching any of them.

This exists as its own operation because "how many match this?" is the question asked most often and it should not require paging through data to answer — particularly for agent clients, where a page of payloads to obtain a single integer is pure waste. It takes the same scope and filter parameters as `GET /api/v3/responses`, minus pagination and sorting, so a count and a page are always answering the same question.

The list endpoint's `meta.totalCount` covers the other case: a caller already paging that also wants the total. That one is opt-in; this one is the direct route.

## Query parameters

- `workspaceId` string, cuid2, required
- `surveyId` string, cuid2
- `contactId` string, cuid2
- `filter[createdAt][gte]` string, date-time
- `filter[createdAt][gt]` string, date-time
- `filter[createdAt][lte]` string, date-time
- `filter[createdAt][lt]` string, date-time
- `filter[finished][eq]` boolean
- `filter[language][in]` string[]
- `filter[id][in]` string[]
- `precision` 'capped' | 'exact'

## Response `200`

Count retrieved successfully

- object
  - `data` object, required
    - `count` integer, required: Responses matching the scope and filters. With `precision=capped` this stops at 10 000; read `relation` before presenting it as a total.
    - `relation` 'eq' | 'gte', required: `eq` when `count` is exact, `gte` when the 10 000 cap was reached and `count` is a lower bound. Always `eq` when `precision=exact`. Same convention as `meta.totalCountRelation` on the list endpoint.

## Other responses

- `400`: Bad Request — invalid or unrecognized query parameters, including `filter[finished][eq]` or `filter[language][in]` without `surveyId` or `contactId`. Date bounds follow the same pairing rule as the list endpoint: at most one lower bound (`gte` xor `gt`), at most one upper bound (`lte` xor `lt`), and the lower bound must not fall after the upper one.
- `401`: Not authenticated (no valid session or API key).
- `403`: Forbidden — no workspace access, or resource does not exist (404 not used; avoids existence leak).
- `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`: 10 warning
  - added the new `creatives_not_entitled` enum value to the `code` response property for the response status `400`
  - added the new `creatives_not_entitled` enum value to the `code` response property for the response status `401`
  - added the new `creatives_not_entitled` enum value to the `code` response property for the response status `403`
  - added the new `creatives_not_entitled` enum value to the `code` response property for the response status `429`
  - …6 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/responses/count/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)