> ## Documentation Index
> Fetch the complete documentation index at: https://help.honestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/surveys — List and Filter Surveys by Status

> Retrieve a paginated list of surveys from your Honestly account. Filter by creation date and archived status, and use total_count to paginate through all results.

The `/v1/surveys` endpoint returns a paginated list of all surveys in your Honestly account, including their schedule, status, permissions, and custom properties.

## Endpoint

```
GET https://api.honestly.com/v1/surveys
```

## Query Parameters

<ParamField query="limit" type="integer">
  Maximum number of surveys to return per page. Accepts values from `0` to `1000`. Defaults to `100`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of surveys to skip before returning results. Defaults to `0`.
</ParamField>

<ParamField query="created_after" type="string">
  RFC 3339 datetime. Return only surveys created at or after this date. URL-encode the value when passing it as a query parameter.
</ParamField>

<ParamField query="is_archived" type="boolean">
  Filter surveys by archived status. Set to `true` to return only archived surveys, or `false` to return only non-archived surveys. Omit this parameter to return all surveys regardless of archived status.
</ParamField>

## Example Request

```bash theme={null}
curl -X GET "https://api.honestly.com/v1/surveys?limit=100&offset=0" \
  -H "X-Api-Key: YOUR_SECRET_API_KEY"
```

## Example Response

```json theme={null}
{
  "total_count": 2,
  "surveys": [
    {
      "id": 23,
      "import_id": null,
      "name": {
        "en": "Q4 Employee Engagement",
        "de": "Q4 Mitarbeiterbefragung"
      },
      "frequency": "monthly",
      "created_at": "2024-01-01T09:00:00Z",
      "start_at": "2024-01-01T09:00:00Z",
      "end_at": null,
      "archived_at": null,
      "current_survey_ends_at": "2024-01-22T23:59:59Z",
      "next_survey_starts_at": "2024-01-15T09:00:00Z",
      "is_archived": false,
      "is_deactivated": false,
      "permissions": {
        "employees_with_access_to_results": [1, 12, 33]
      },
      "survey_properties": [
        {
          "id": 5,
          "name": "Type",
          "survey_property_options": [
            { "id": 9, "name": "Pulse surveys" }
          ]
        }
      ]
    },
    {
      "id": 24,
      "import_id": "x23344b",
      "name": {
        "en": "Onboarding Pulse",
        "de": "Onboarding Puls"
      },
      "frequency": "once",
      "created_at": "2023-09-10T08:00:00Z",
      "start_at": "2023-09-11T08:00:00Z",
      "end_at": "2023-10-11T08:00:00Z",
      "archived_at": "2023-11-01T08:00:00Z",
      "current_survey_ends_at": null,
      "next_survey_starts_at": null,
      "is_archived": true,
      "is_deactivated": false,
      "permissions": {
        "employees_with_access_to_results": []
      },
      "survey_properties": []
    }
  ]
}
```

## Response Fields

<ResponseField name="total_count" type="integer">
  Total number of surveys matching the query. Use this value to calculate how many pages to fetch when paginating.
</ResponseField>

<ResponseField name="surveys" type="array">
  List of survey objects.

  <Expandable title="survey object fields">
    <ResponseField name="id" type="integer">
      Unique identifier for the survey.
    </ResponseField>

    <ResponseField name="import_id" type="string | null">
      The identifier assigned when the survey was created through the Honestly Import API. `null` when the survey was created in the web application.
    </ResponseField>

    <ResponseField name="name" type="object">
      The translated survey name, keyed by ISO 639-1 language code (e.g. `{ "en": "…", "de": "…" }`).
    </ResponseField>

    <ResponseField name="frequency" type="string">
      How often an employee can participate in this survey. One of `weekly`, `biweekly`, `monthly`, or `once`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      RFC 3339 datetime the survey was created.
    </ResponseField>

    <ResponseField name="start_at" type="string | null">
      RFC 3339 datetime of the survey start. `null` when the survey started on its `created_at` date.
    </ResponseField>

    <ResponseField name="end_at" type="string | null">
      RFC 3339 datetime of the survey end. `null` when no end date is defined.
    </ResponseField>

    <ResponseField name="archived_at" type="string | null">
      RFC 3339 datetime the survey was archived. `null` when the survey was never archived.
    </ResponseField>

    <ResponseField name="current_survey_ends_at" type="string | null">
      RFC 3339 datetime when the current survey participation period ends. `null` if the survey is closed or the current period is not yet open.
    </ResponseField>

    <ResponseField name="next_survey_starts_at" type="string | null">
      RFC 3339 datetime when the survey opens next. `null` if the survey is closed.
    </ResponseField>

    <ResponseField name="is_archived" type="boolean">
      Whether the survey has been archived.
    </ResponseField>

    <ResponseField name="is_deactivated" type="boolean">
      Whether the survey has been deactivated. Deactivated surveys are no longer sent to employees.
    </ResponseField>

    <ResponseField name="permissions" type="object">
      Access control for the survey results.

      <Expandable title="permissions fields">
        <ResponseField name="employees_with_access_to_results" type="array of integers">
          The employee IDs that have access to this survey's results.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="survey_properties" type="array">
      Customer-defined properties used to segment surveys.

      <Expandable title="survey property fields">
        <ResponseField name="id" type="integer">
          Unique identifier for the property.
        </ResponseField>

        <ResponseField name="name" type="string">
          The property name.
        </ResponseField>

        <ResponseField name="survey_property_options" type="array">
          The available options for this property, each with an `id` (integer) and `name` (string).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The `frequency` field uses an extensible enum — new values may be added as Honestly introduces new functionality. Make sure your code handles unknown values gracefully.
</Note>

<Tip>
  Use `total_count` to calculate how many pages to fetch. See [Pagination](/developers/concepts/pagination) for a complete walkthrough.
</Tip>