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

# Ask AI Analytics

> Publisher-facing Ask AI engagement rollup: summary KPIs plus a daily time-series. Numbers match the Dappier platform analytics dashboard for the same filters.

<Info>
  Data is sourced from BigQuery — expect a **5–15 minute lag** for the most recent events. All dates and timestamps are **UTC**. Responses are tenant-scoped to the API key and are rate limited (default **60 requests/minute** per key; `X-RateLimit-*` headers are returned, `429` with `Retry-After` when exceeded) and cached server-side for up to **30 minutes** (send `Cache-Control: no-cache` to skip the cache read; the `X-Cache` response header reports `HIT`, `MISS`, `BYPASS`, or `DISABLED`).
</Info>

<Warning>
  If either `start_date` or `end_date` is omitted, **both** default to the trailing 7-day window ending today UTC. Explicit ranges must be ≤ **365 days**. `widget_id` is validated against the key's tenant — an unknown or other-tenant id returns `400 widget_id not found`.
</Warning>

<Warning>
  `creative_id` / `line_item_id` / `publisher_id` match the publisher-supplied values the widget was loaded with. Once a session enters a sponsored conversation these fields are overridden with the matched DSP ad-render IDs, so filtering by your own publisher macros excludes most sponsored-conversation events. For sponsored conversion data use the Sponsored Conversations Analytics endpoint instead.
</Warning>


## OpenAPI

````yaml get /v1/analytics/ask-ai
openapi: 3.1.0
info:
  title: Dappier Datamodel API
  version: 0.1.0
servers:
  - url: https://api.dappier.com
security: []
paths:
  /v1/analytics/ask-ai:
    get:
      summary: Get Ask AI Analytics
      description: >-
        Publisher-facing Ask AI engagement rollup: summary KPIs plus a daily
        time-series. Numbers match the Dappier platform analytics dashboard for
        the same filters.
      operationId: get_AskAi_analytics
      parameters:
        - name: start_date
          in: query
          required: false
          description: >-
            Inclusive start of the analytics window, formatted `YYYY-MM-DD`
            (UTC). Optional — if either `start_date` or `end_date` is omitted,
            both default to the trailing **7-day window** ending `today_UTC`
            (i.e., `start_date = today_UTC - 6`).
          schema:
            type: string
            format: date
            example: '2026-04-01'
        - name: end_date
          in: query
          required: false
          description: >-
            Inclusive end of the analytics window, formatted `YYYY-MM-DD` (UTC).
            Optional — if either `start_date` or `end_date` is omitted, both
            default to the trailing **7-day window** ending `today_UTC`. Must be
            on or after `start_date`; the total range must be ≤ **365 days**.
          schema:
            type: string
            format: date
            example: '2026-04-30'
        - name: widget_id
          in: query
          required: false
          description: >-
            External widget id (e.g. `wd_...`). Validated against the key's
            tenant — an unknown or other-tenant id returns `400 widget_id not
            found`. Scopes results to that widget's AI agent. Omit for all of
            the tenant's widgets.
          schema:
            type: string
            example: wd_92831
        - name: placement_id
          in: query
          required: false
          description: External placement id.
          schema:
            type: string
        - name: deployment_type
          in: query
          required: false
          description: >-
            Deployment type, e.g. `brand_agent`, `sponsored_conversation`,
            `embed`. Omit for all.
          schema:
            type: string
            example: brand_agent
        - name: creative_id
          in: query
          required: false
          description: >-
            Publisher-supplied ad-tracking macro filter (HTML attribute on
            `<dappier-ask-ai-widget>`).
          schema:
            type: string
        - name: line_item_id
          in: query
          required: false
          description: Publisher-supplied ad-tracking macro filter.
          schema:
            type: string
        - name: publisher_id
          in: query
          required: false
          description: Publisher-supplied ad-tracking macro filter.
          schema:
            type: string
      responses:
        '200':
          description: Engagement rollup for the requested window and filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AskAiAnalyticsResponse'
        '400':
          description: >-
            Missing or invalid dates, range greater than 365 days, or unknown
            `widget_id`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
        '401':
          description: '`Authorization` header missing, or token does not start with `ak_`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
        '403':
          description: API key not found, or key is inactive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsError'
        '429':
          description: Rate limit exceeded. A `Retry-After` header (seconds) is returned.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: rate limit exceeded
        '500':
          description: Internal or BigQuery failure (empty body).
      security:
        - ApiKeyBearer: []
components:
  schemas:
    AskAiAnalyticsResponse:
      type: object
      title: AskAiAnalyticsResponse
      properties:
        success:
          type: boolean
          description: Always `true` for a 200 response.
          example: true
        filters:
          type: object
          description: Echoes back only the filters you supplied in the request.
          properties:
            start_date:
              type: string
              format: date
              example: '2026-04-01'
            end_date:
              type: string
              format: date
              example: '2026-04-30'
            deployment_type:
              type: string
              example: brand_agent
            widget_id:
              type: string
              example: wd_92831
            placement_id:
              type: string
            creative_id:
              type: string
              example: cr_123
            line_item_id:
              type: string
            publisher_id:
              type: string
        summary:
          type: object
          description: >-
            Full 13-metric rollup for the window. The block is internally
            self-consistent; all percentages are rounded to 2 decimals.
          properties:
            widget_loads:
              type: integer
              description: Times the widget script initialized on a page.
              example: 124550
            viewable_sessions:
              type: integer
              description: Sessions where the widget entered the viewport.
              example: 38122
            viewability_rate:
              type: number
              description: '`viewable_sessions / widget_loads * 100`.'
              example: 30.6
            engagement_queries:
              type: integer
              description: >-
                All user-originated queries — free-form, brand-agent, search,
                click-to-brand-agent, sponsored, automated follow-ups.
              example: 6421
            engagement_rate:
              type: number
              description: '`engagement_queries / viewable_sessions * 100`.'
              example: 16.8
            total_clicks:
              type: integer
              description: >-
                Article-body + ad + amplify + brand-agent answer + brand-agent
                CTA clicks.
              example: 2310
            article_clicks:
              type: integer
              description: Subset of `total_clicks` on a URL inside the AI answer body.
              example: 1240
            cta_clicks:
              type: integer
              description: Subset of `total_clicks` on a brand-agent CTA button.
              example: 1070
            sessions:
              type: integer
              description: Unique sessions with ≥1 engagement query.
              example: 5120
            avg_session_duration_seconds:
              type: integer
              description: Mean active time per engaged session (5s beacon resolution).
              example: 142
            engagement_session_rate:
              type: number
              description: '`sessions / viewable_sessions * 100`.'
              example: 13.4
            total_session_time_seconds:
              type: integer
              description: Sum of active time across engaged sessions.
              example: 727040
            query_to_click_rate:
              type: number
              description: '`total_clicks / engagement_queries * 100`.'
              example: 36
        daily_breakdown:
          type: array
          description: Per-day subset for charting, ascending by date.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                example: '2026-04-28'
              widget_loads:
                type: integer
                example: 4211
              viewable_sessions:
                type: integer
                example: 1312
              engagement_queries:
                type: integer
                example: 248
              total_clicks:
                type: integer
                example: 94
              sessions:
                type: integer
                example: 201
        meta:
          type: object
          properties:
            timezone:
              type: string
              example: UTC
            generated_at:
              type: string
              format: date-time
              example: '2026-05-11T18:45:00Z'
    AnalyticsError:
      type: object
      title: AnalyticsError
      properties:
        message:
          type: string
          description: Human-readable error description.
          example: end_date must be on or after start_date
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication using your Dappier API key. Get your API key
        at https://platform.dappier.com/profile/api-keys.

````