---
title: "POST /v1/ask"
method: POST
path: "/v1/ask"
tags: ["Ask"]
---

# POST /v1/ask

`POST /v1/ask`

## Request

- Base URL: `https://api.originalvoices.ai`
- URL: `https://api.originalvoices.ai/v1/ask`
- Auth: HTTP bearer

Ask a study's participants, a saved audience or an audience described in words up to 15 open and/or choice questions in one call. Each participant's Digital Twin answers them in order in one conversation, so an open question after a choice question can probe the pick; study participants also have their whole study conversation in context. Choice questions return per-option counts and percentages; every answer carries a low/medium/high confidence, and picks carry the model's reason. Replaces POST /v1/ask/open and POST /v1/ask/choices.

## Request body

- object
  - `target` object, required: Who answers: exactly one of studyId, audienceId or audience.
    - `studyId` string, uuid: A study id (GET /v1/studies). Its participants answer with their whole study conversation in context.
    - `audienceId` string: A saved audience UUID (GET /v1/audiences) or a network audience as '{networkId}:{audienceSlug}'.
    - `audience` string: The audience described in words, e.g. "UK, 18-30, fitness enthusiasts". Matching Digital Twins are found across your default networks.
    - `audiencePrompt` string: Deprecated: use audience.
    - `networkId` string: Only with audience: search this one network instead of your default set.
  - `questions` union[], required: Asked in order to every participant, inside one conversation.
    - union
      - object
        - `id` string: Your key for this question in every participant's answers. Defaults to q1, q2, … in request order.
        - `type` 'open', required
        - `question` string, required
        - `media` object[]: Platform keys only for now. Files every participant sees with this question: images, 90-second videos or PDFs. The same file on several questions is shown once.
          - `uri` string, required: A file in the Original Voices media bucket, under your organization.
          - `mediaType` union, required: The file's media type.
            - 'image/png'
            - 'image/jpeg'
            - 'image/webp'
            - 'video/mp4'
            - 'application/pdf'
          - `label` string: How the question refers to it, e.g. "A" or "Pack 2". Shown to the twins.
      - object
        - `id` string: Your key for this question in every participant's answers. Defaults to q1, q2, … in request order.
        - `type` 'choice', required
        - `question` string, required
        - `choices` string[], required
        - `isMultipleChoice` boolean: Allow several picks. Defaults to false.
        - `media` object[]: Platform keys only for now. Files every participant sees with this question: images, 90-second videos or PDFs. The same file on several questions is shown once.
          - `uri` string, required: A file in the Original Voices media bucket, under your organization.
          - `mediaType` union, required: The file's media type.
            - 'image/png'
            - 'image/jpeg'
            - 'image/webp'
            - 'video/mp4'
            - 'application/pdf'
          - `label` string: How the question refers to it, e.g. "A" or "Pack 2". Shown to the twins.
  - `filter` string: Study targets only. Free-text criteria matched against each participant's profile and what they said in the study, e.g. "said price was the main barrier".
  - `twinIds` string[]: Study targets: specific participants (twinIds from GET /v1/studies/{studyId}/participants); combines with filter. Saved-audience UUID targets: member twin ids (at most 100), echoed back as participants' twinId.
  - `sampleSize` integer: How many participants to ask. Defaults: interview studies ask everyone, twin-survey studies 25, saved and network audiences everyone up to 100, described audiences 25. Audiences take at most 100.

## Response `200`

Default Response

- object
  - `requestId` string, required
  - `data` object, required
    - `source` object, required: Who answered: type "study" (with id, title, kind) or "audience" (with id when saved, and the audience description).
      - `type` string, required
      - `id` string, required
      - `title` string
      - `kind` string
      - `description` string
    - `total` integer, required: Participants in the study or audience.
    - `matched` integer, required: Participants matching filter and twinIds (equals total without them).
    - `asked` integer, required: Participants whose answers are returned.
    - `questions` object[], required
      - `id` string, required
      - `type` union, required
        - 'open'
        - 'choice'
      - `question` string, required
      - `choices` string[]
      - `isMultipleChoice` boolean
      - `answered` integer, required: Participants who answered this question.
      - `results` object[]: Choice questions only. count: answering participants who picked the option. percentage: the option's average probability across answering participants (0-100), steadier than counting picks; multiple-choice percentages can sum past 100.
        - `choice` string, required
        - `count` integer, required
        - `percentage` number, required
    - `participants` object[], required
      - `twinId` string, uuid, required
      - `demographics` object, required
        - `age` integer, required
        - `gender` string, required
        - `country` string, required
      - `answers` object, required: Keyed by question id. A missing key means this participant didn't answer that question.
  - `error` unknown, required

## Other responses

- `400`: Invalid request body
- `401`: Unauthorized - Missing or invalid API token
- `402`: Payment Required - Insufficient credits balance
- `403`: Forbidden - Organization lacks required permission
- `500`: Internal server error
- `503`: Service Unavailable - Service configuration issue (e.g. empty public-network registry)

## Changes

- **2026-11-05** `6b5f58588536`: 1 breaking, 1 info
  - removed `subschema #1, subschema #2` from the `questions/items/` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `questions/items/` request property `anyOf` list
- **2026-10-24** `1a67c32785c8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/originalvoices/apis/originalvoices-api/changes/v1/ask/post.md)

---

[API](https://skmtc.dev/originalvoices/apis/originalvoices-api.md) - [All operations](https://skmtc.dev/originalvoices/apis/originalvoices-api/llms.txt) - [OpenAPI document](https://skmtc.dev/originalvoices/apis/originalvoices-api/revisions/6b5f58588536?raw)