Returns the account's survey cycles. Required scope: r_surveys.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
This endpoint uses ther_surveysscope, which must be enabled through the Integrations section found within the Settings menu.
Requires a user token whose member has permission to view survey cycles, or an account token together with the member_id query parameter of such a member (the request is then evaluated with that member's permissions). An account token without member_id gets 403 Account tokens need a member_id for this operation. The account must have the Surveys feature enabled.
Deleted survey cycles are never returned. Members whose survey view permission is granted through a scoped role only see the survey cycles within their scope, plus any survey cycle they participate in.
Results are ordered by creation (ascending id).
Pagination
limit and offset are optional. When both are omitted, every matching survey cycle is returned in a single response. total_count always reflects the total number of matching survey cycles, regardless of limit / offset.
Filtering
Use states[] to restrict the results to one or more states, e.g. ?states[]=active&states[]=closed. Valid values: draft, scheduled, active, closed, archived. When omitted, survey cycles in all of these states are returned.
Results
{
"total_count": 1,
"survey_cycles": [
{
"id": "4d4",
"name": "Q1 Engagement Pulse",
"welcome_message": "<p>Tell us how things are going this quarter.</p>",
"state": "active",
"type": "cycle",
"template_id": "b2f0c1de-5a7e-4c1b-9d2a-0f6c3e8a91d4",
"start_date": "2025-03-01T08:00:00.000Z",
"end_date": "2025-03-15T20:00:00.000Z",
"timezone": "Europe/Athens",
"is_anonymous": true,
"min_responses_required": 3,
"participant_count": 42,
"employee_sharing_type": "all",
"created_at": "2025-02-15T10:00:00.000Z",
"updated_at": "2025-03-01T08:00:00.000Z"
}
]
}| key | type | description |
|---|---|---|
| total_count | integer | Number of survey cycles matching the filters |
| survey_cycles | array | Array of survey cycle objects (see GET /surveys/:id for the survey cycle payload) |
Error responses
| Status | Condition |
|---|---|
| 400 | Invalid query parameters (limit < 1, offset < 0, or an unknown value in states[]) |
| 401 | Missing or invalid token |
| 403 | Missing r_surveys scope, account token without member_id, the Surveys feature is not enabled for the account, or the user lacks permission to view survey cycles |
Error bodies: 401 / 403 responses are plain text holding the reason (e.g. Required scopes missing: ["r_surveys"]). 404 responses are JSON of the form {"message": "..."}. 400 validation errors are JSON keyed by the offending field, e.g. {"limit": {"code": "number.min", "message": "\"limit\" must be greater than or equal to 1"}}.