> ## 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/questions — List and Filter Survey Questions

> Retrieve every question stored in your Honestly account, including its translated name, type, answer options, and deleted status. Explains why the same text appears under several IDs. Supports offset pagination.

The `/v1/questions` endpoint returns a paginated list of every question stored in your Honestly account. Use it to look up question IDs, texts, types and answer options before you request scores.

The list is account-wide and is not a picture of your current surveys: it contains more than your active surveys ask, and the same question text can appear under many IDs. Read [What the list contains](/developers/api-reference/questions#what-the-list-contains) and [Question IDs and surveys](/developers/api-reference/questions#question-ids-and-surveys) before you build a data model on top of it.

## Endpoint

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

## Query Parameters

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

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

## Example Request

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

## Example Response

```json theme={null}
{
  "total_count": 2,
  "questions": [
    {
      "id": 23,
      "name": {
        "en": "How satisfied are you with your workplace?",
        "de": "Sind Sie zufrieden mit Ihrem Arbeitsplatz?"
      },
      "type": "ranked_select",
      "is_deleted": false,
      "dimension": "Leadership",
      "answer_options": [
        {
          "id": 12,
          "name": { "en": "Not satisfied at all", "de": "Gar nicht zufrieden" },
          "value": 0,
          "is_maximum": false,
          "is_minimum": true
        },
        {
          "id": 13,
          "name": { "en": "Very satisfied", "de": "Sehr zufrieden" },
          "value": 5,
          "is_maximum": true,
          "is_minimum": false
        }
      ]
    },
    {
      "id": 24,
      "name": {
        "en": "What could we improve about our meetings?",
        "de": "Was können wir an unseren Meetings verbessern?"
      },
      "type": "textfield",
      "is_deleted": true,
      "dimension": null,
      "answer_options": []
    }
  ]
}
```

## Response Fields

<ResponseField name="total_count" type="integer">
  Total number of questions matching the query.
</ResponseField>

<ResponseField name="questions" type="array">
  List of question objects.

  <Expandable title="question object fields">
    <ResponseField name="id" type="integer">
      Unique identifier for the question. An ID belongs to exactly one questionnaire, so the same question text can appear under several IDs — see [Question IDs and surveys](/developers/api-reference/questions#question-ids-and-surveys).
    </ResponseField>

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

    <ResponseField name="type" type="string">
      The question type. One of `stars`, `textfield`, `single_select`, `multiple_select`, `ranked_select`, `smiley_faces`, or `nps`. Use the type to determine how to calculate a score.
    </ResponseField>

    <ResponseField name="is_deleted" type="boolean">
      `true` if the question has been deleted from its questionnaire. Deleted questions stay in the list, so filter on this field if you only want questions that are still asked.
    </ResponseField>

    <ResponseField name="dimension" type="string | null">
      Planned for v1.4.0. Title of the dimension this question belongs to, for example `"Leadership"`. `null` when the question is not mapped to a dimension.

      A question belongs to at most one dimension, so this is a plain string rather than an object or a list. Group questions by matching on this value.
    </ResponseField>

    <ResponseField name="answer_options" type="array">
      Always present. For question types with a fixed set of options (`single_select`, `multiple_select`, `ranked_select`, `smiley_faces`, `nps`, `stars`) it lists every possible option; for free-text questions (`textfield`) it is an empty array.

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

        <ResponseField name="name" type="object">
          The translated option label, keyed by ISO 639-1 language code.
        </ResponseField>

        <ResponseField name="value" type="number">
          Numeric value that can be used to calculate a score.
        </ResponseField>

        <ResponseField name="is_maximum" type="boolean">
          `true` when this option is the best possible answer in the ordered set.
        </ResponseField>

        <ResponseField name="is_minimum" type="boolean">
          `true` when this option is the worst possible answer in the ordered set.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

<Warning>
  The `dimension` field is **planned for v1.4.0** and is not yet returned by `api.honestly.com`. It is documented here so you can plan your integration. Watch [Versioning](/developers/concepts/versioning) for the release.
</Warning>

<Tip>
  To score a whole dimension, collect the IDs of every question whose `dimension` matches that title and pass them together as `question_ids` to [`/v1/scores`](/developers/api-reference/scores) — the endpoint aggregates them into one score.
</Tip>

## What the list contains

The list covers every questionnaire in your account, not just the surveys you are running today. Besides the questions of your active surveys it includes:

* questions from **archived surveys**
* **deleted questions**, marked with `is_deleted: true`
* questions from **questionnaires that no survey uses any more**
* questions from **360° feedback** questionnaires, whose surveys [`/v1/surveys`](/developers/api-reference/surveys) does not return

If you want to rebuild the structure of one particular survey, expect `/v1/questions` to return more than that survey asks.

## Question IDs and surveys

### Why the same text appears under several IDs

Every question ID belongs to exactly one questionnaire. How a survey gets its questionnaire decides whether it shares IDs with other surveys:

* A survey created **from a template** (for example the Pulse Survey) or **from scratch** gets its own new questionnaire. All of its questions receive new IDs, even when their text is identical to a question in another survey.
* A survey created with **Reuse existing** shares the questionnaire of the survey it was based on, and therefore uses the same question IDs.

Both cases usually occur in the same account. An account that created 30 surveys from the same template therefore returns each template question 30 times, each time with a different `id`. This is expected, not duplicated data.

<Warning>
  Question IDs are not stable across surveys. Do not treat an `id` as the key for "the same question" over time or across surveys. To group questions that ask the same thing, match on the question text in `name`, or on `dimension` once it is available.
</Warning>

### Mapping a question to its survey

The Export API currently has no field that links a question to a survey: the question object carries no survey reference, and [`/v1/surveys`](/developers/api-reference/surveys) does not list a survey's questions. You cannot tell from these two endpoints which survey a question ID belongs to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.