> ## 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.

# Sponsored Conversations Analytics

> Advertiser-facing rollup for the campaigns the API key's tenant owns: summary KPIs, daily timeline, plus per-campaign, per-prompt, and click-type breakdowns. Numbers match the Dappier platform 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**. `agent_id` is validated against the key's tenant — an unknown or other-tenant id returns `400 agent_id not found`.
</Warning>

<Warning>
  `creative_id` / `line_item_id` / `publisher_id` reflect **DSP ad-render values** (the creative that matched the campaign and triggered the SC), snapshotted at SC entry and frozen for the SC lifetime. `publisher_id` is **absent on GAM-derived events** (GAM has no per-impression publisher id) — only Dianomi-served events carry it, so filtering by `publisher_id` scopes to Dianomi-derived traffic only. `prompt_breakdown` is grouped by prompt text and includes user-typed follow-ups (`impressions == 0`, `queries > 0`); filter client-side to `impressions > 0` for configured prompts only.
</Warning>


## OpenAPI

````yaml get /v1/analytics/sponsored-conversations
openapi: 3.1.0
info:
  title: Dappier Datamodel API
  version: 0.1.0
servers:
  - url: https://api.dappier.com
security: []
paths:
  /v1/analytics/sponsored-conversations:
    get:
      summary: Get Sponsored Conversations Analytics
      description: >-
        Advertiser-facing rollup for the campaigns the API key's tenant owns:
        summary KPIs, daily timeline, plus per-campaign, per-prompt, and
        click-type breakdowns. Numbers match the Dappier platform dashboard for
        the same filters.
      operationId: get_SponsoredConversations_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: campaign_id
          in: query
          required: false
          description: External campaign id (e.g. `cp_...`).
          schema:
            type: string
            example: cp_xxx
        - name: agent_id
          in: query
          required: false
          description: >-
            AI model external id (e.g. `am_...`). Validated against the tenant —
            an unknown or other-tenant id returns `400 agent_id not found`.
          schema:
            type: string
            example: am_01j06ytn18ejftedz6dyhz2b15
        - name: placement_id
          in: query
          required: false
          description: External placement id.
          schema:
            type: string
        - name: prompt_id
          in: query
          required: false
          description: External prompt id (e.g. `pm_...`).
          schema:
            type: string
        - name: creative_id
          in: query
          required: false
          description: >-
            DSP-served ad creative id (GAM/Dianomi) that triggered the sponsored
            conversation.
          schema:
            type: string
            example: '391487'
        - name: line_item_id
          in: query
          required: false
          description: DSP-served line item id.
          schema:
            type: string
        - name: publisher_id
          in: query
          required: false
          description: >-
            Publisher id. Present on Dianomi-served events only — filtering by
            this scopes results to Dianomi-derived traffic.
          schema:
            type: string
      responses:
        '200':
          description: Sponsored-conversation rollup for the requested window and filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SponsoredConversationsResponse'
        '400':
          description: >-
            Missing or invalid dates, range greater than 365 days, or unknown
            `agent_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:
    SponsoredConversationsResponse:
      type: object
      title: SponsoredConversationsResponse
      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'
            campaign_id:
              type: string
              example: cp_xxx
            agent_id:
              type: string
            placement_id:
              type: string
            prompt_id:
              type: string
            creative_id:
              type: string
            line_item_id:
              type: string
            publisher_id:
              type: string
        summary:
          type: object
          description: >-
            Rollup for the window. Internally self-consistent; percentages
            rounded to 2 decimals.
          properties:
            impressions:
              type: integer
              description: >-
                Times a sponsored prompt was rendered and visible inside a
                publisher's widget.
              example: 36470
            queries:
              type: integer
              description: >-
                User queries inside the sponsored conversation
                (`deployment_type='sponsored_conversation'`).
              example: 7900
            sessions:
              type: integer
              description: Distinct sessions with ≥1 sponsored-conversation query.
              example: 2820
            engagement_rate:
              type: number
              description: >-
                `queries / sessions × 100`. Can exceed 100% (multiple queries
                per session).
              example: 280.14
            avg_session_duration_seconds:
              type: integer
              description: Mean active time per engaged SC session (5s beacon resolution).
              example: 182
            total_clicks:
              type: integer
              description: >-
                All SC clicks (`sponsored_cta_click` +
                `sponsored_answer_click`).
              example: 1282
            article_clicks:
              type: integer
              description: >-
                Subset on a URL inside the AI answer body
                (`sponsored_answer_click`).
              example: 312
            cta_clicks:
              type: integer
              description: Subset on the brand-agent CTA button (`sponsored_cta_click`).
              example: 970
            conversion_rate:
              type: number
              description: '`total_clicks / sessions × 100`.'
              example: 45.46
            avg_queries_per_session:
              type: number
              description: '`queries / sessions`.'
              example: 2.8
        daily_breakdown:
          type: array
          description: Mirrors the dashboard "Performance Timeline".
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                example: '2026-04-29'
              queries:
                type: integer
                example: 248
              engagement_rate:
                type: number
                example: 21.4
              total_clicks:
                type: integer
                example: 31
        campaign_breakdown:
          type: array
          description: >-
            Per-campaign rollup, sorted by impressions desc. `creative_ids` is
            the list of DSP creative IDs configured on the campaign (from
            campaign setup, not per-event data) — use it to cross-reference your
            DSP/ad-server reports.
          items:
            type: object
            properties:
              campaign_id:
                type: string
                example: cp_xxx
              campaign_name:
                type: string
                example: StateFarm Q2
              creative_ids:
                type: array
                items:
                  type: string
                example:
                  - '391487'
                  - '391840'
              impressions:
                type: integer
                example: 12000
              queries:
                type: integer
                example: 2500
              total_clicks:
                type: integer
                example: 320
              engagement_rate:
                type: number
                example: 20.8
        prompt_breakdown:
          type: array
          description: >-
            Top rows by engagement, grouped by prompt text (not prompt id).
            Configured sponsored prompts appear with `impressions > 0`;
            user-typed follow-ups inside the SC appear with `impressions == 0`
            and `queries > 0`. `prompt_id` is currently always `""` (reserved
            for a future release).
          items:
            type: object
            properties:
              prompt_id:
                type: string
                example: ''
              prompt_text:
                type: string
                example: Tell me more about coverage
              impressions:
                type: integer
                example: 8200
              queries:
                type: integer
                example: 1900
              engagement_rate:
                type: number
                example: 23.2
        click_type_breakdown:
          type: array
          description: One entry per click type present.
          items:
            type: object
            properties:
              type:
                type: string
                example: sponsored_cta_click
              count:
                type: integer
                example: 970
        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.

````