---
title: "List Questions"
method: GET
path: "/voice/questions"
tags: ["Voice Agent Questions"]
---

# List Questions

`GET /voice/questions`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/voice/questions`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

### List Questions

Lists the questions configured on one agent, in the order the agent asks them. Requires agentId -- returns 404 if that agent does not exist or does not belong to your company.

These are agent-level instances of a template (see Question Templates below); each carries its own required/attempts/no-response settings and, optionally, a mappedFieldId that writes the caller's answer onto a company Field after the call ends.

## Query parameters

- `agentId` string, required
- `enabledOnly` boolean

## Response `200`

OK

- object
  - `status` 'success'
  - `data` object
    - `fields` object[]
      - `_id` string: MongoDB document id, included because every document has one; use fieldId to identify it.
      - `fieldId` string: Server-generated UUID. Immutable -- sent in the body on create or update is silently dropped.
      - `companyId` string: Stamped from the caller's authenticated company. Sent in the body is silently dropped.
      - `userId` string: Id of the user who created this question. Sent in the body is silently dropped.
      - `agentId` string: Required on create. Immutable after create -- sent on update is silently dropped.
      - `templateId` string: Required on create. The question template this question is based on. Immutable after create -- sent on update is silently dropped.
      - `customConfig` object: Agent-level override of the template's defaultConfig. Only the keys you send are overridden; the rest fall back to the template.
        - `displayLabel` string
        - `question` string: The prompt text the agent speaks to ask this question. Renamed from promptText.
        - `confirmationText` string
        - `validationPrompt` string
        - `validation` object
          - `pattern` string
          - `minLength` number
          - `maxLength` number
          - `min` number
          - `max` number
          - `allowedValues` string[]
      - `required` boolean: Defaults to false. Agent must collect this before ending the conversation.
      - `maxPromptAttempts` number: Defaults to 2. Hard maximum of 3. Joi validates this as Joi.number().integer(), which this spec generator reports as "number".
      - `noResponseBehavior` 'move_to_next_question' | 'end_conversation': Defaults to move_to_next_question.
      - `triggerCondition` string
      - `order` number: Defaults to 0. Use PUT /voice/questions/reorder to reorder in bulk.
      - `enabled` boolean: Defaults to true.
      - `mappedFieldId` string, nullable: Id of a general company Field (see the Fields API) this question's collected answer is written onto after each call ends. Send null or an empty string to clear the mapping.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
    - `total` integer

## Other responses

- `404`: Agent not found

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)