FOformbricks
V3 Surveys

List surveys

Changed on

Returns the surveys in the workspace that the caller may read. A restricted survey is listed only to its owner and to the organisation's owners and managers; to everyone else, API keys included, it does not exist here. meta.totalCount and meta.workspaceSurveyCount count that same readable set, so neither number reveals a restricted survey to someone who cannot see it. The visibility predicate is applied in the query and the cursor, never after the fact: limit keeps its meaning and meta.nextCursor being null remains the only end-of-collection signal.

Session cookie, x-api-key, or a Bearer token.

get/api/v3/surveys

Request

  • Base URL
    https://app.formbricks.com
  • URL
    https://app.formbricks.com/api/v3/surveys
  • 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.

limitinteger

Page size (max 250)

cursorstring

Opaque cursor returned as meta.nextCursor from the previous page. Omit on the first request.

includeTotalCountboolean

Whether to calculate meta.totalCount for this request. Set to false on cursor-pagination follow-up requests to skip the extra count query; in that case meta.totalCount is null.

filter[name][contains]string

Case-insensitive substring match on survey name (same as in-app list filters).

filter[status][in]string[]

Survey status filter. Repeat the parameter (filter[status][in]=draft&filter[status][in]=inProgress) or use comma-separated values (filter[status][in]=draft,inProgress). Invalid values → 400. archived is a pseudo-status: it does not match a real survey status but includes archived (soft-deleted) surveys in the result set. Archived surveys are otherwise excluded from the default list.

filter[type][in]string[]

Survey type filter (link / app). Same repeat-or-comma rules as filter[status][in].

filter[visibility][in]SurveyVisibility[]

Keep only surveys with one of these visibilities, as each item reports it (a survey with a change in flight counts as restricted). Same repeat-or-comma rules as filter[status][in]; unknown values → 400. Filters within the readable set: a workspace member asking for restricted gets their own restricted surveys, an organisation manager gets everyone's.

filter[owner][in]string[]

me keeps surveys whose owner is the caller; others keeps the rest, ownerless surveys included. Relative to the signed-in user, so an API key sending this parameter gets 400.

filter[singleUse][eq]boolean

true keeps only single-use surveys (single-use links turned on), false only the others. Omit it to list both. Applied in the query, so limit and the counts keep their meaning.

filter[pinProtected][eq]boolean

true keeps only surveys that ask for a PIN before they open, false only the others. Omit it to list both. Applied in the query, so limit and the counts keep their meaning.

sortBy'createdAt' | 'updatedAt' | 'name' | 'relevance'

Sort order. Defaults to updatedAt. The cursor token is bound to the selected sort order.

Response

Surveys retrieved successfully

Example response

{
  "data": [
    {
      "access": {
        "via": "workspace"
      }
    }
  ]
}

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

    • info

      added the new optional query request parameter filter[pinProtected][eq]

    • info

      added the new optional query request parameter filter[singleUse][eq]