Visibility & Mentions

Run a dimensional analytics query for a product

Query one analytics metric (sov, citations, traffic, sentiment) grouped by at most one dimension, scoped by filters and a date window. Returns flat rows plus column metadata for generic rendering.

post/api/v1/analytics/explore

Request

  • Base URL
    https://app.promptingco.com
  • URL
    https://app.promptingco.com/api/v1/analytics/explore
  • Auth
    • API key in header x-api-key
    • or HTTP bearer
    • or API key in cookie better-auth.session_token

Request body

productIdstring required

Product ID to scope the query to.

metric'sov' | 'citations' | 'traffic' | 'sentiment' required

Metric to query. Ungrouped and date-dimension SoV use configurable trailing snapshots rather than additive period totals.

dimensionsstring[]

At most one dimension to group by. Omit or pass [] for a summary. For metric=sov when dimensions are omitted or dimensions=[date] or dimensions=[engine], sov, mentions, and runs are trailing-window snapshot values. granularity selects day, week, or month buckets and rollingWindow counts those buckets; they default to day and 30. Omit dimensions to return the latest product snapshot, use dimensions=[date] for one snapshot per date, or use dimensions=[engine] for the latest snapshot per engine. The window selects eligible snapshot dates; it is not a period aggregation. Custom rolling settings are supported for product, date, and engine SOV series. Do not sum mentions or runs across dated rows because their rolling windows overlap. Capabilities — sov: dimensions [date, prompt, topic, engine, competitor], filters [viewId, promptId, topicId, engine, regionId], sortBy depends on the dimension (prompt, topic, and engine rows sort by sov, mentions, runs, or label; competitor rows sort by sov or mentions, desc only; date and ungrouped results do not sort); citations: dimensions [source, category, type, author, model, date], filters [viewId, topicId, regionId, category, contentType, model, author, searchTerm, productMentioned], sortBy [citations, mentions]; traffic: dimensions [date, page, model, category], filters [trafficType, provider, category]; sentiment: dimensions [prompt], filters [viewId, promptId, topicId].

granularity'day' | 'week' | 'month'

UTC bucket and rollingWindow unit for metric=sov, or time bucket for metric=traffic with dimensions=[date]. Defaults to day.

rollingWindowinteger

Number of granularity buckets in each metric=sov snapshot. Defaults to 30.

compare'wow'

Week-over-week comparison, metric=sentiment only.

pageinteger
pageSizeinteger
sortBystring
sortDirection'asc' | 'desc'

Response

Successful response

oktrue required

Changes

No recorded changes to this operation across all 1 revision of this API.