Count responses

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.

GET /api/v3/responses/count

Count responses

cURL

curl --request GET \
  --url https://app.formbricks.com/api/v3/responses/count \
  --cookie next-auth.session-token=

200

{
  "data": {
    "count": 1,
    "relation": "eq"
  }
}

Authorizations

sessionAuthapiKeyAuthbearerAuth

next-auth.session-token · string · cookie · required

NextAuth session JWT cookie. Development: often next-auth.session-token. Production (HTTPS): often __Secure-next-auth.session-token. Send the cookie your browser receives after sign-in.

Query Parameters

workspaceId · string<cuid2> · required

Workspace identifier. This is the canonical container ID for v3 APIs.

surveyId · string<cuid2>

Optional survey scoping.

contactId · string<cuid2>

Optional contact scoping.

filter[createdAt][gte] · string<date-time>

Only records created at or after this instant (inclusive). Mutually exclusive with filter[createdAt][gt] — sending both is a 400.

filter[createdAt][gt] · string<date-time>

Only records created strictly after this instant (exclusive). Paired with filter[createdAt][lt] this is a fully open (start, end) window. For a half-open [start, end) window — the one whose consecutive pages tile without dropping a record that sits exactly on a boundary instant — use filter[createdAt][gte] with filter[createdAt][lt]. Mutually exclusive with filter[createdAt][gte] — sending both is a 400.

filter[createdAt][lte] · string<date-time>

Only records created at or before this instant (inclusive). Mutually exclusive with filter[createdAt][lt] — sending both is a 400.

filter[createdAt][lt] · string<date-time>

Only records created strictly before this instant (exclusive). The upper bound of a half-open [start, end) window, which is what makes consecutive windows tile without overlapping or dropping a record on the boundary. Mutually exclusive with filter[createdAt][lte] — sending both is a 400.

filter[finished][eq] · boolean

Completed (true) or partial (false) responses only. Requires surveyId or contactId, for the same reason as on the list endpoint.

filter[language][in] · string[]

Survey language codes to include. Requires surveyId or contactId.

filter[id][in] · string<cuid2>[]

Count a specific set of responses by id, at most 100 per call. Ids outside the requested scope are simply not counted rather than erroring, so this cannot be used to probe whether an id exists elsewhere.

Maximum array length: 100

precision · enum<string> · default: capped

How hard to count. capped (the default) stops at 10 000 and reports relation: gte at the cap — flat cost, safe to call on anything. exact counts every matching row and reports relation: eq always.

exact is the deliberate slow path: cost grows superlinearly with the matching set, so on a large or loosely-filtered scope it is markedly more expensive than a page of data. Ask for it when a person needs a precise figure, not on a dashboard poll. It exists so that the capped default is a sensible default rather than a limitation, and so the cap cannot be sidestepped by accident.

exact requires surveyId or contactId, and answers 400 naming precision without one — the same anchor rule filter[finished][eq] and filter[language][in] carry. capped stops at the cap whatever the scope, so its cost is flat; an unanchored exact is a full scan of every response in the workspace, and the contract refuses a query it cannot bound rather than serving it slowly. For a workspace-wide figure use the capped default, which reports relation: gte once it reaches the cap.

Available options: capped, exact

Response

200

application/json

Count retrieved successfully

data · object · required

Show child attributes