---
title: "Run a dimensional analytics query for a product"
method: POST
path: "/api/v1/analytics/explore"
tags: ["Visibility & Mentions"]
---

# Run a dimensional analytics query for a product

`POST /api/v1/analytics/explore`

## Request

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

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.

## Request body

- object
  - `productId` string, 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.
  - `dimensions` string[]: 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].
  - `filters` object
    - `viewId` string: Scope to a saved view's prompts (sov, citations, sentiment).
    - `promptId` string: Scope to a single prompt (sov, sentiment). With metric=sov, use dimensions=[date] for the prompt's time series, [engine] for its share of voice per engine, or [competitor] for the ranking within that prompt.
    - `topicId` string: Scope to a single topic/category (sov, citations, sentiment). With metric=sov, use dimensions=[prompt] for each prompt's share of voice within the topic, [competitor] for the industry ranking within the topic, or [date] for the topic's time series.
    - `engine` string: Answer engine filter for sov, e.g. chatgpt or sonar.
    - `regionId` string: Region scope.
    - `category` string: Source category (citations) or page category (traffic).
    - `contentType` string: Citations content type, e.g. article or youtube.
    - `model` string: Citations: answer engine/model that cited the source.
    - `author` string: Citations: author name filter.
    - `searchTerm` string: Citations: case-insensitive URL/title search.
    - `productMentioned` 'mentioned' | 'not_mentioned': Citations: only sources where the product was (not) mentioned.
    - `trafficType` 'ai' | 'human': Traffic: ai (default) or human.
    - `provider` string: Traffic: AI crawler or assistant filter, for example chatgpt.
  - `window` object: Date window; both start and end or neither. Defaults to the last 30 days. Maximum 366 inclusive days. 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.
    - `start` string: ISO date (YYYY-MM-DD).
    - `end` string: ISO date (YYYY-MM-DD).
  - `granularity` 'day' | 'week' | 'month': UTC bucket and rollingWindow unit for metric=sov, or time bucket for metric=traffic with dimensions=[date]. Defaults to day.
  - `rollingWindow` integer: Number of granularity buckets in each metric=sov snapshot. Defaults to 30.
  - `compare` 'wow': Week-over-week comparison, metric=sentiment only.
  - `page` integer
  - `pageSize` integer
  - `sortBy` string
  - `sortDirection` 'asc' | 'desc'

## Response `200`

Successful response

- object
  - `ok` true, required
  - `data` object, required
    - `metric` 'sov' | 'citations' | 'traffic' | 'sentiment', required
    - `dimensions` string[], required
    - `scope` object, required
      - `product` object, required
        - `id` string, required
        - `name` string, required
        - `slug` string, required
    - `window` object, required
      - `start` string, required
      - `end` string, required
    - `granularity` 'day' | 'week' | 'month'
    - `rollingWindow` integer
    - `compare` 'wow'
    - `columns` object[], required
      - `key` string, required
      - `label` string, required
      - `kind` 'dimension' | 'metric', required
      - `type` 'string' | 'number' | 'date', required
    - `rows` object[], required
    - `pagination` object
      - `page` integer, required
      - `pageSize` integer, required
      - `total` integer, required
      - `totalPages` integer, required
    - `totals` object

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Not found
- `422`: Validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api.md) - [All operations](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api/llms.txt) - [OpenAPI document](https://skmtc.dev/promptingcompany/apis/the-prompting-company-api/revisions/c0451ea10e9a?raw)