GET /v1/survey_cycles — List the Cycles of a Recurring Survey

Planned for Export API v1.4.0 — not yet available on api.honestly.com. Documented here so you can plan your integration. Watch Versioning for the release.

A recurring survey runs in cycles — each cycle opens, collects responses, and closes. This endpoint lists those cycles with their exact boundaries, so you can align an export to the periods your survey actually ran in rather than to arbitrary calendar dates. This is what makes a like-for-like period comparison possible: pass one cycle’s boundaries to /v1/scores, then the previous cycle’s.

Endpoint

GET https://api.honestly.com/v1/survey_cycles

Query Parameters

integer

Return only cycles of this survey. Survey IDs come from /v1/surveys. Omit to list cycles of every survey in the account.

integer

Maximum number of cycles to return per page. Accepts values from 0 to 1000. Defaults to 100.

integer

Number of cycles to skip before returning results. Defaults to 0.

Example Request

curl -G "https://api.honestly.com/v1/survey_cycles" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY" \
  --data-urlencode "survey_id=17"

Example Response

{
  "total_count": 4,
  "cycles": [
    {
      "id": "9f1c8a52-2b7d-4f3e-9d21-0c5a7e4b1f88",
      "survey_id": 17,
      "opened_at": "2026-04-01T06:00:00Z",
      "closed_at": null,
      "timezone": "Europe/Berlin"
    },
    {
      "id": "7b3a1e04-6c92-4a1b-8f75-3d2e9a6c04b1",
      "survey_id": 17,
      "opened_at": "2026-01-01T06:00:00Z",
      "closed_at": "2026-01-14T21:59:59Z",
      "timezone": "Europe/Berlin"
    }
  ]
}

Response Fields

integer

Total number of cycles matching the filter, for pagination.

array

Show cycle

string

Cycle UUID. Pass it as survey_cycle_ids to /v1/text_responses to export one cycle’s free-text answers. It also identifies the cycle in the participation breakdown returned by /v1/scores.

integer

ID of the survey this cycle belongs to, matching /v1/surveys.

string

RFC 3339 datetime in UTC when the cycle opened.

string | null

RFC 3339 datetime in UTC when the cycle closed. null means the cycle is still open.

string

The survey’s configured timezone, for rendering local dates. Timestamps themselves are always UTC.

Cycles are returned newest first.

Comparing a score to the previous period

Read the cycles, then call /v1/scores once per cycle using its boundaries:

# current cycle
curl -G "https://api.honestly.com/v1/scores" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY" \
  --data-urlencode "question_ids=121" \
  --data-urlencode "survey_ids=17" \
  --data-urlencode "period_from=2026-04-01T06:00:00Z" \
  --data-urlencode "period_to=2026-04-14T21:59:59Z"

# previous cycle
curl -G "https://api.honestly.com/v1/scores" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY" \
  --data-urlencode "question_ids=121" \
  --data-urlencode "survey_ids=17" \
  --data-urlencode "period_from=2026-01-01T06:00:00Z" \
  --data-urlencode "period_to=2026-01-14T21:59:59Z"

There is no built-in comparison endpoint, because “previous period” means different things in different reports — the previous cycle, the same quarter a year earlier, a fixed baseline. Two calls cost one extra round trip and let you compare anything to anything.Each call is anonymity-checked independently, so a comparison can legitimately return a number for one period and a suppressed value for the other.

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Comparing a score to the previous period

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

Comparing a score to the previous period