Returns a single survey cycle by id. 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.
The id is the survey cycle key returned by the list endpoint. Deleted survey cycles return 404. Members whose survey view permission is granted through a scoped role receive 404 for survey cycles outside their scope (unless they participate in the survey).
Results
{
"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 |
|---|---|---|
| id | string | Survey cycle key |
| name | string | Name of the survey |
| welcome_message | string | null | Welcome message shown to participants (HTML) |
| state | string | Survey state. One of: draft, scheduled, active, closed, archived |
| type | string | null | How the survey is distributed. cycle for a survey sent to participants on a date-based schedule, workflow_task for a survey sent as a task of a workflow |
| template_id | string | null | Id of the survey master template the questionnaire is based on (see GET /surveys/templates/:id) |
| start_date | string | null | ISO 8601 timestamp the survey starts (or started) |
| end_date | string | null | ISO 8601 timestamp the survey ends (or ended) |
| timezone | string | null | IANA timezone the survey dates are scheduled in |
| is_anonymous | boolean | Whether responses are anonymous. For anonymous surveys the answers endpoint never exposes participant identity |
| min_responses_required | integer | Minimum number of submitted responses required before results of an anonymous survey are revealed. 0 means no threshold |
| participant_count | integer | Number of participants assigned to the survey |
| employee_sharing_type | string | null | Who the survey is shared with. One of: all, selected, custom |
| created_at | string | ISO 8601 timestamp of creation |
| updated_at | string | ISO 8601 timestamp of the last update |
Error responses
| Status | Condition |
|---|---|
| 400 | id is not a valid survey cycle key |
| 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 |
| 404 | No survey cycle with the supplied id exists in the account, it is deleted, or it is outside the member's scope |
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"}}.