List surveys

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

const options = {method: 'GET', headers: {cookie: 'next-auth.session-token='}};

fetch('https://app.formbricks.com/api/v3/surveys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.formbricks.com/api/v3/surveys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_COOKIE => "next-auth.session-token=",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.formbricks.com/api/v3/surveys"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("cookie", "next-auth.session-token=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.formbricks.com/api/v3/surveys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["cookie"] = 'next-auth.session-token='

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "workspaceId": "<string>",
      "type": "link",
      "status": "draft",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "publishOn": "2023-11-07T05:31:56Z",
      "responseCount": 123,
      "completedResponseCount": 123,
      "creator": {
        "name": "<string>"
      },
      "visibility": "restricted",
      "owner": {
        "name": "<string>"
      },
      "access": {
        "via": "workspace",
        "canManageVisibility": true
      }
    }
  ],
  "meta": {
    "limit": 2,
    "nextCursor": "<string>",
    "totalCount": 1,
    "workspaceSurveyCount": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

V3 Surveys

List surveys

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

surveys

List surveys

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

const options = {method: 'GET', headers: {cookie: 'next-auth.session-token='}};

fetch('https://app.formbricks.com/api/v3/surveys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.formbricks.com/api/v3/surveys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_COOKIE => "next-auth.session-token=",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.formbricks.com/api/v3/surveys"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("cookie", "next-auth.session-token=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.formbricks.com/api/v3/surveys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["cookie"] = 'next-auth.session-token='

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "workspaceId": "<string>",
      "type": "link",
      "status": "draft",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "archivedAt": "2023-11-07T05:31:56Z",
      "publishOn": "2023-11-07T05:31:56Z",
      "responseCount": 123,
      "completedResponseCount": 123,
      "creator": {
        "name": "<string>"
      },
      "visibility": "restricted",
      "owner": {
        "name": "<string>"
      },
      "access": {
        "via": "workspace",
        "canManageVisibility": true
      }
    }
  ],
  "meta": {
    "limit": 2,
    "nextCursor": "<string>",
    "totalCount": 1,
    "workspaceSurveyCount": 1
  }
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

{
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "requestId": "<string>",
  "type": "<string>",
  "instance": "<string>",
  "code": "ai_features_not_enabled",
  "details": {},
  "invalid_params": [
    {
      "name": "<string>",
      "reason": "<string>",
      "code": "dangling_reference",
      "identifier": "<string>",
      "referenceType": "block",
      "missingId": "<string>",
      "firstUsedAt": "<string>",
      "conflictsWith": "<string>"
    }
  ]
}

Authorizations

next-auth.session-token

string

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.

limit

integer

default:20

Page size (max 250)

Required range: 1 <= x <= 250

cursor

string

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

includeTotalCount

boolean

default:true

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).

Maximum string length: 512

filter[status][in]

enum<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.

Available options:

draft,

inProgress,

paused,

completed,

archived

filter[type][in]

enum<string>[]

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

Available options:

link,

app

filter[visibility][in]

enum<string>[]

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.

restricted: readable by the owner and the organisation's owners and managers only. The owner's access is conditional on their workspace access, level for level: they read the survey only while they can read the workspace, and edit it only while they can write to it — being the owner grants nothing the workspace does not. workspace: readable by everyone with access to the workspace — today's behaviour.

Available options:

restricted,

workspace

filter[owner][in]

enum<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.

Available options:

me,

others

sortBy

enum<string>

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

Available options:

createdAt,

updatedAt,

name,

relevance

Response

Surveys retrieved successfully

data

object[]

required

Show child attributes

API v3 Documentation (Private Beta)

V3 Surveys

V3 Responses

V3 Workflows

V3 Action Classes

V3 Contact Attribute Keys

V3 Workspaces

V3 Feedback Records

List surveys

Authorizations

Query Parameters

Response