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

# Ask a question

> Submit a natural-language question to the ClarityQ agent. The request is processed asynchronously; use the returned conversation_id to poll for results. The optional data_partition restricts the analyzed data to a UTC date range, like the date filter in the ClarityQ app; when omitted, the product's configured default date filter is applied (the same default the ClarityQ app uses), or no date filter if the product has no default.



## OpenAPI

````yaml post /api/v1/products/{product_id}/ask
openapi: 3.1.0
info:
  title: ClarityQ API
  description: ClarityQ API, authenticated via API keys.
  version: 1.0.0
servers:
  - url: https://api.clarityq.ai
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/products/{product_id}/ask:
    post:
      tags:
        - API
      summary: Ask a question
      description: >-
        Submit a natural-language question to the ClarityQ agent. The request is
        processed asynchronously; use the returned conversation_id to poll for
        results. The optional data_partition restricts the analyzed data to a
        UTC date range, like the date filter in the ClarityQ app; when omitted,
        the product's configured default date filter is applied (the same
        default the ClarityQ app uses), or no date filter if the product has no
        default.
      operationId: ask_api_v1_products__product_id__ask_post
      parameters:
        - name: product_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Product Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AskRequest:
      properties:
        prompt:
          type: string
          title: Prompt
          description: Question to send to the ClarityQ agent.
        data_partition:
          anyOf:
            - $ref: '#/components/schemas/DataPartition'
            - type: 'null'
          description: >-
            Optional UTC date range restricting the data the agent analyzes,
            equivalent to the date filter in the ClarityQ app. When omitted, the
            product's configured default date filter is applied (the same
            default the ClarityQ app uses); if the product has no default, no
            date filter is applied.
      type: object
      required:
        - prompt
      title: AskRequest
    AskResponse:
      properties:
        status:
          $ref: '#/components/schemas/ConversationStatus'
          description: Current status of the request.
        message:
          type: string
          title: Message
          description: Human-readable status message.
        conversation_id:
          type: string
          title: Conversation Id
          description: Conversation ID for tracking the request.
      type: object
      required:
        - status
        - message
        - conversation_id
      title: AskResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DataPartition:
      properties:
        start:
          type: string
          format: date
          title: Start
          description: First UTC calendar day of data to include (YYYY-MM-DD).
        end:
          type: string
          format: date
          title: End
          description: Last UTC calendar day of data to include, inclusive (YYYY-MM-DD).
      type: object
      required:
        - start
        - end
      title: DataPartition
      description: UTC calendar-day range restricting the data the agent analyzes.
    ConversationStatus:
      type: string
      enum:
        - IN_PROGRESS
        - COMPLETED
        - ERROR
      title: ConversationStatus
      description: Status of a conversation.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from the ClarityQ dashboard.

````