Skip to main content
GET
/
v1
/
analytics
/
sponsored-conversations
Get Sponsored Conversations Analytics
curl --request GET \
  --url https://api.dappier.com/v1/analytics/sponsored-conversations \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "filters": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "campaign_id": "cp_xxx",
    "agent_id": "<string>",
    "placement_id": "<string>",
    "prompt_id": "<string>",
    "creative_id": "<string>",
    "line_item_id": "<string>",
    "publisher_id": "<string>"
  },
  "summary": {
    "impressions": 36470,
    "queries": 7900,
    "sessions": 2820,
    "engagement_rate": 280.14,
    "avg_session_duration_seconds": 182,
    "total_clicks": 1282,
    "article_clicks": 312,
    "cta_clicks": 970,
    "conversion_rate": 45.46,
    "avg_queries_per_session": 2.8
  },
  "daily_breakdown": [
    {
      "date": "2026-04-29",
      "queries": 248,
      "engagement_rate": 21.4,
      "total_clicks": 31
    }
  ],
  "campaign_breakdown": [
    {
      "campaign_id": "cp_xxx",
      "campaign_name": "StateFarm Q2",
      "creative_ids": [
        "391487",
        "391840"
      ],
      "impressions": 12000,
      "queries": 2500,
      "total_clicks": 320,
      "engagement_rate": 20.8
    }
  ],
  "prompt_breakdown": [
    {
      "prompt_id": "",
      "prompt_text": "Tell me more about coverage",
      "impressions": 8200,
      "queries": 1900,
      "engagement_rate": 23.2
    }
  ],
  "click_type_breakdown": [
    {
      "type": "sponsored_cta_click",
      "count": 970
    }
  ],
  "meta": {
    "timezone": "UTC",
    "generated_at": "2026-05-11T18:45:00Z"
  }
}
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).
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.
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.

Authorizations

​
Authorization
string
header
required

Bearer token authentication using your Dappier API key. Get your API key at https://platform.dappier.com/profile/api-keys.

Query Parameters

​
start_date
string<date>

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

Example:

"2026-04-01"

​
end_date
string<date>

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.

Example:

"2026-04-30"

​
campaign_id
string

External campaign id (e.g. cp_...).

Example:

"cp_xxx"

​
agent_id
string

AI model external id (e.g. am_...). Validated against the tenant — an unknown or other-tenant id returns 400 agent_id not found.

Example:

"am_01j06ytn18ejftedz6dyhz2b15"

​
placement_id
string

External placement id.

​
prompt_id
string

External prompt id (e.g. pm_...).

​
creative_id
string

DSP-served ad creative id (GAM/Dianomi) that triggered the sponsored conversation.

Example:

"391487"

​
line_item_id
string

DSP-served line item id.

​
publisher_id
string

Publisher id. Present on Dianomi-served events only — filtering by this scopes results to Dianomi-derived traffic.

Response

Sponsored-conversation rollup for the requested window and filters.

​
success
boolean

Always true for a 200 response.

Example:

true

​
filters
object

Echoes back only the filters you supplied in the request.

​
summary
object

Rollup for the window. Internally self-consistent; percentages rounded to 2 decimals.

​
daily_breakdown
object[]

Mirrors the dashboard "Performance Timeline".

​
campaign_breakdown
object[]

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.

​
prompt_breakdown
object[]

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

​
click_type_breakdown
object[]

One entry per click type present.

​
meta
object