Skip to main content
GET
/
v1
/
analytics
/
ask-ai
Get Ask AI Analytics
curl --request GET \
  --url https://api.dappier.com/v1/analytics/ask-ai \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "filters": {
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "deployment_type": "brand_agent",
    "widget_id": "wd_92831",
    "placement_id": "<string>",
    "creative_id": "cr_123",
    "line_item_id": "<string>",
    "publisher_id": "<string>"
  },
  "summary": {
    "widget_loads": 124550,
    "viewable_sessions": 38122,
    "viewability_rate": 30.6,
    "engagement_queries": 6421,
    "engagement_rate": 16.8,
    "total_clicks": 2310,
    "article_clicks": 1240,
    "cta_clicks": 1070,
    "sessions": 5120,
    "avg_session_duration_seconds": 142,
    "engagement_session_rate": 13.4,
    "total_session_time_seconds": 727040,
    "query_to_click_rate": 36
  },
  "daily_breakdown": [
    {
      "date": "2026-04-28",
      "widget_loads": 4211,
      "viewable_sessions": 1312,
      "engagement_queries": 248,
      "total_clicks": 94,
      "sessions": 201
    }
  ],
  "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. widget_id is validated against the key’s tenant — an unknown or other-tenant id returns 400 widget_id not found.
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.

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"

​
widget_id
string

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.

Example:

"wd_92831"

​
placement_id
string

External placement id.

​
deployment_type
string

Deployment type, e.g. brand_agent, sponsored_conversation, embed. Omit for all.

Example:

"brand_agent"

​
creative_id
string

Publisher-supplied ad-tracking macro filter (HTML attribute on <dappier-ask-ai-widget>).

​
line_item_id
string

Publisher-supplied ad-tracking macro filter.

​
publisher_id
string

Publisher-supplied ad-tracking macro filter.

Response

Engagement 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

Full 13-metric rollup for the window. The block is internally self-consistent; all percentages are rounded to 2 decimals.

​
daily_breakdown
object[]

Per-day subset for charting, ascending by date.

​
meta
object