FOformbricks
V3 Responses

Count responses

Changed on

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

Request

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

Query parameters

workspaceIdstring cuid2 required

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

surveyIdstring cuid2

Optional survey scoping.

contactIdstring 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[]

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.

precision'capped' | 'exact'

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.

Response

Count retrieved successfully

Changes

  • 84820a01e550Revision changes
    • warning

      added the new chart_in_use enum value to the response property for the response status

    • warning

      added the new chart_in_use enum value to the response property for the response status

    • warning

      added the new chart_in_use enum value to the response property for the response status

    • warning

      added the new chart_in_use enum value to the response property for the response status

    • warning

      added the new chart_in_use enum value to the response property for the response status

    • warning

      added the new dashboards_plan_required enum value to the response property for the response status

    • warning

      added the new dashboards_plan_required enum value to the response property for the response status

    • warning

      added the new dashboards_plan_required enum value to the response property for the response status

    • warning

      added the new dashboards_plan_required enum value to the response property for the response status

    • warning

      added the new dashboards_plan_required enum value to the response property for the response status

    • warning

      added the new limit_exceeded enum value to the // response property for the response status

    • warning

      added the new limit_exceeded enum value to the // response property for the response status

    • warning

      added the new limit_exceeded enum value to the // response property for the response status

    • warning

      added the new limit_exceeded enum value to the // response property for the response status

    • warning

      added the new limit_exceeded enum value to the // response property for the response status

  • aad5dc1d8236Revision changes
    • warning

      added the new creatives_not_entitled enum value to the response property for the response status

    • warning

      added the new creatives_not_entitled enum value to the response property for the response status

    • warning

      added the new creatives_not_entitled enum value to the response property for the response status

    • warning

      added the new creatives_not_entitled enum value to the response property for the response status

    • warning

      added the new creatives_not_entitled enum value to the response property for the response status

    • warning

      added the new survey_has_linked_creatives enum value to the response property for the response status

    • warning

      added the new survey_has_linked_creatives enum value to the response property for the response status

    • warning

      added the new survey_has_linked_creatives enum value to the response property for the response status

    • warning

      added the new survey_has_linked_creatives enum value to the response property for the response status

    • warning

      added the new survey_has_linked_creatives enum value to the response property for the response status