Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the
UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns.
Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope;
filtering to any other platform correctly returns no rows.
Example: “Which advertisers bid against my brand, by topic?”
date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date
website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard’s Advertisers page (default otherwise is SELF)
product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT)
ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard
share_of_ad_placements = this advertiser’s placements / all tracked advertisers’ placements, the definition behind the Ads dashboard KPI card. The dashboard’s Advertisers table labels ad_placements / ad_answers as “share of ad placements”; that column is ad_visibility here
ad_placements counts distinct answers in which the entity’s ad appeared, not individual placements
avg_quoted_price also returns avg_quoted_price_currency
has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here.
platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform).
Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type.
Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range.
Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.
Filter values:markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id.
Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting.
Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters).
Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.
Unique identifier of the project to query. Get valid project IDs from get_all_projects.
Minimum string length: 1
Example:
"550e8400-e29b-41d4-a716-446655440000"
dimensions
enum<string>[]
required
Dimensions to group ad data by. At least one dimension is required.
Minimum array length: 1
Dimensions to group report data by. Each report accepts a subset; unsupported dimensions are rejected with 400.
topic: Group by topic/category
tag: Group by tag
market: Group by market/region
model: Group by AI model (e.g. ChatGPT, Perplexity)
query: Group by individual query/prompt
date: Group by date (requires date_aggregation_interval)
website: Group by tracked website
shopping: Group by whether the response has a shopping card (true/false)
ads: Group by whether the response has sponsored/ad placements (true/false)
branded: Group by whether the underlying query is branded (true/false)
persona: Group by the persona prompt target attached to the query
intent_stage: Group by the intent-stage prompt target attached to the query
locality: Group by the locality prompt target attached to the query
search_intent: Group by the query's dominant search intent (transactional, navigational, informational, commercial)
domain: Group by cited domain (citations report only)
page: Group by cited page URL (citations report only)
source_type: Group by cited source type: owned, competitor, social_forums, third_party (citations report only)
theme: Group by sentiment theme (sentiments report only)
subtheme: Group by sentiment subtheme (sentiments report only)
keyword: Group by sentiment keyword (sentiments report only)
product: Group by shopping product / ad creative (shopping and ads reports only)
merchant: Group by the merchant offering a purchase link (shopping report only)
advertiser: Group by the advertiser that placed the ad (ads report only)
placement_type: Group by placement type (e.g. SHOPPING_CARD, AD_TEXT)
Available options:
topic,
tag,
market,
model,
query,
date,
website,
shopping,
ads,
branded,
persona,
intent_stage,
locality,
search_intent,
domain,
page,
source_type,
theme,
subtheme,
keyword,
product,
merchant,
advertiser,
placement_type
Examples:
["website"]
["advertiser"]
["topic", "date"]
start_date
string<date-time>
Start of the date range (ISO 8601). Limits results to data collected on or after this date. When omitted: defaults to the latest run's start date for metric queries, or earliest available date for list queries.
Examples:
"2026-01-01T00:00:00Z"
"2026-03-01T00:00:00Z"
end_date
string<date-time>
End of the date range (ISO 8601). Limits results to data collected on or before this date. When omitted: defaults to today. Date-only strings (no 'T') are extended to end of day.
Examples:
"2026-01-31T23:59:59Z"
"2026-03-17T23:59:59Z"
current_from
string<date-time>
Alias for start_date (analytics-tool date naming).
current_to
string<date-time>
Alias for end_date (analytics-tool date naming).
comparison_start_date
string<date-time>
Start of the comparison (past) date range (ISO 8601). Provide together with comparison_end_date to additionally compute every measure over this past range — each row then includes previous_ values calculated with identical dimensions, measures, and filters.
Example:
"2026-07-25T00:00:00Z"
comparison_end_date
string<date-time>
End of the comparison (past) date range (ISO 8601). Required together with comparison_start_date. Date-only strings (no 'T') are extended to end of day, same as end_date.
Example:
"2026-07-31T23:59:59Z"
previous_from
string<date-time>
Alias for comparison_start_date (analytics-tool date naming).
previous_to
string<date-time>
Alias for comparison_end_date (analytics-tool date naming).
order_by
SortingOrder · object[]
Sort results by one or more fields. Each entry specifies a field name and direction. Results are sorted by the first entry, then ties broken by subsequent entries.
Control result pagination. Set limit for page size and offset to skip results. Omit to return all results (use with caution on large datasets).
Show child attributes
Examples:
{ "limit": 10, "offset": 0 }
{ "limit": 25, "offset": 50 }
measures
enum<string>[]
Ad metrics to include. If empty, all measures are returned.
Ad metrics to include in the report.
ad_visibility: Percentage of ad-bearing answers featuring this entity (0-100)
share_of_ad_placements: This entity's placements as a percentage of all tracked-brand ad placements in the group (0-100)
ad_placements: Number of distinct answers in which this entity's ad appeared
ad_answers: Total answers in the group containing at least one ad placement (the ad_visibility denominator)
placements_with_self_brand: Ad placements promoting your own brand's product
unique_advertisers: Number of distinct advertisers
unique_ad_creatives: Number of distinct ad creatives (product cards and text ads)
ad_rank: Average position of the ad within the answer (lower is better)
avg_quoted_price: Average quoted price across ad purchase links; also returns avg_quoted_price_currency
Available options:
ad_visibility,
share_of_ad_placements,
ad_placements,
ad_answers,
placements_with_self_brand,
unique_advertisers,
unique_ad_creatives,
ad_rank,
avg_quoted_price
Example:
["ad_visibility", "share_of_ad_placements"]
filters
AdsFiltersInput · object
Narrow results by topics, markets, advertisers, placement type, etc. All filters combine with AND logic.
Show child attributes
date_aggregation_interval
enum<string>
Optional. When using the 'date' dimension, controls time-series bucket size. Defaults to 'day'.
Available options:
day,
week,
month
Examples:
"week"
"month"
website_type
enum<string>
Scope results by brand ownership. 'SELF' = your brand only, 'SELF+COMPETITORS' = plus competitors, 'ALL' = including untracked third-party brands.
Available options:
SELF,
SELF+COMPETITORS,
ALL
Example:
"SELF+COMPETITORS"
Response
Successful Response
Response containing ads report data.
info
ResponseInfo · object
Information of the API request including total count and query details
Show child attributes
data
AdsDataRow · object[]
Array of ad data rows grouped by the requested dimensions
Show child attributes
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"Writesonic Docs","description":"Writesonic is the GEO platform that tracks your AI visibility across ChatGPT, Gemini, Claude, and 10+ AI search platforms. Diagnose gaps. Own the answer.","colors":{"primary":"#FF6719","light":"#FF8337","dark":"#FF6719"},"logo":{"light":"https://mintcdn.com/writesonic/pJXgH59hJ3fQBw5s/images/logo/logo-light.svg?fit=max\u0026auto=format\u0026n=pJXgH59hJ3fQBw5s\u0026q=85\u0026s=12c1c23ddbb7e4ef1e6a1243503b4114","dark":"https://mintcdn.com/writesonic/pJXgH59hJ3fQBw5s/images/logo/logo-dark.svg?fit=max\u0026auto=format\u0026n=pJXgH59hJ3fQBw5s\u0026q=85\u0026s=b9f811e9c053d5c965eec5f00369524e","href":"https://docs.writesonic.com"},"favicon":"https://mintcdn.com/writesonic/yGK8Y6Gb_2rbk4m6/favicon.png?fit=max\u0026auto=format\u0026n=yGK8Y6Gb_2rbk4m6\u0026q=85\u0026s=cd8c2523e8e57796f14c675f6cc95986","background":{"color":{"light":"#F5F4F0","dark":"#202020"}},"navbar":{"primary":{"type":"button","label":"Open Writesonic","href":"https://app.writesonic.com/?utm_source=docs"}},"footer":{"socials":{"x":"https://x.com/writesonic","linkedin":"https://www.linkedin.com/company/writesonic","github":"https://github.com/Writesonic"},"links":[{"header":"Product","items":[{"label":"Platform","href":"https://writesonic.com"},{"label":"Pricing","href":"https://writesonic.com/pricing"},{"label":"Customers","href":"https://writesonic.com/customers"}]},{"header":"Resources","items":[{"label":"Docs","href":"https://docs.writesonic.com"},{"label":"API","href":"https://docs.writesonic.com/api-reference/authentication"},{"label":"MCP","href":"https://docs.writesonic.com/mcp/mcp-server"}]}]},"fonts":{"heading":{"family":"Roobert","weight":600,"source":"fonts/Roobert-SemiBold.woff2","format":"woff2"},"body":{"family":"Roobert","weight":400,"source":"fonts/Roobert-Regular.woff2","format":"woff2"}},"styling":{"eyebrows":"section","codeblocks":"system","latex":false},"navigation":{"global":{"anchors":[{"anchor":"Open Writesonic","icon":"arrow-up-right-from-square","href":"https://app.writesonic.com/?utm_source=docs"},{"anchor":"Book a demo","icon":"headset","href":"https://writesonic.com/?demo=open"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"writesonic","hasAudioNarration":false,"actualSubdomain":"writesonic","customDomains":["apidocs.writesonic.com"],"gitSource":{"type":"github","owner":"writesonic","repo":"mintlify-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6aff1f751c16aa85135f7454","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Platform","count":54},{"language":"default","tag":"Agents","count":34},{"language":"default","tag":"Agents REST API","count":21},{"language":"default","tag":"Writesonic REST API","count":16},{"language":"default","tag":"AI Bot (Traffic) Analytics","count":12},{"language":"default","tag":"Generic","count":10},{"language":"default","tag":"Reference","count":9},{"language":"default","tag":"Context","count":8},{"language":"default","tag":"Playbooks","count":8},{"language":"default","tag":"Setup and Implementation Guide","count":8}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"custom.css","content":"@font-face{font-family:\"Roobert\";font-weight:400;font-style:normal;font-display:swap;src:url(\"/fonts/Roobert-Regular.woff2\") format(\"woff2\"),\n url(\"/fonts/Roobert-Regular.woff\") format(\"woff\")}@font-face{font-family:\"Roobert\";font-weight:500;font-style:normal;font-display:swap;src:url(\"/fonts/Roobert-Medium.woff2\") format(\"woff2\"),\n url(\"/fonts/Roobert-Medium.woff\") format(\"woff\")}@font-face{font-family:\"Roobert\";font-weight:600;font-style:normal;font-display:swap;src:url(\"/fonts/Roobert-SemiBold.woff2\") format(\"woff2\"),\n url(\"/fonts/Roobert-SemiBold.woff\") format(\"woff\")}@font-face{font-family:\"Roobert\";font-weight:700;font-style:normal;font-display:swap;src:url(\"/fonts/Roobert-Bold.woff2\") format(\"woff2\"),\n url(\"/fonts/Roobert-Bold.woff\") format(\"woff\")}:root{--ws-paper-white: #ffffff;--ws-light-cream: #f5f4f0;--ws-sonic-orange: #ff6719;--ws-ink-black: #202020;--ws-orange-50: #fff6ed;--ws-orange-100: #ffead4;--ws-orange-200: #ffd1a8;--ws-orange-300: #ffa46c;--ws-orange-400: #ff8337;--ws-orange-500: #ff6719;--ws-orange-600: #fd4606;--ws-orange-700: #c73107;--ws-orange-800: #9e280e;--ws-orange-900: #7f240f;--ws-orange-950: #450e05;--ws-cream-100: #eeede6;--ws-cream-200: #dcd9cc;--ws-fg-muted: #5c5c5c;--ws-fg-subtle: #8a8a86;--ws-border: rgba(32, 32, 32, 0.1);--ws-border-strong: rgba(32, 32, 32, 0.22);--ws-font:\n \"Roobert\", \"Inter\", system-ui, -apple-system, \"Segoe UI\", sans-serif;--ws-font-mono: \"JetBrains Mono\", ui-monospace, \"SF Mono\", Menlo, monospace}html,body,[class*=\"font-sans\"],[class*=\"font-display\"],.prose,.prose *{font-family:var(--ws-font)!important}code,kbd,pre,[class*=\"font-mono\"],.prose code,.prose pre{font-family:var(--ws-font-mono)!important}h1,h2,h3,h4,h5,h6,.prose h1,.prose h2,.prose h3,.prose h4,.prose h5,.prose h6{font-family:var(--ws-font)!important;font-weight:600!important;letter-spacing:-0.015em;color:var(--ws-ink-black)}.prose h1,article h1{font-size:30px;line-height:36px;letter-spacing:-0.025em}.prose h2,article h2{font-size:22px;line-height:30px;letter-spacing:-0.02em}.prose h3,article h3{font-size:18px;line-height:26px;letter-spacing:-0.015em}.prose h4,article h4,.prose h5,article h5{font-size:16px}.prose strong{font-weight:600}.dark h1,.dark h2,.dark h3,.dark h4,.dark h5,.dark h6,.dark .prose h1,.dark .prose h2,.dark .prose h3,.dark .prose h4,.dark .prose h5,.dark .prose h6{color:var(--ws-light-cream)}h1,.prose h1{letter-spacing:-0.02em}body{font-weight:400;-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}::selection{background:var(--ws-orange-200);color:var(--ws-orange-950)}.prose a,a[class*=\"text-primary\"]{color:var(--ws-sonic-orange)!important;text-decoration:none;text-underline-offset:3px;transition:color 200ms cubic-bezier(0.2, 0.7, 0.2, 1)}.prose a:hover{color:var(--ws-orange-700)!important;text-decoration:underline}.prose :not(pre)>code{background:var(--ws-orange-50)!important;color:var(--ws-orange-800)!important;border-radius:6px;padding:2px 4px;font-size:0.92em;border:1px solid var(--ws-orange-100)}.dark .prose :not(pre)>code{background:rgba(255, 103, 25, 0.12)!important;color:var(--ws-orange-300)!important;border-color:rgba(255, 103, 25, 0.22)}a[class*=\"bg-primary\"],button[class*=\"bg-primary\"],.button-primary,[data-mintlify-primary]{background-color:#ff6719!important;color:#ffffff!important;border:1px solid #ff6719!important;border-radius:12px!important;font-weight:700!important;letter-spacing:0!important;transition:background-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1),\n border-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1)!important}a[class*=\"bg-primary\"]:hover,button[class*=\"bg-primary\"]:hover{background-color:#f04506!important;border-color:#f04506!important}a[class*=\"bg-primary\"]:active,button[class*=\"bg-primary\"]:active{background-color:#c73107!important;border-color:#c73107!important}.docs-hero-cta-primary{border:1px solid #ff6719;font-weight:700!important;border-radius:12px!important;padding:10px 22px!important;transition:background-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1),\n border-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1)!important}.docs-hero-cta-primary:hover{background-color:#f04506!important;border-color:#f04506!important;color:#ffffff!important}.docs-hero-cta-ghost{background:#ffffff!important;border:1px solid #d1d1d1!important;font-weight:700!important;border-radius:12px!important;padding:10px 22px!important;transition:background-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1),\n border-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1),\n color 200ms cubic-bezier(0.2, 0.7, 0.2, 1)!important}.docs-hero-cta-ghost:hover{background:#ff6719!important;border-color:#ff6719!important;color:#ffffff!important}.dark .docs-hero-cta-ghost{background:rgba(255, 255, 255, 0.05)!important;border-color:rgba(245, 244, 240, 0.18)!important;color:#f5f4f0!important}.dark .docs-hero-cta-ghost:hover{background:#ff6719!important;border-color:#ff6719!important;color:#ffffff!important}a.group[class*=\"bg-primary\"]{background-color:var(--ws-orange-50)!important;color:var(--ws-orange-800)!important;border-radius:8px}a.group[class*=\"bg-primary\"] *{color:var(--ws-orange-800)!important}.dark a.group[class*=\"bg-primary\"],a.group[class*=\"dark:bg-primary\"]{background-color:rgba(255, 103, 25, 0.14)!important;color:var(--ws-orange-300)!important}.dark a.group[class*=\"bg-primary\"] *{color:var(--ws-orange-300)!important}.dark aside a:hover,aside a:hover{background-color:var(--ws-orange-50)}.dark aside a:hover{background-color:rgba(255, 103, 25, 0.08)}button[class*=\"ai\"i],button[class*=\"ai\"i] *,button[class*=\"Ask\"i],button[class*=\"Ask\"i] *,[class*=\"AskAI\"],[class*=\"AskAI\"] *,header button[style*=\"background\"],header button[style*=\"background\"] *{color:#ffffff!important}[class*=\"method-post\"],.rm-MethodBadge--post{background-color:var(--ws-orange-500)!important;color:#ffffff!important}[class*=\"method-get\"]{background-color:#258895!important;color:#ffffff!important}[class*=\"method-put\"],[class*=\"method-patch\"]{background-color:#dd7702!important;color:#ffffff!important}[class*=\"method-delete\"]{background-color:#c73107!important;color:#ffffff!important}.card{border-radius:16px!important;border:1px solid rgba(32, 32, 32, 0.08)!important;background:#ffffff!important;box-shadow:none!important;--tw-ring-shadow: 0 0 #0000 !important;--tw-ring-offset-shadow: 0 0 #0000 !important;--tw-ring-color: transparent !important;transition:border-color 180ms cubic-bezier(0.2, 0.7, 0.2, 1)!important}.card:hover{border-color:#ff6719!important;box-shadow:none!important;--tw-ring-shadow: 0 0 #0000 !important;--tw-ring-color: transparent !important}.dark .card{background:#2a2a2a!important;border-color:rgba(255, 255, 255, 0.08)!important}.dark .card:hover{border-color:#ff8337!important}.docs-home-body [class*=\"rounded-full\"][class*=\"size-7\"],.docs-home-body div.rounded-full{background:#ffffff!important;border:1.5px solid #ff6719!important;color:#ff6719!important;font-weight:600!important;box-shadow:0 1px 2px rgba(32, 32, 32, 0.04)}.dark .docs-home-body [class*=\"rounded-full\"][class*=\"size-7\"],.dark .docs-home-body div.rounded-full{background:#2a2a2a!important;border-color:#ff8337!important;color:#ff8337!important}.docs-home-body [class*=\"border-l\"],.docs-home-body div[class*=\"border-gray\"][class*=\"border-l\"]{border-left-color:rgba(32, 32, 32, 0.18)!important;border-left-width:1px!important}.dark .docs-home-body [class*=\"border-l\"],.dark .docs-home-body div[class*=\"border-gray\"][class*=\"border-l\"]{border-left-color:rgba(245, 244, 240, 0.18)!important}[class*=\"callout\"],.callout{border-radius:12px!important;border-left-width:3px!important}.prose table{border-collapse:separate;border-spacing:0;border-radius:12px;overflow:hidden;border:1px solid var(--ws-border);background:var(--ws-paper-white);font-size:0.94em}.dark .prose table{background:rgba(255, 255, 255, 0.02)}.prose thead{background:var(--ws-cream-100)}.dark .prose thead{background:rgba(255, 255, 255, 0.06)}.prose th,.prose td{padding:11px 16px;line-height:1.5;vertical-align:top}.prose th{font-weight:600;color:var(--ws-ink-black);letter-spacing:0.005em;border-bottom:1px solid var(--ws-border)}.dark .prose th{color:var(--ws-light-cream)}.prose tbody tr+tr>td{border-top:1px solid var(--ws-border)}.prose tbody tr:hover>td{background:rgba(32, 32, 32, 0.018)}.dark .prose tbody tr:hover>td{background:rgba(255, 255, 255, 0.03)}.prose tbody td:first-child{color:var(--ws-ink-black)}.dark .prose tbody td:first-child{color:var(--ws-light-cream)}.prose blockquote{border-left:3px solid var(--ws-sonic-orange)!important;background:var(--ws-orange-50);border-radius:0 12px 12px 0;font-style:normal}.dark .prose blockquote{background:rgba(255, 103, 25, 0.06)}*:focus-visible{outline:2px solid var(--ws-sonic-orange)!important;outline-offset:2px!important}.docs-hero{position:relative;overflow:hidden;background:#f5f4f0;padding:64px 24px 96px;margin-top:0;transition:background 200ms cubic-bezier(0.2, 0.7, 0.2, 1)}.dark .docs-hero{background:#202020}.docs-hero-inner{position:relative;max-width:880px;margin:0 auto;z-index:1;text-align:center}.docs-hero-eyebrow{display:inline-block;padding:6px 14px;border-radius:999px;background:rgba(255, 103, 25, 0.1);color:#9e280e;font-size:12px;font-weight:500;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:28px}.dark .docs-hero-eyebrow{background:rgba(255, 103, 25, 0.18);color:#ffa46c}.docs-hero-headline{font-family:\"Roobert\", \"Inter\", system-ui, sans-serif;font-size:clamp(36px, 5.2vw, 60px);font-weight:600;line-height:1.1;letter-spacing:-0.04em;color:#202020;margin:0 auto;text-wrap:balance;max-width:820px}.dark .docs-hero-headline{color:#f5f4f0}.docs-hero-sub{font-family:\"Roobert\", \"Inter\", system-ui, sans-serif;font-size:clamp(16px, 1.2vw, 19px);line-height:1.55;margin:24px auto 0;max-width:620px;color:#3d3d3d}.dark .docs-hero-sub{color:#c6c0ab}.docs-hero-cta-row{margin-top:36px;display:flex;gap:12px;flex-wrap:wrap;justify-content:center}.docs-hero-cta-primary{background:#ff6719;color:#ffffff!important;padding:12px 22px;border-radius:10px;font-weight:500;font-size:15px;text-decoration:none!important;display:inline-flex;align-items:center;gap:6px;transition:background 200ms cubic-bezier(0.2, 0.7, 0.2, 1)}.docs-hero-cta-primary:hover{background:#fd4606;color:#ffffff!important}.docs-hero-cta-ghost{background:transparent;color:#202020!important;padding:12px 22px;border-radius:10px;font-weight:500;font-size:15px;text-decoration:none!important;display:inline-flex;align-items:center;gap:6px;border:1px solid rgba(32, 32, 32, 0.18);transition:border-color 200ms cubic-bezier(0.2, 0.7, 0.2, 1)}.docs-hero-cta-ghost:hover{border-color:#ff6719;color:#ffffff!important}.dark .docs-hero-cta-ghost{color:#f5f4f0!important;border-color:rgba(245, 244, 240, 0.22)}.dark .docs-hero-cta-ghost:hover{border-color:#ff6719;color:#ffffff!important}.docs-hero-lines{position:absolute;bottom:-100px;width:1180px;max-width:none;opacity:0.7;pointer-events:none}.docs-hero-lines.left{left:-360px}.docs-hero-lines.right{right:-360px}.dark .docs-hero-lines{opacity:0.18;filter:invert(1) hue-rotate(180deg) brightness(0.85)}.docs-hero-ailogo{display:inline-flex;align-items:center;justify-content:center;width:0.92em;height:0.92em;margin:0 0.16em -0.08em;background:#ffffff;border-radius:10px;box-shadow:0px 0px 6.36px 0px rgba(255, 103, 25, 0.3);vertical-align:baseline;position:relative;overflow:hidden;flex-shrink:0}.dark .docs-hero-ailogo{background:#ffffff;box-shadow:0px 0px 12px 0px rgba(255, 103, 25, 0.45)}.docs-hero-ailogo>span,.docs-hero-ailogo>span[data-rmiz]{position:absolute!important;top:50%;left:50%;width:64%;height:64%;transform:translate(-50%, calc(-50% + 14px));opacity:0;animation:docs-ai-rotate 7500ms cubic-bezier(0.22, 0.7, 0.2, 1) infinite;display:flex;align-items:center;justify-content:center;pointer-events:none}.docs-hero-ailogo [data-rmiz-content],.docs-hero-ailogo [data-rmiz-content=\"found\"]{display:flex!important;width:100%;height:100%;align-items:center;justify-content:center}.docs-hero-ailogo img{width:100%!important;height:100%!important;object-fit:contain;position:static!important;border-radius:0!important;border:none!important;background:none!important}.docs-hero-ailogo [data-rmiz-ghost],.docs-hero-ailogo [data-rmiz-btn-zoom],.docs-hero-ailogo button{display:none!important;pointer-events:none!important}@keyframes docs-ai-rotate{0%{opacity:0;transform:translate(-50%, calc(-50% + 14px))}3.33%{opacity:1;transform:translate(-50%, -50%)}13.33%{opacity:1;transform:translate(-50%, -50%)}16.67%{opacity:0;transform:translate(-50%, calc(-50% - 14px))}100%{opacity:0;transform:translate(-50%, calc(-50% - 14px))}}.docs-hero-ailogo>span:nth-of-type(1){animation-delay:0ms}.docs-hero-ailogo>span:nth-of-type(2){animation-delay:1250ms}.docs-hero-ailogo>span:nth-of-type(3){animation-delay:2500ms}.docs-hero-ailogo>span:nth-of-type(4){animation-delay:3750ms}.docs-hero-ailogo>span:nth-of-type(5){animation-delay:5000ms}.docs-hero-ailogo>span:nth-of-type(6){animation-delay:6250ms}@media (prefers-reduced-motion: reduce){.docs-hero-ailogo>span{animation:none;opacity:0}.docs-hero-ailogo>span:nth-of-type(1){opacity:1;transform:translate(-50%, -50%)}}.docs-home-body{max-width:1120px;margin:0 auto;padding:0 24px}.docs-home-section{padding:80px 0 24px;border-bottom:1px solid rgba(32, 32, 32, 0.14)}.docs-home-section-last{border-bottom:0;padding-bottom:120px}.dark .docs-home-section{border-bottom-color:rgba(245, 244, 240, 0.14)}.dark .docs-home-section-last{border-bottom:0}.docs-home-eyebrow{font-size:15px;font-weight:600;letter-spacing:0.06em;text-transform:uppercase;color:#ff6719;margin-bottom:18px}.docs-home-h2{font-family:\"Roobert\", \"Inter\", system-ui, sans-serif;font-weight:600;font-size:clamp(28px, 3vw, 40px);line-height:1.15;letter-spacing:-0.03em;color:#202020;margin:0 0 16px;max-width:800px;text-wrap:balance}.dark .docs-home-h2{color:#f5f4f0}.docs-home-lede{font-family:\"Roobert\", \"Inter\", system-ui, sans-serif;font-size:clamp(16px, 1.1vw, 18px);line-height:1.55;color:#5c5c5c;margin:0 0 36px;max-width:720px}.dark .docs-home-lede{color:#c6c0ab}img[src=\"/images/logo/logo-light.svg\"],img[src=\"/images/logo/logo-dark.svg\"],img[alt=\"light logo\"],img[alt=\"dark logo\"]{height:14px!important;width:auto!important;max-height:14px!important}::-webkit-scrollbar{width:10px;height:10px}::-webkit-scrollbar-track{background:transparent}::-webkit-scrollbar-thumb{background:var(--ws-cream-200);border-radius:8px}.dark ::-webkit-scrollbar-thumb{background:rgba(255, 255, 255, 0.1)}::-webkit-scrollbar-thumb:hover{background:var(--ws-orange-300)}"}]}
{"page":{"pagePath":"api-reference/reports/get-ads-report","slug":"/api-reference/reports/get-ads-report","pageMetadata":{"title":"Get Ads Report","description":"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the\nUI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns.\n\nOnly answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope;\nfiltering to any other platform correctly returns no rows.\n\n**Example:** \"Which advertisers bid against my brand, by topic?\"\n\n**Dimensions** (at least 1 required): `topic`, `tag`, `market`, `model`, `query`, `date`, `website`, `branded`, `product`, `placement_type`, `advertiser`\n- `product` rows also carry `product_image`, `product_link`, `brand_id` / `brand_name` / `brand_url` / `brand_logo`, `brand_is_self` and `product_source_type`; `advertiser` rows carry `advertiser_url`, `advertiser_logo`, `advertiser_is_self`\n- `date` supports optional `date_aggregation_interval`: `day` (default) | `week` | `month`; buckets on the placement date\n- `website` is the advertised brand, and auto-sets `website_type` to `SELF+COMPETITORS`; `product` / `advertiser` auto-set it to `ALL`, like the dashboard's Advertisers page (default otherwise is `SELF`)\n- `product` is the ad creative — a product card (`AD_SHOPPING`) or a text ad (`AD_TEXT`)\n\n**Measures** (omit for all): `ad_visibility`, `share_of_ad_placements`, `ad_placements`, `ad_answers`, `placements_with_self_brand`, `unique_advertisers`, `unique_ad_creatives`, `ad_rank`, `avg_quoted_price`\n- `ad_visibility` = `ad_placements` / `ad_answers`, where `ad_answers` counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard\n- `share_of_ad_placements` = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels `ad_placements / ad_answers` as \"share of ad placements\"; that column is `ad_visibility` here\n- `ad_placements` counts distinct **answers** in which the entity's ad appeared, not individual placements\n- `avg_quoted_price` also returns `avg_quoted_price_currency`\n\n**Filters:** `topics`, `prompts`, `tags`, `markets`, `intent`, `branded`, `platform`, `website_mentioned_in_answer`, `cited_page_url`, `cited_domain`, `website_mentioned_in_citation`, `products`, `brands`, `advertisers`, `placement_type`, `source_type`, `price`, `product_rank`.\n- `has_shopping_card`, `has_ads_data`, `visibility`, `rank` and `status` are accepted for compatibility with the other report endpoints and ignored here.\n- `platform` matches the model that produced the answer (stricter than `/reports/performance`, which matches prompts that ever ran on a platform).\n\n**Sort fields:** Any measure name, plus `date`, `query_name`, `topic_name`, `market_name`, `model_name`, `website_name`, `tag_name`, `product_name`, `advertiser_name`, `placement_type`.\n\n**Dates:** If no dates provided, defaults to latest run date range. Provide `start_date` and `end_date` in ISO 8601 format to specify a custom range.\n\n**Comparison:** Provide `comparison_start_date` and `comparison_end_date` (ISO 8601, both required together) to also compute every measure over a past range — each row then gains `previous_\u003cmeasure>` fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the `date` dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\n\n**Filter values:** `markets` takes a market id or `contains` with a region code such as `us` (names like `United States` and labels like `us - en` match nothing); `tags`, `topics` and `platform` match by name or id.\n\n**Pagination:** Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting.\n\n**Response:** Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters).\n\n**Notes:** Days with no placements are omitted rather than zero-filled. Grouping by `merchant`/`advertiser` fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive.","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/ads","href":"/api-reference/reports/get-ads-report","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the\\nUI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns.\"\n }), \"\\n\", _jsx(_components.p, {\n children: \"Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope;\\nfiltering to any other platform correctly returns no rows.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Example:\"\n }), \" “Which advertisers bid against my brand, by topic?”\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Dimensions\"\n }), \" (at least 1 required): \", _jsx(_components.code, {\n children: \"topic\"\n }), \", \", _jsx(_components.code, {\n children: \"tag\"\n }), \", \", _jsx(_components.code, {\n children: \"market\"\n }), \", \", _jsx(_components.code, {\n children: \"model\"\n }), \", \", _jsx(_components.code, {\n children: \"query\"\n }), \", \", _jsx(_components.code, {\n children: \"date\"\n }), \", \", _jsx(_components.code, {\n children: \"website\"\n }), \", \", _jsx(_components.code, {\n children: \"branded\"\n }), \", \", _jsx(_components.code, {\n children: \"product\"\n }), \", \", _jsx(_components.code, {\n children: \"placement_type\"\n }), \", \", _jsx(_components.code, {\n children: \"advertiser\"\n })]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"product\"\n }), \" rows also carry \", _jsx(_components.code, {\n children: \"product_image\"\n }), \", \", _jsx(_components.code, {\n children: \"product_link\"\n }), \", \", _jsx(_components.code, {\n children: \"brand_id\"\n }), \" / \", _jsx(_components.code, {\n children: \"brand_name\"\n }), \" / \", _jsx(_components.code, {\n children: \"brand_url\"\n }), \" / \", _jsx(_components.code, {\n children: \"brand_logo\"\n }), \", \", _jsx(_components.code, {\n children: \"brand_is_self\"\n }), \" and \", _jsx(_components.code, {\n children: \"product_source_type\"\n }), \"; \", _jsx(_components.code, {\n children: \"advertiser\"\n }), \" rows carry \", _jsx(_components.code, {\n children: \"advertiser_url\"\n }), \", \", _jsx(_components.code, {\n children: \"advertiser_logo\"\n }), \", \", _jsx(_components.code, {\n children: \"advertiser_is_self\"\n })]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"date\"\n }), \" supports optional \", _jsx(_components.code, {\n children: \"date_aggregation_interval\"\n }), \": \", _jsx(_components.code, {\n children: \"day\"\n }), \" (default) | \", _jsx(_components.code, {\n children: \"week\"\n }), \" | \", _jsx(_components.code, {\n children: \"month\"\n }), \"; buckets on the placement date\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"website\"\n }), \" is the advertised brand, and auto-sets \", _jsx(_components.code, {\n children: \"website_type\"\n }), \" to \", _jsx(_components.code, {\n children: \"SELF+COMPETITORS\"\n }), \"; \", _jsx(_components.code, {\n children: \"product\"\n }), \" / \", _jsx(_components.code, {\n children: \"advertiser\"\n }), \" auto-set it to \", _jsx(_components.code, {\n children: \"ALL\"\n }), \", like the dashboard’s Advertisers page (default otherwise is \", _jsx(_components.code, {\n children: \"SELF\"\n }), \")\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"product\"\n }), \" is the ad creative — a product card (\", _jsx(_components.code, {\n children: \"AD_SHOPPING\"\n }), \") or a text ad (\", _jsx(_components.code, {\n children: \"AD_TEXT\"\n }), \")\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Measures\"\n }), \" (omit for all): \", _jsx(_components.code, {\n children: \"ad_visibility\"\n }), \", \", _jsx(_components.code, {\n children: \"share_of_ad_placements\"\n }), \", \", _jsx(_components.code, {\n children: \"ad_placements\"\n }), \", \", _jsx(_components.code, {\n children: \"ad_answers\"\n }), \", \", _jsx(_components.code, {\n children: \"placements_with_self_brand\"\n }), \", \", _jsx(_components.code, {\n children: \"unique_advertisers\"\n }), \", \", _jsx(_components.code, {\n children: \"unique_ad_creatives\"\n }), \", \", _jsx(_components.code, {\n children: \"ad_rank\"\n }), \", \", _jsx(_components.code, {\n children: \"avg_quoted_price\"\n })]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ad_visibility\"\n }), \" = \", _jsx(_components.code, {\n children: \"ad_placements\"\n }), \" / \", _jsx(_components.code, {\n children: \"ad_answers\"\n }), \", where \", _jsx(_components.code, {\n children: \"ad_answers\"\n }), \" counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"share_of_ad_placements\"\n }), \" = this advertiser’s placements / all tracked advertisers’ placements, the definition behind the Ads dashboard KPI card. The dashboard’s Advertisers table labels \", _jsx(_components.code, {\n children: \"ad_placements / ad_answers\"\n }), \" as “share of ad placements”; that column is \", _jsx(_components.code, {\n children: \"ad_visibility\"\n }), \" here\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"ad_placements\"\n }), \" counts distinct \", _jsx(_components.strong, {\n children: \"answers\"\n }), \" in which the entity’s ad appeared, not individual placements\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"avg_quoted_price\"\n }), \" also returns \", _jsx(_components.code, {\n children: \"avg_quoted_price_currency\"\n })]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Filters:\"\n }), \" \", _jsx(_components.code, {\n children: \"topics\"\n }), \", \", _jsx(_components.code, {\n children: \"prompts\"\n }), \", \", _jsx(_components.code, {\n children: \"tags\"\n }), \", \", _jsx(_components.code, {\n children: \"markets\"\n }), \", \", _jsx(_components.code, {\n children: \"intent\"\n }), \", \", _jsx(_components.code, {\n children: \"branded\"\n }), \", \", _jsx(_components.code, {\n children: \"platform\"\n }), \", \", _jsx(_components.code, {\n children: \"website_mentioned_in_answer\"\n }), \", \", _jsx(_components.code, {\n children: \"cited_page_url\"\n }), \", \", _jsx(_components.code, {\n children: \"cited_domain\"\n }), \", \", _jsx(_components.code, {\n children: \"website_mentioned_in_citation\"\n }), \", \", _jsx(_components.code, {\n children: \"products\"\n }), \", \", _jsx(_components.code, {\n children: \"brands\"\n }), \", \", _jsx(_components.code, {\n children: \"advertisers\"\n }), \", \", _jsx(_components.code, {\n children: \"placement_type\"\n }), \", \", _jsx(_components.code, {\n children: \"source_type\"\n }), \", \", _jsx(_components.code, {\n children: \"price\"\n }), \", \", _jsx(_components.code, {\n children: \"product_rank\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"has_shopping_card\"\n }), \", \", _jsx(_components.code, {\n children: \"has_ads_data\"\n }), \", \", _jsx(_components.code, {\n children: \"visibility\"\n }), \", \", _jsx(_components.code, {\n children: \"rank\"\n }), \" and \", _jsx(_components.code, {\n children: \"status\"\n }), \" are accepted for compatibility with the other report endpoints and ignored here.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"platform\"\n }), \" matches the model that produced the answer (stricter than \", _jsx(_components.code, {\n children: \"/reports/performance\"\n }), \", which matches prompts that ever ran on a platform).\"]\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Sort fields:\"\n }), \" Any measure name, plus \", _jsx(_components.code, {\n children: \"date\"\n }), \", \", _jsx(_components.code, {\n children: \"query_name\"\n }), \", \", _jsx(_components.code, {\n children: \"topic_name\"\n }), \", \", _jsx(_components.code, {\n children: \"market_name\"\n }), \", \", _jsx(_components.code, {\n children: \"model_name\"\n }), \", \", _jsx(_components.code, {\n children: \"website_name\"\n }), \", \", _jsx(_components.code, {\n children: \"tag_name\"\n }), \", \", _jsx(_components.code, {\n children: \"product_name\"\n }), \", \", _jsx(_components.code, {\n children: \"advertiser_name\"\n }), \", \", _jsx(_components.code, {\n children: \"placement_type\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Dates:\"\n }), \" If no dates provided, defaults to latest run date range. Provide \", _jsx(_components.code, {\n children: \"start_date\"\n }), \" and \", _jsx(_components.code, {\n children: \"end_date\"\n }), \" in ISO 8601 format to specify a custom range.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Comparison:\"\n }), \" Provide \", _jsx(_components.code, {\n children: \"comparison_start_date\"\n }), \" and \", _jsx(_components.code, {\n children: \"comparison_end_date\"\n }), \" (ISO 8601, both required together) to also compute every measure over a past range — each row then gains \", _jsx(_components.code, {\n children: \"previous_\u003cmeasure>\"\n }), \" fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the \", _jsx(_components.code, {\n children: \"date\"\n }), \" dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Filter values:\"\n }), \" \", _jsx(_components.code, {\n children: \"markets\"\n }), \" takes a market id or \", _jsx(_components.code, {\n children: \"contains\"\n }), \" with a region code such as \", _jsx(_components.code, {\n children: \"us\"\n }), \" (names like \", _jsx(_components.code, {\n children: \"United States\"\n }), \" and labels like \", _jsx(_components.code, {\n children: \"us - en\"\n }), \" match nothing); \", _jsx(_components.code, {\n children: \"tags\"\n }), \", \", _jsx(_components.code, {\n children: \"topics\"\n }), \" and \", _jsx(_components.code, {\n children: \"platform\"\n }), \" match by name or id.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Pagination:\"\n }), \" Use \", _jsx(_components.code, {\n children: \"pagination\"\n }), \" (\", _jsx(_components.code, {\n children: \"limit\"\n }), \" 1-100, default 10; \", _jsx(_components.code, {\n children: \"offset\"\n }), \" for paging). Use \", _jsx(_components.code, {\n children: \"order_by\"\n }), \" for sorting.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Response:\"\n }), \" Returns \", _jsx(_components.code, {\n children: \"data\"\n }), \" array with \", _jsx(_components.code, {\n children: \"info\"\n }), \" metadata containing \", _jsx(_components.code, {\n children: \"total_rows\"\n }), \" (before pagination) and \", _jsx(_components.code, {\n children: \"query\"\n }), \" (applied metrics, dates, sorting, pagination, filters).\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Notes:\"\n }), \" Days with no placements are omitted rather than zero-filled. Grouping by \", _jsx(_components.code, {\n children: \"merchant\"\n }), \"/\", _jsx(_components.code, {\n children: \"advertiser\"\n }), \" fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). \", _jsx(_components.code, {\n children: \"AD_SHOPPING\"\n }), \" placements count in both this report and the other one, so shopping and ad totals are not additive.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"codeStyling":"system","config":{},"pageMetadata":{"title":"Get Ads Report","description":"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the\nUI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns.\n\nOnly answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope;\nfiltering to any other platform correctly returns no rows.\n\n**Example:** \"Which advertisers bid against my brand, by topic?\"\n\n**Dimensions** (at least 1 required): `topic`, `tag`, `market`, `model`, `query`, `date`, `website`, `branded`, `product`, `placement_type`, `advertiser`\n- `product` rows also carry `product_image`, `product_link`, `brand_id` / `brand_name` / `brand_url` / `brand_logo`, `brand_is_self` and `product_source_type`; `advertiser` rows carry `advertiser_url`, `advertiser_logo`, `advertiser_is_self`\n- `date` supports optional `date_aggregation_interval`: `day` (default) | `week` | `month`; buckets on the placement date\n- `website` is the advertised brand, and auto-sets `website_type` to `SELF+COMPETITORS`; `product` / `advertiser` auto-set it to `ALL`, like the dashboard's Advertisers page (default otherwise is `SELF`)\n- `product` is the ad creative — a product card (`AD_SHOPPING`) or a text ad (`AD_TEXT`)\n\n**Measures** (omit for all): `ad_visibility`, `share_of_ad_placements`, `ad_placements`, `ad_answers`, `placements_with_self_brand`, `unique_advertisers`, `unique_ad_creatives`, `ad_rank`, `avg_quoted_price`\n- `ad_visibility` = `ad_placements` / `ad_answers`, where `ad_answers` counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard\n- `share_of_ad_placements` = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels `ad_placements / ad_answers` as \"share of ad placements\"; that column is `ad_visibility` here\n- `ad_placements` counts distinct **answers** in which the entity's ad appeared, not individual placements\n- `avg_quoted_price` also returns `avg_quoted_price_currency`\n\n**Filters:** `topics`, `prompts`, `tags`, `markets`, `intent`, `branded`, `platform`, `website_mentioned_in_answer`, `cited_page_url`, `cited_domain`, `website_mentioned_in_citation`, `products`, `brands`, `advertisers`, `placement_type`, `source_type`, `price`, `product_rank`.\n- `has_shopping_card`, `has_ads_data`, `visibility`, `rank` and `status` are accepted for compatibility with the other report endpoints and ignored here.\n- `platform` matches the model that produced the answer (stricter than `/reports/performance`, which matches prompts that ever ran on a platform).\n\n**Sort fields:** Any measure name, plus `date`, `query_name`, `topic_name`, `market_name`, `model_name`, `website_name`, `tag_name`, `product_name`, `advertiser_name`, `placement_type`.\n\n**Dates:** If no dates provided, defaults to latest run date range. Provide `start_date` and `end_date` in ISO 8601 format to specify a custom range.\n\n**Comparison:** Provide `comparison_start_date` and `comparison_end_date` (ISO 8601, both required together) to also compute every measure over a past range — each row then gains `previous_\u003cmeasure>` fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the `date` dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\n\n**Filter values:** `markets` takes a market id or `contains` with a region code such as `us` (names like `United States` and labels like `us - en` match nothing); `tags`, `topics` and `platform` match by name or id.\n\n**Pagination:** Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting.\n\n**Response:** Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters).\n\n**Notes:** Days with no placements are omitted rather than zero-filled. Grouping by `merchant`/`advertiser` fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive.","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/ads","href":"/api-reference/reports/get-ads-report","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"tags":["Reports"],"summary":"Get Ads Report","description":"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the\nUI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns.\n\nOnly answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope;\nfiltering to any other platform correctly returns no rows.\n\n**Example:** \"Which advertisers bid against my brand, by topic?\"\n\n**Dimensions** (at least 1 required): `topic`, `tag`, `market`, `model`, `query`, `date`, `website`, `branded`, `product`, `placement_type`, `advertiser`\n- `product` rows also carry `product_image`, `product_link`, `brand_id` / `brand_name` / `brand_url` / `brand_logo`, `brand_is_self` and `product_source_type`; `advertiser` rows carry `advertiser_url`, `advertiser_logo`, `advertiser_is_self`\n- `date` supports optional `date_aggregation_interval`: `day` (default) | `week` | `month`; buckets on the placement date\n- `website` is the advertised brand, and auto-sets `website_type` to `SELF+COMPETITORS`; `product` / `advertiser` auto-set it to `ALL`, like the dashboard's Advertisers page (default otherwise is `SELF`)\n- `product` is the ad creative — a product card (`AD_SHOPPING`) or a text ad (`AD_TEXT`)\n\n**Measures** (omit for all): `ad_visibility`, `share_of_ad_placements`, `ad_placements`, `ad_answers`, `placements_with_self_brand`, `unique_advertisers`, `unique_ad_creatives`, `ad_rank`, `avg_quoted_price`\n- `ad_visibility` = `ad_placements` / `ad_answers`, where `ad_answers` counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard\n- `share_of_ad_placements` = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels `ad_placements / ad_answers` as \"share of ad placements\"; that column is `ad_visibility` here\n- `ad_placements` counts distinct **answers** in which the entity's ad appeared, not individual placements\n- `avg_quoted_price` also returns `avg_quoted_price_currency`\n\n**Filters:** `topics`, `prompts`, `tags`, `markets`, `intent`, `branded`, `platform`, `website_mentioned_in_answer`, `cited_page_url`, `cited_domain`, `website_mentioned_in_citation`, `products`, `brands`, `advertisers`, `placement_type`, `source_type`, `price`, `product_rank`.\n- `has_shopping_card`, `has_ads_data`, `visibility`, `rank` and `status` are accepted for compatibility with the other report endpoints and ignored here.\n- `platform` matches the model that produced the answer (stricter than `/reports/performance`, which matches prompts that ever ran on a platform).\n\n**Sort fields:** Any measure name, plus `date`, `query_name`, `topic_name`, `market_name`, `model_name`, `website_name`, `tag_name`, `product_name`, `advertiser_name`, `placement_type`.\n\n**Dates:** If no dates provided, defaults to latest run date range. Provide `start_date` and `end_date` in ISO 8601 format to specify a custom range.\n\n**Comparison:** Provide `comparison_start_date` and `comparison_end_date` (ISO 8601, both required together) to also compute every measure over a past range — each row then gains `previous_\u003cmeasure>` fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the `date` dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\n\n**Filter values:** `markets` takes a market id or `contains` with a region code such as `us` (names like `United States` and labels like `us - en` match nothing); `tags`, `topics` and `platform` match by name or id.\n\n**Pagination:** Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting.\n\n**Response:** Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters).\n\n**Notes:** Days with no placements are omitted rather than zero-filled. Grouping by `merchant`/`advertiser` fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive.","operationId":"get_ads_report","requestBody":"0f54233b-af9e-4b43-9c33-8cdf3f9b648b","responses":{"200":"51f7722b-eeb6-4575-b887-bddee5c46b34","422":"e87de02c-86d1-42fb-a6a4-134a8981699c"},"security":["3bf10f38-a770-4694-a534-e8a0dc2445c3"],"method":"post","type":"path","servers":["9c01b566-187d-43fe-b854-b1240f8f9075"],"path":"/v2/geo/reports/ads","baseUrlOptions":["https://api.writesonic.com"],"title":"Get Ads Report","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"content":{"application/json":{"schema":{"properties":{"project_id":{"type":"string","minLength":1,"title":"Project Id","description":"Unique identifier of the project to query. Get valid project IDs from get_all_projects.","examples":["550e8400-e29b-41d4-a716-446655440000"],"isRequired":true,"uniqueKey":"project_id","typeLabel":"string"},"dimensions":{"items":{"type":"string","enum":["topic","tag","market","model","query","date","website","shopping","ads","branded","persona","intent_stage","locality","search_intent","domain","page","source_type","theme","subtheme","keyword","product","merchant","advertiser","placement_type"],"title":"Dimension","description":"Dimensions to group report data by. Each report accepts a subset; unsupported dimensions are rejected with 400.\n\n- `topic`: Group by topic/category\n- `tag`: Group by tag\n- `market`: Group by market/region\n- `model`: Group by AI model (e.g. ChatGPT, Perplexity)\n- `query`: Group by individual query/prompt\n- `date`: Group by date (requires date_aggregation_interval)\n- `website`: Group by tracked website\n- `shopping`: Group by whether the response has a shopping card (true/false)\n- `ads`: Group by whether the response has sponsored/ad placements (true/false)\n- `branded`: Group by whether the underlying query is branded (true/false)\n- `persona`: Group by the persona prompt target attached to the query\n- `intent_stage`: Group by the intent-stage prompt target attached to the query\n- `locality`: Group by the locality prompt target attached to the query\n- `search_intent`: Group by the query's dominant search intent (transactional, navigational, informational, commercial)\n- `domain`: Group by cited domain (citations report only)\n- `page`: Group by cited page URL (citations report only)\n- `source_type`: Group by cited source type: owned, competitor, social_forums, third_party (citations report only)\n- `theme`: Group by sentiment theme (sentiments report only)\n- `subtheme`: Group by sentiment subtheme (sentiments report only)\n- `keyword`: Group by sentiment keyword (sentiments report only)\n- `product`: Group by shopping product / ad creative (shopping and ads reports only)\n- `merchant`: Group by the merchant offering a purchase link (shopping report only)\n- `advertiser`: Group by the advertiser that placed the ad (ads report only)\n- `placement_type`: Group by placement type (e.g. SHOPPING_CARD, AD_TEXT)","x-enumDescriptions":{"ads":"Group by whether the response has sponsored/ad placements (true/false)","advertiser":"Group by the advertiser that placed the ad (ads report only)","branded":"Group by whether the underlying query is branded (true/false)","date":"Group by date (requires date_aggregation_interval)","domain":"Group by cited domain (citations report only)","intent_stage":"Group by the intent-stage prompt target attached to the query","keyword":"Group by sentiment keyword (sentiments report only)","locality":"Group by the locality prompt target attached to the query","market":"Group by market/region","merchant":"Group by the merchant offering a purchase link (shopping report only)","model":"Group by AI model (e.g. ChatGPT, Perplexity)","page":"Group by cited page URL (citations report only)","persona":"Group by the persona prompt target attached to the query","placement_type":"Group by placement type (e.g. SHOPPING_CARD, AD_TEXT)","product":"Group by shopping product / ad creative (shopping and ads reports only)","query":"Group by individual query/prompt","search_intent":"Group by the query's dominant search intent (transactional, navigational, informational, commercial)","shopping":"Group by whether the response has a shopping card (true/false)","source_type":"Group by cited source type: owned, competitor, social_forums, third_party (citations report only)","subtheme":"Group by sentiment subtheme (sentiments report only)","tag":"Group by tag","theme":"Group by sentiment theme (sentiments report only)","topic":"Group by topic/category","website":"Group by tracked website"},"uniqueKey":"dimensions.items.[INDEX]","typeLabel":"enum\u003cstring>"},"type":"array","minItems":1,"title":"Dimensions","description":"Dimensions to group ad data by. At least one dimension is required.","examples":[["website"],["advertiser"],["topic","date"]],"isRequired":true,"uniqueKey":"dimensions","typeLabel":"enum\u003cstring>[]"},"start_date":{"type":"string","format":"date-time","title":"Start Date","description":"Start of the date range (ISO 8601). Limits results to data collected on or after this date. When omitted: defaults to the latest run's start date for metric queries, or earliest available date for list queries.","examples":["2026-01-01T00:00:00Z","2026-03-01T00:00:00Z"],"uniqueKey":"start_date","typeLabel":"string\u003cdate-time>"},"end_date":{"type":"string","format":"date-time","title":"End Date","description":"End of the date range (ISO 8601). Limits results to data collected on or before this date. When omitted: defaults to today. Date-only strings (no 'T') are extended to end of day.","examples":["2026-01-31T23:59:59Z","2026-03-17T23:59:59Z"],"uniqueKey":"end_date","typeLabel":"string\u003cdate-time>"},"current_from":{"type":"string","format":"date-time","title":"Current From","description":"Alias for start_date (analytics-tool date naming).","uniqueKey":"current_from","typeLabel":"string\u003cdate-time>"},"current_to":{"type":"string","format":"date-time","title":"Current To","description":"Alias for end_date (analytics-tool date naming).","uniqueKey":"current_to","typeLabel":"string\u003cdate-time>"},"comparison_start_date":{"type":"string","format":"date-time","title":"Comparison Start Date","description":"Start of the comparison (past) date range (ISO 8601). Provide together with comparison_end_date to additionally compute every measure over this past range — each row then includes previous_\u003cmeasure> values calculated with identical dimensions, measures, and filters.","examples":["2026-07-25T00:00:00Z"],"uniqueKey":"comparison_start_date","typeLabel":"string\u003cdate-time>"},"comparison_end_date":{"type":"string","format":"date-time","title":"Comparison End Date","description":"End of the comparison (past) date range (ISO 8601). Required together with comparison_start_date. Date-only strings (no 'T') are extended to end of day, same as end_date.","examples":["2026-07-31T23:59:59Z"],"uniqueKey":"comparison_end_date","typeLabel":"string\u003cdate-time>"},"previous_from":{"type":"string","format":"date-time","title":"Previous From","description":"Alias for comparison_start_date (analytics-tool date naming).","uniqueKey":"previous_from","typeLabel":"string\u003cdate-time>"},"previous_to":{"type":"string","format":"date-time","title":"Previous To","description":"Alias for comparison_end_date (analytics-tool date naming).","uniqueKey":"previous_to","typeLabel":"string\u003cdate-time>"},"order_by":{"items":{"properties":{"field":{"type":"string","title":"Field","description":"Field name to sort by. Must match a measure or dimension name from the response (e.g., 'visibility_score', 'mention_count', 'topic_name').","examples":["visibility_score","mention_count","rank"],"isRequired":true,"uniqueKey":"order_by.items.[INDEX].field","typeLabel":"string"},"order":{"type":"string","enum":["asc","desc"],"title":"SortOrderType","description":"Sort direction: 'asc' (lowest first) or 'desc' (highest first).","x-enumDescriptions":{"asc":"Ascending order (lowest first, A-Z, oldest first)","desc":"Descending order (highest first, Z-A, newest first)"},"examples":["desc"],"isRequired":true,"uniqueKey":"order_by.items.[INDEX].order","typeLabel":"enum\u003cstring>"}},"additionalProperties":false,"type":"object","required":["field","order"],"title":"SortingOrder","description":"Sort results by a specific field. Use with `order_by` to control result ordering — e.g., sort by visibility score descending to see top performers first.","uniqueKey":"order_by.items.[INDEX]","typeLabel":"SortingOrder · object"},"type":"array","title":"Order By","description":"Sort results by one or more fields. Each entry specifies a field name and direction. Results are sorted by the first entry, then ties broken by subsequent entries.","examples":[[{"field":"visibility_score","order":"desc"}],[{"field":"mention_count","order":"desc"},{"field":"rank","order":"asc"}]],"uniqueKey":"order_by","typeLabel":"SortingOrder · object[]"},"pagination":{"properties":{"limit":{"type":"integer","maximum":100,"minimum":1,"title":"Limit","description":"Number of items per page (1-100). Use smaller values for faster responses.","default":10,"examples":[10,25,50],"uniqueKey":"pagination.limit","typeLabel":"integer"},"offset":{"type":"integer","minimum":0,"title":"Offset","description":"Number of items to skip. Set to `limit * page_number` for page-based navigation.","default":0,"examples":[0,10,50],"uniqueKey":"pagination.offset","typeLabel":"integer"}},"additionalProperties":false,"type":"object","title":"PaginationInput","description":"Control result pagination. Set `limit` for page size and `offset` to skip results. Omit to return all results (use with caution on large datasets).","examples":[{"limit":10,"offset":0},{"limit":25,"offset":50}],"uniqueKey":"pagination","typeLabel":"PaginationInput · object"},"measures":{"items":{"type":"string","enum":["ad_visibility","share_of_ad_placements","ad_placements","ad_answers","placements_with_self_brand","unique_advertisers","unique_ad_creatives","ad_rank","avg_quoted_price"],"title":"AdsMeasure","description":"Ad metrics to include in the report.\n\n- `ad_visibility`: Percentage of ad-bearing answers featuring this entity (0-100)\n- `share_of_ad_placements`: This entity's placements as a percentage of all tracked-brand ad placements in the group (0-100)\n- `ad_placements`: Number of distinct answers in which this entity's ad appeared\n- `ad_answers`: Total answers in the group containing at least one ad placement (the ad_visibility denominator)\n- `placements_with_self_brand`: Ad placements promoting your own brand's product\n- `unique_advertisers`: Number of distinct advertisers\n- `unique_ad_creatives`: Number of distinct ad creatives (product cards and text ads)\n- `ad_rank`: Average position of the ad within the answer (lower is better)\n- `avg_quoted_price`: Average quoted price across ad purchase links; also returns avg_quoted_price_currency","x-enumDescriptions":{"ad_answers":"Total answers in the group containing at least one ad placement (the ad_visibility denominator)","ad_placements":"Number of distinct answers in which this entity's ad appeared","ad_rank":"Average position of the ad within the answer (lower is better)","ad_visibility":"Percentage of ad-bearing answers featuring this entity (0-100)","avg_quoted_price":"Average quoted price across ad purchase links; also returns avg_quoted_price_currency","placements_with_self_brand":"Ad placements promoting your own brand's product","share_of_ad_placements":"This entity's placements as a percentage of all tracked-brand ad placements in the group (0-100)","unique_ad_creatives":"Number of distinct ad creatives (product cards and text ads)","unique_advertisers":"Number of distinct advertisers"},"uniqueKey":"measures.items.[INDEX]","typeLabel":"enum\u003cstring>"},"type":"array","title":"Measures","description":"Ad metrics to include. If empty, all measures are returned.","examples":[["ad_visibility","share_of_ad_placements"]],"uniqueKey":"measures","typeLabel":"enum\u003cstring>[]"},"filters":{"properties":{"topics":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.topics.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.topics.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.topics.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.topics.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.topics.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by topic ID or topic name.","examples":[{"condition":"OR","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]}],"uniqueKey":"filters.topics","typeLabel":"StringFilterGroup · object"},"prompts":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.prompts.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.prompts.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.prompts.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.prompts.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.prompts.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by prompt ID or query text. Use 'contains' for partial text matching.","examples":[{"condition":"AND","items":[{"operator":"contains","value":"best AI tools"}]}],"uniqueKey":"filters.prompts","typeLabel":"StringFilterGroup · object"},"tags":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.tags.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.tags.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.tags.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.tags.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.tags.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by tag ID or tag name. 'is' checks tag association, 'is_not' excludes.","examples":[{"condition":"OR","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"}]}],"uniqueKey":"filters.tags","typeLabel":"StringFilterGroup · object"},"markets":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.markets.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.markets.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.markets.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.markets.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.markets.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by market ID or region name (e.g., 'United States').","examples":[{"condition":"OR","items":[{"operator":"is","value":"United States"},{"operator":"is","value":"United Kingdom"}]}],"uniqueKey":"filters.markets","typeLabel":"StringFilterGroup · object"},"intent":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.intent.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.intent.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.intent.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.intent.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.intent.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by search intent: 'transactional', 'navigational', 'informational', 'commercial'.","examples":[{"condition":"OR","items":[{"operator":"is","value":"informational"},{"operator":"is","value":"commercial"}]}],"uniqueKey":"filters.intent","typeLabel":"StringFilterGroup · object"},"branded":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.branded.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not"],"title":"BooleanOperator","description":"'is' (match value) or 'is_not' (exclude value)","x-enumDescriptions":{"is":"Match rows where the field equals the boolean value","is_not":"Match rows where the field does not equal the boolean value"},"examples":["is"],"isRequired":true,"uniqueKey":"filters.branded.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Boolean value: true or false.","examples":[true,false],"uniqueKey":"filters.branded.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"BooleanFilterCondition","description":"A single boolean filter condition.\n\nOperators:\n- `is` — Match value. Example: {\"operator\": \"is\", \"value\": true}\n- `is_not` — Exclude value.","uniqueKey":"filters.branded.\\items.items.[INDEX]","typeLabel":"BooleanFilterCondition · object"},"type":"array","title":"Items","description":"List of boolean filter conditions to apply.","examples":[[{"operator":"is","value":true}]],"uniqueKey":"filters.branded.\\items","typeLabel":"BooleanFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"BooleanFilterGroup","description":"true = branded queries only, false = non-branded only.","examples":[{"condition":"AND","items":[{"operator":"is","value":false}]}],"uniqueKey":"filters.branded","typeLabel":"BooleanFilterGroup · object"},"platform":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.platform.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.platform.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.platform.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.platform.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.platform.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by AI platform name (e.g., 'ChatGPT', 'Perplexity', 'Gemini'). Use 'contains' for partial matches.","examples":[{"condition":"OR","items":[{"operator":"is","value":"ChatGPT"},{"operator":"is","value":"Perplexity"}]}],"uniqueKey":"filters.platform","typeLabel":"StringFilterGroup · object"},"has_shopping_card":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.has_shopping_card.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not"],"title":"BooleanOperator","description":"'is' (match value) or 'is_not' (exclude value)","x-enumDescriptions":{"is":"Match rows where the field equals the boolean value","is_not":"Match rows where the field does not equal the boolean value"},"examples":["is"],"isRequired":true,"uniqueKey":"filters.has_shopping_card.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Boolean value: true or false.","examples":[true,false],"uniqueKey":"filters.has_shopping_card.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"BooleanFilterCondition","description":"A single boolean filter condition.\n\nOperators:\n- `is` — Match value. Example: {\"operator\": \"is\", \"value\": true}\n- `is_not` — Exclude value.","uniqueKey":"filters.has_shopping_card.\\items.items.[INDEX]","typeLabel":"BooleanFilterCondition · object"},"type":"array","title":"Items","description":"List of boolean filter conditions to apply.","examples":[[{"operator":"is","value":true}]],"uniqueKey":"filters.has_shopping_card.\\items","typeLabel":"BooleanFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"BooleanFilterGroup","description":"true = only responses with shopping cards.","examples":[{"condition":"AND","items":[{"operator":"is","value":true}]}],"uniqueKey":"filters.has_shopping_card","typeLabel":"BooleanFilterGroup · object"},"has_ads_data":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.has_ads_data.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not"],"title":"BooleanOperator","description":"'is' (match value) or 'is_not' (exclude value)","x-enumDescriptions":{"is":"Match rows where the field equals the boolean value","is_not":"Match rows where the field does not equal the boolean value"},"examples":["is"],"isRequired":true,"uniqueKey":"filters.has_ads_data.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Boolean value: true or false.","examples":[true,false],"uniqueKey":"filters.has_ads_data.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"BooleanFilterCondition","description":"A single boolean filter condition.\n\nOperators:\n- `is` — Match value. Example: {\"operator\": \"is\", \"value\": true}\n- `is_not` — Exclude value.","uniqueKey":"filters.has_ads_data.\\items.items.[INDEX]","typeLabel":"BooleanFilterCondition · object"},"type":"array","title":"Items","description":"List of boolean filter conditions to apply.","examples":[[{"operator":"is","value":true}]],"uniqueKey":"filters.has_ads_data.\\items","typeLabel":"BooleanFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"BooleanFilterGroup","description":"true = only responses that include sponsored / ad placements.","examples":[{"condition":"AND","items":[{"operator":"is","value":true}]}],"uniqueKey":"filters.has_ads_data","typeLabel":"BooleanFilterGroup · object"},"visibility":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.visibility.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"],"title":"NumericOperator","description":"'eq' (=), 'neq' (!=), 'gt' (>), 'gte' (>=), 'lt' (\u003c), 'lte' (\u003c=)","x-enumDescriptions":{"eq":"Equal to (=)","gt":"Greater than (>)","gte":"Greater than or equal to (>=)","lt":"Less than (\u003c)","lte":"Less than or equal to (\u003c=)","neq":"Not equal to (!=)"},"examples":["gte","lte","eq"],"isRequired":true,"uniqueKey":"filters.visibility.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Numeric value to compare against (integer or float).","examples":[50,3,0.75],"uniqueKey":"filters.visibility.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"NumericFilterCondition","description":"A single numeric filter condition for range-based filtering.\n\nOperators:\n- `eq` (=), `neq` (not equal), `gt` (>), `gte` (>=), `lt` (\u003c), `lte` (\u003c=)\n\nExample: {\"operator\": \"gte\", \"value\": 50}","uniqueKey":"filters.visibility.\\items.items.[INDEX]","typeLabel":"NumericFilterCondition · object"},"type":"array","title":"Items","description":"List of numeric filter conditions to apply.","examples":[[{"operator":"gte","value":50}]],"uniqueKey":"filters.visibility.\\items","typeLabel":"NumericFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"NumericFilterGroup","description":"Keep only answers where your brand's mention has this visibility score (0-100).","examples":[{"condition":"AND","items":[{"operator":"gte","value":50}]}],"uniqueKey":"filters.visibility","typeLabel":"NumericFilterGroup · object"},"rank":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.rank.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"],"title":"NumericOperator","description":"'eq' (=), 'neq' (!=), 'gt' (>), 'gte' (>=), 'lt' (\u003c), 'lte' (\u003c=)","x-enumDescriptions":{"eq":"Equal to (=)","gt":"Greater than (>)","gte":"Greater than or equal to (>=)","lt":"Less than (\u003c)","lte":"Less than or equal to (\u003c=)","neq":"Not equal to (!=)"},"examples":["gte","lte","eq"],"isRequired":true,"uniqueKey":"filters.rank.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Numeric value to compare against (integer or float).","examples":[50,3,0.75],"uniqueKey":"filters.rank.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"NumericFilterCondition","description":"A single numeric filter condition for range-based filtering.\n\nOperators:\n- `eq` (=), `neq` (not equal), `gt` (>), `gte` (>=), `lt` (\u003c), `lte` (\u003c=)\n\nExample: {\"operator\": \"gte\", \"value\": 50}","uniqueKey":"filters.rank.\\items.items.[INDEX]","typeLabel":"NumericFilterCondition · object"},"type":"array","title":"Items","description":"List of numeric filter conditions to apply.","examples":[[{"operator":"gte","value":50}]],"uniqueKey":"filters.rank.\\items","typeLabel":"NumericFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"NumericFilterGroup","description":"Keep only answers where your brand is mentioned at this rank position (1-99, lower is better).","examples":[{"condition":"AND","items":[{"operator":"lte","value":3}]}],"uniqueKey":"filters.rank","typeLabel":"NumericFilterGroup · object"},"volume":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.volume.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"],"title":"NumericOperator","description":"'eq' (=), 'neq' (!=), 'gt' (>), 'gte' (>=), 'lt' (\u003c), 'lte' (\u003c=)","x-enumDescriptions":{"eq":"Equal to (=)","gt":"Greater than (>)","gte":"Greater than or equal to (>=)","lt":"Less than (\u003c)","lte":"Less than or equal to (\u003c=)","neq":"Not equal to (!=)"},"examples":["gte","lte","eq"],"isRequired":true,"uniqueKey":"filters.volume.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Numeric value to compare against (integer or float).","examples":[50,3,0.75],"uniqueKey":"filters.volume.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"NumericFilterCondition","description":"A single numeric filter condition for range-based filtering.\n\nOperators:\n- `eq` (=), `neq` (not equal), `gt` (>), `gte` (>=), `lt` (\u003c), `lte` (\u003c=)\n\nExample: {\"operator\": \"gte\", \"value\": 50}","uniqueKey":"filters.volume.\\items.items.[INDEX]","typeLabel":"NumericFilterCondition · object"},"type":"array","title":"Items","description":"List of numeric filter conditions to apply.","examples":[[{"operator":"gte","value":50}]],"uniqueKey":"filters.volume.\\items","typeLabel":"NumericFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"NumericFilterGroup","description":"Filter by prompt monthly search volume. Prompts without a known volume never match.","examples":[{"condition":"AND","items":[{"operator":"gte","value":1000}]}],"uniqueKey":"filters.volume","typeLabel":"NumericFilterGroup · object"},"website_mentioned_in_answer":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.website_mentioned_in_answer.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.website_mentioned_in_answer.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.website_mentioned_in_answer.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.website_mentioned_in_answer.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.website_mentioned_in_answer.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by a tracked website (your brand or a competitor) mentioned in the AI response body: website ID or domain. 'contains' matches a substring of the domain. A value that matches no tracked website selects nothing.","examples":[{"condition":"AND","items":[{"operator":"contains","value":"writesonic.com"}]}],"uniqueKey":"filters.website_mentioned_in_answer","typeLabel":"StringFilterGroup · object"},"cited_page_url":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.cited_page_url.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.cited_page_url.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.cited_page_url.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.cited_page_url.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.cited_page_url.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by cited page URL. Use 'contains' for partial matching.","examples":[{"condition":"AND","items":[{"operator":"contains","value":"/blog/"}]}],"uniqueKey":"filters.cited_page_url","typeLabel":"StringFilterGroup · object"},"cited_domain":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.cited_domain.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.cited_domain.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.cited_domain.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.cited_domain.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.cited_domain.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by cited domain name (e.g., 'writesonic.com').","examples":[{"condition":"AND","items":[{"operator":"is","value":"writesonic.com"}]}],"uniqueKey":"filters.cited_domain","typeLabel":"StringFilterGroup · object"},"website_mentioned_in_citation":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.website_mentioned_in_citation.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.website_mentioned_in_citation.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.website_mentioned_in_citation.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.website_mentioned_in_citation.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.website_mentioned_in_citation.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by a tracked website whose pages are cited: website ID or domain. 'contains' matches a substring of the domain. A value that matches no tracked website selects nothing.","examples":[{"condition":"AND","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"}]}],"uniqueKey":"filters.website_mentioned_in_citation","typeLabel":"StringFilterGroup · object"},"advanced_filters":{"properties":{"join":{"type":"string","enum":["and","or"],"title":"Join","description":"'and' = all children must match, 'or' = any child.","default":"and","uniqueKey":"filters.advanced_filters.join","typeLabel":"enum\u003cstring>"},"conditions":{"items":{"oneOf":[{},{"type":"object","title":"ReportFilterLeaf","description":"A single condition inside an `advanced_filters` tree.\n\nThe operator must fit the field: text/id fields take `is`, `is_not`,\n`contains`, `not_contains`; boolean fields (`branded`, `has_shopping_card`)\ntake `is`, `is_not` with true/false; numeric fields (`volume`, `sentiment`)\ntake `eq`, `neq`, `gt`, `gte`, `lt`, `lte` with a number. Anything else is\nrejected with 422 instead of being silently ignored.","required":["field","operator","value"],"properties":{"field":{"type":"string","enum":["topics","prompts","tags","markets","intent","branded","platform","has_shopping_card","website_mentioned_in_answer","cited_page_url","cited_domain","website_mentioned_in_citation","volume","sentiment"],"title":"ReportFilterField","description":"A filter field usable as a leaf inside `advanced_filters`.","isRequired":true,"uniqueKey":"filters.advanced_filters.conditions.items.[INDEX].oneOf.1.field","typeLabel":"enum\u003cstring>"},"operator":{"type":"string","title":"Operator","description":"'is' | 'is_not' | 'contains' | 'not_contains' for text/id fields; 'is' | 'is_not' for booleans; 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' for numeric fields (volume, sentiment).","isRequired":true,"uniqueKey":"filters.advanced_filters.conditions.items.[INDEX].oneOf.1.operator","typeLabel":"string"},"value":{"title":"Value","description":"The value to match against (required).","isRequired":true,"uniqueKey":"filters.advanced_filters.conditions.items.[INDEX].oneOf.1.value","typeLabel":"any"}},"additionalProperties":false,"uniqueKey":"filters.advanced_filters.conditions.items.[INDEX].oneOf.1","typeLabel":"ReportFilterLeaf · object"}],"uniqueKey":"filters.advanced_filters.conditions.items.[INDEX]","typeLabel":"ReportFilterLeaf · object"},"type":"array","title":"Conditions","description":"Child nodes: nested trees or leaf conditions. Empty = no advanced filter.","uniqueKey":"filters.advanced_filters.conditions","typeLabel":"ReportFilterLeaf · object[]"}},"additionalProperties":false,"type":"object","title":"ReportFilterTree","description":"Arbitrary AND/OR tree across any filter fields. When set, it takes precedence over the flat per-field filters above and is the only way to express cross-field OR, e.g. (topic is SEO) OR (platform is Grok).","examples":[{"conditions":[{"field":"topics","operator":"is","value":"\u003ctopic-id>"},{"field":"platform","operator":"is","value":"Grok"}],"join":"or"}],"uniqueKey":"filters.advanced_filters","typeLabel":"ReportFilterTree · object"},"status":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.status.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.status.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.status.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.status.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.status.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by query status (e.g. 'ACTIVE', 'PAUSED').","examples":[{"condition":"AND","items":[{"operator":"is","value":"ACTIVE"}]}],"uniqueKey":"filters.status","typeLabel":"StringFilterGroup · object"},"products":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.products.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.products.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.products.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.products.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.products.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by product / ad-creative ID or title.","examples":[{"condition":"AND","items":[{"operator":"contains","value":"running shoe"}]}],"uniqueKey":"filters.products","typeLabel":"StringFilterGroup · object"},"brands":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.brands.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.brands.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.brands.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.brands.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.brands.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by the website ID, name or URL of the brand that owns the product.","examples":[{"condition":"AND","items":[{"operator":"is","value":"Nike"}]}],"uniqueKey":"filters.brands","typeLabel":"StringFilterGroup · object"},"placement_type":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.placement_type.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.placement_type.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.placement_type.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.placement_type.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.placement_type.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by placement type (e.g. 'SHOPPING_CARD', 'AD_TEXT').","examples":[{"condition":"AND","items":[{"operator":"is","value":"SHOPPING_CARD"}]}],"uniqueKey":"filters.placement_type","typeLabel":"StringFilterGroup · object"},"source_type":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.source_type.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.source_type.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.source_type.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.source_type.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.source_type.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by brand ownership: 'owned', 'competitor', 'third_party', 'unconfigured'.","examples":[{"condition":"AND","items":[{"operator":"is","value":"owned"}]}],"uniqueKey":"filters.source_type","typeLabel":"StringFilterGroup · object"},"price":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.price.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"],"title":"NumericOperator","description":"'eq' (=), 'neq' (!=), 'gt' (>), 'gte' (>=), 'lt' (\u003c), 'lte' (\u003c=)","x-enumDescriptions":{"eq":"Equal to (=)","gt":"Greater than (>)","gte":"Greater than or equal to (>=)","lt":"Less than (\u003c)","lte":"Less than or equal to (\u003c=)","neq":"Not equal to (!=)"},"examples":["gte","lte","eq"],"isRequired":true,"uniqueKey":"filters.price.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Numeric value to compare against (integer or float).","examples":[50,3,0.75],"uniqueKey":"filters.price.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"NumericFilterCondition","description":"A single numeric filter condition for range-based filtering.\n\nOperators:\n- `eq` (=), `neq` (not equal), `gt` (>), `gte` (>=), `lt` (\u003c), `lte` (\u003c=)\n\nExample: {\"operator\": \"gte\", \"value\": 50}","uniqueKey":"filters.price.\\items.items.[INDEX]","typeLabel":"NumericFilterCondition · object"},"type":"array","title":"Items","description":"List of numeric filter conditions to apply.","examples":[[{"operator":"gte","value":50}]],"uniqueKey":"filters.price.\\items","typeLabel":"NumericFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"NumericFilterGroup","description":"Filter by quoted price on a purchase link.","examples":[{"condition":"AND","items":[{"operator":"lte","value":100}]}],"uniqueKey":"filters.price","typeLabel":"NumericFilterGroup · object"},"product_rank":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["AND"],"uniqueKey":"filters.product_rank.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"],"title":"NumericOperator","description":"'eq' (=), 'neq' (!=), 'gt' (>), 'gte' (>=), 'lt' (\u003c), 'lte' (\u003c=)","x-enumDescriptions":{"eq":"Equal to (=)","gt":"Greater than (>)","gte":"Greater than or equal to (>=)","lt":"Less than (\u003c)","lte":"Less than or equal to (\u003c=)","neq":"Not equal to (!=)"},"examples":["gte","lte","eq"],"isRequired":true,"uniqueKey":"filters.product_rank.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"Numeric value to compare against (integer or float).","examples":[50,3,0.75],"uniqueKey":"filters.product_rank.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"NumericFilterCondition","description":"A single numeric filter condition for range-based filtering.\n\nOperators:\n- `eq` (=), `neq` (not equal), `gt` (>), `gte` (>=), `lt` (\u003c), `lte` (\u003c=)\n\nExample: {\"operator\": \"gte\", \"value\": 50}","uniqueKey":"filters.product_rank.\\items.items.[INDEX]","typeLabel":"NumericFilterCondition · object"},"type":"array","title":"Items","description":"List of numeric filter conditions to apply.","examples":[[{"operator":"gte","value":50}]],"uniqueKey":"filters.product_rank.\\items","typeLabel":"NumericFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"NumericFilterGroup","description":"Filter by the placement's position within the answer (lower is better).","examples":[{"condition":"AND","items":[{"operator":"lte","value":3}]}],"uniqueKey":"filters.product_rank","typeLabel":"NumericFilterGroup · object"},"advertisers":{"properties":{"condition":{"type":"string","enum":["AND","OR"],"title":"FilterConditionType","description":"'AND' (all conditions must match, default) or 'OR' (any condition can match).","x-enumDescriptions":{"AND":"All conditions must match (intersection)","OR":"Any condition can match (union)"},"default":"AND","examples":["OR"],"uniqueKey":"filters.advertisers.condition","typeLabel":"enum\u003cstring>"},"items":{"items":{"properties":{"operator":{"type":"string","enum":["is","is_not","contains","not_contains"],"title":"StringOperator","description":"'is' (exact match), 'is_not' (exclude), 'contains' (partial, case-insensitive), 'not_contains' (exclude partial)","x-enumDescriptions":{"contains":"Partial text match (case-insensitive). Value is matched using ILIKE","is":"Exact match. If value is a UUID, matches by ID; otherwise matches by name/text","is_not":"Exclude exact match. Inverse of 'is'","not_contains":"Exclude partial text match. Inverse of 'contains'"},"examples":["is","contains"],"isRequired":true,"uniqueKey":"filters.advertisers.\\items.items.[INDEX].operator","typeLabel":"enum\u003cstring>"},"value":{"title":"Value","description":"An entity ID for exact matching, or text for name/content matching. Partial matching with 'contains' is case-insensitive.","examples":["550e8400-e29b-41d4-a716-446655440000","AI Tools"],"uniqueKey":"filters.advertisers.\\items.items.[INDEX].value","typeLabel":"any"}},"additionalProperties":false,"type":"object","required":["operator"],"title":"StringFilterCondition","description":"A single text filter condition.\n\nOperators:\n- `is` — Exact match by ID or name.\n- `is_not` — Exclude exact match.\n- `contains` — Partial text match (case-insensitive).\n- `not_contains` — Exclude partial text match.\n\nExample: {\"operator\": \"is\", \"value\": \"\u003ctopic-id>\"}\nExample: {\"operator\": \"contains\", \"value\": \"AI Tools\"}","uniqueKey":"filters.advertisers.\\items.items.[INDEX]","typeLabel":"StringFilterCondition · object"},"type":"array","title":"Items","description":"List of filter conditions to apply.","examples":[[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]],"uniqueKey":"filters.advertisers.\\items","typeLabel":"StringFilterCondition · object[]"}},"additionalProperties":false,"type":"object","title":"StringFilterGroup","description":"Filter by advertiser website ID, name or URL.","examples":[{"condition":"AND","items":[{"operator":"contains","value":"shopify"}]}],"uniqueKey":"filters.advertisers","typeLabel":"StringFilterGroup · object"}},"additionalProperties":false,"type":"object","title":"AdsFiltersInput","description":"Narrow results by topics, markets, advertisers, placement type, etc. All filters combine with AND logic.","uniqueKey":"filters","typeLabel":"AdsFiltersInput · object"},"date_aggregation_interval":{"type":"string","enum":["day","week","month"],"title":"DateAggregationInterval","description":"Optional. When using the 'date' dimension, controls time-series bucket size. Defaults to 'day'.","x-enumDescriptions":{"day":"Daily aggregation","month":"Monthly aggregation","week":"Weekly aggregation"},"examples":["week","month"],"uniqueKey":"date_aggregation_interval","typeLabel":"enum\u003cstring>"},"website_type":{"type":"string","enum":["SELF","SELF+COMPETITORS","ALL"],"title":"WebsiteType","description":"Scope results by brand ownership. 'SELF' = your brand only, 'SELF+COMPETITORS' = plus competitors, 'ALL' = including untracked third-party brands.","x-enumDescriptions":{"ALL":"All citations with no domain filtering applied","SELF":"Your brand's tracked domains only","SELF+COMPETITORS":"Your brand plus competitor tracked domains"},"examples":["SELF+COMPETITORS"],"uniqueKey":"website_type","typeLabel":"enum\u003cstring>"}},"additionalProperties":false,"type":"object","required":["project_id","dimensions"],"title":"AdsReportRequest","description":"Request parameters for the Ads Report API.","uniqueKey":"","typeLabel":"AdsReportRequest · object"},"examples":{"Example":{"title":"Example","value":{"project_id":"550e8400-e29b-41d4-a716-446655440000","dimensions":["website"],"start_date":"2026-01-01T00:00:00Z","end_date":"2026-01-31T23:59:59Z","current_from":"2023-11-07T05:31:56Z","current_to":"2023-11-07T05:31:56Z","comparison_start_date":"2026-07-25T00:00:00Z","comparison_end_date":"2026-07-31T23:59:59Z","previous_from":"2023-11-07T05:31:56Z","previous_to":"2023-11-07T05:31:56Z","order_by":[{"field":"visibility_score","order":"desc"}],"pagination":{"limit":10,"offset":0},"measures":["ad_visibility","share_of_ad_placements"],"filters":{"topics":{"condition":"OR","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"},{"operator":"contains","value":"SEO"}]},"prompts":{"condition":"AND","items":[{"operator":"contains","value":"best AI tools"}]},"tags":{"condition":"OR","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"}]},"markets":{"condition":"OR","items":[{"operator":"is","value":"United States"},{"operator":"is","value":"United Kingdom"}]},"intent":{"condition":"OR","items":[{"operator":"is","value":"informational"},{"operator":"is","value":"commercial"}]},"branded":{"condition":"AND","items":[{"operator":"is","value":false}]},"platform":{"condition":"OR","items":[{"operator":"is","value":"ChatGPT"},{"operator":"is","value":"Perplexity"}]},"has_shopping_card":{"condition":"AND","items":[{"operator":"is","value":true}]},"has_ads_data":{"condition":"AND","items":[{"operator":"is","value":true}]},"visibility":{"condition":"AND","items":[{"operator":"gte","value":50}]},"rank":{"condition":"AND","items":[{"operator":"lte","value":3}]},"volume":{"condition":"AND","items":[{"operator":"gte","value":1000}]},"website_mentioned_in_answer":{"condition":"AND","items":[{"operator":"contains","value":"writesonic.com"}]},"cited_page_url":{"condition":"AND","items":[{"operator":"contains","value":"/blog/"}]},"cited_domain":{"condition":"AND","items":[{"operator":"is","value":"writesonic.com"}]},"website_mentioned_in_citation":{"condition":"AND","items":[{"operator":"is","value":"550e8400-e29b-41d4-a716-446655440000"}]},"advanced_filters":{"conditions":[{"field":"topics","operator":"is","value":"\u003ctopic-id>"},{"field":"platform","operator":"is","value":"Grok"}],"join":"or"},"status":{"condition":"AND","items":[{"operator":"is","value":"ACTIVE"}]},"products":{"condition":"AND","items":[{"operator":"contains","value":"running shoe"}]},"brands":{"condition":"AND","items":[{"operator":"is","value":"Nike"}]},"placement_type":{"condition":"AND","items":[{"operator":"is","value":"SHOPPING_CARD"}]},"source_type":{"condition":"AND","items":[{"operator":"is","value":"owned"}]},"price":{"condition":"AND","items":[{"operator":"lte","value":100}]},"product_rank":{"condition":"AND","items":[{"operator":"lte","value":3}]},"advertisers":{"condition":"AND","items":[{"operator":"contains","value":"shopify"}]}},"date_aggregation_interval":"week","website_type":"SELF+COMPETITORS"}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"51f7722b-eeb6-4575-b887-bddee5c46b34":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"info":{"properties":{"total_rows":{"type":"integer","title":"Total Rows","description":"Total number of rows matching the query (before pagination)","isRequired":true,"uniqueKey":"info.total_rows","typeLabel":"integer"},"query":{"properties":{"metrics":{"items":{"type":"string","uniqueKey":"info.query.metrics.items.[INDEX]","typeLabel":"string"},"type":"array","title":"Metrics","description":"Metrics that were requested","isRequired":true,"uniqueKey":"info.query.metrics","typeLabel":"string[]"},"start_date":{"type":"string","format":"date-time","title":"Start Date","description":"Start date used in the query","isRequired":true,"uniqueKey":"info.query.start_date","typeLabel":"string\u003cdate-time>"},"end_date":{"type":"string","format":"date-time","title":"End Date","description":"End date used in the query","isRequired":true,"uniqueKey":"info.query.end_date","typeLabel":"string\u003cdate-time>"},"order_by":{"additionalProperties":{"type":"string","uniqueKey":"info.query.order_by.additionalProperties","typeLabel":"string"},"type":"object","title":"Order By","description":"Sorting applied to the results","isRequired":true,"uniqueKey":"info.query.order_by","typeLabel":"Order By · object"},"pagination":{"additionalProperties":{"type":"integer","uniqueKey":"info.query.pagination.additionalProperties","typeLabel":"integer"},"type":"object","title":"Pagination","description":"Pagination parameters used","isRequired":true,"uniqueKey":"info.query.pagination","typeLabel":"Pagination · object"},"filters":{"additionalProperties":false,"type":"object","title":"Filters","description":"Filters that were applied","isRequired":true,"uniqueKey":"info.query.filters","typeLabel":"Filters · object"},"comparison_start_date":{"type":"string","format":"date-time","title":"Comparison Start Date","description":"Start date of the comparison range, if requested","uniqueKey":"info.query.comparison_start_date","typeLabel":"string\u003cdate-time>"},"comparison_end_date":{"type":"string","format":"date-time","title":"Comparison End Date","description":"End date of the comparison range, if requested","uniqueKey":"info.query.comparison_end_date","typeLabel":"string\u003cdate-time>"}},"type":"object","required":["metrics","start_date","end_date","order_by","pagination","filters"],"title":"QueryInfo","description":"Details of the query that produced this response","isRequired":true,"uniqueKey":"info.query","typeLabel":"QueryInfo · object"}},"type":"object","required":["total_rows","query"],"title":"ResponseInfo","description":"Information of the API request including total count and query details","uniqueKey":"info","typeLabel":"ResponseInfo · object"},"data":{"items":{"properties":{"topic_id":{"type":"string","title":"Topic Id","description":"Unique identifier of the topic","uniqueKey":"data.items.[INDEX].topic_id","typeLabel":"string"},"topic_name":{"type":"string","title":"Topic Name","description":"Display name of the topic","uniqueKey":"data.items.[INDEX].topic_name","typeLabel":"string"},"tag_id":{"type":"string","title":"Tag Id","description":"Unique identifier of the tag","uniqueKey":"data.items.[INDEX].tag_id","typeLabel":"string"},"tag_name":{"type":"string","title":"Tag Name","description":"Display name of the tag","uniqueKey":"data.items.[INDEX].tag_name","typeLabel":"string"},"market_id":{"type":"string","title":"Market Id","description":"Unique identifier of the market/region","uniqueKey":"data.items.[INDEX].market_id","typeLabel":"string"},"market_name":{"type":"string","title":"Market Name","description":"Display name of the market","uniqueKey":"data.items.[INDEX].market_name","typeLabel":"string"},"model_id":{"type":"string","title":"Model Id","description":"Unique identifier of the AI model","uniqueKey":"data.items.[INDEX].model_id","typeLabel":"string"},"model_name":{"type":"string","title":"Model Name","description":"Display name of the AI model","uniqueKey":"data.items.[INDEX].model_name","typeLabel":"string"},"query_id":{"type":"string","title":"Query Id","description":"Unique identifier of the query/prompt","uniqueKey":"data.items.[INDEX].query_id","typeLabel":"string"},"query_name":{"type":"string","title":"Query Name","description":"The actual query text","uniqueKey":"data.items.[INDEX].query_name","typeLabel":"string"},"date":{"type":"string","title":"Date","description":"Date bucket for time-series data (ISO format)","uniqueKey":"data.items.[INDEX].date","typeLabel":"string"},"website_id":{"type":"string","title":"Website Id","description":"Unique identifier of the brand that owns the product; null for untracked third-party brands","uniqueKey":"data.items.[INDEX].website_id","typeLabel":"string"},"website_name":{"type":"string","title":"Website Name","description":"Display name of the owning brand; empty string for untracked third-party brands","uniqueKey":"data.items.[INDEX].website_name","typeLabel":"string"},"branded":{"type":"boolean","title":"Branded","description":"When grouping by `branded`: true = branded queries, false = non-branded","uniqueKey":"data.items.[INDEX].branded","typeLabel":"boolean"},"product_id":{"type":"string","title":"Product Id","description":"Unique identifier of the product / ad creative","uniqueKey":"data.items.[INDEX].product_id","typeLabel":"string"},"product_name":{"type":"string","title":"Product Name","description":"Title of the product / ad creative","uniqueKey":"data.items.[INDEX].product_name","typeLabel":"string"},"product_image":{"type":"string","title":"Product Image","description":"Primary product image URL (when grouping by `product`)","uniqueKey":"data.items.[INDEX].product_image","typeLabel":"string"},"product_link":{"type":"string","title":"Product Link","description":"Product page URL (when grouping by `product`)","uniqueKey":"data.items.[INDEX].product_link","typeLabel":"string"},"brand_id":{"type":"string","title":"Brand Id","description":"Website id the product belongs to (when grouping by `product`)","uniqueKey":"data.items.[INDEX].brand_id","typeLabel":"string"},"brand_name":{"type":"string","title":"Brand Name","description":"Brand website name","uniqueKey":"data.items.[INDEX].brand_name","typeLabel":"string"},"brand_url":{"type":"string","title":"Brand Url","description":"Brand website URL","uniqueKey":"data.items.[INDEX].brand_url","typeLabel":"string"},"brand_logo":{"type":"string","title":"Brand Logo","description":"Brand website logo URL","uniqueKey":"data.items.[INDEX].brand_logo","typeLabel":"string"},"brand_is_self":{"type":"boolean","title":"Brand Is Self","description":"True when the product belongs to your own brand","uniqueKey":"data.items.[INDEX].brand_is_self","typeLabel":"boolean"},"product_source_type":{"type":"string","title":"Product Source Type","description":"owned | competitor | third_party | unconfigured, by the product's brand website","uniqueKey":"data.items.[INDEX].product_source_type","typeLabel":"string"},"placement_type":{"type":"string","title":"Placement Type","description":"Placement type (e.g. 'SHOPPING_CARD', 'AD_TEXT', 'AD_SHOPPING')","uniqueKey":"data.items.[INDEX].placement_type","typeLabel":"string"},"advertiser_id":{"type":"string","title":"Advertiser Id","description":"Unique identifier of the advertiser","uniqueKey":"data.items.[INDEX].advertiser_id","typeLabel":"string"},"advertiser_name":{"type":"string","title":"Advertiser Name","description":"Display name of the advertiser","uniqueKey":"data.items.[INDEX].advertiser_name","typeLabel":"string"},"advertiser_url":{"type":"string","title":"Advertiser Url","description":"Advertiser website URL","uniqueKey":"data.items.[INDEX].advertiser_url","typeLabel":"string"},"advertiser_logo":{"type":"string","title":"Advertiser Logo","description":"Advertiser logo URL","uniqueKey":"data.items.[INDEX].advertiser_logo","typeLabel":"string"},"advertiser_is_self":{"type":"boolean","title":"Advertiser Is Self","description":"True when the advertiser is your own website","uniqueKey":"data.items.[INDEX].advertiser_is_self","typeLabel":"boolean"},"ad_visibility":{"type":"number","title":"Ad Visibility","description":"Percentage of ad-bearing answers featuring this entity (0-100)","uniqueKey":"data.items.[INDEX].ad_visibility","typeLabel":"number"},"share_of_ad_placements":{"type":"number","title":"Share Of Ad Placements","description":"This entity's placements as a percentage of all tracked-brand ad placements in the group (0-100)","uniqueKey":"data.items.[INDEX].share_of_ad_placements","typeLabel":"number"},"ad_placements":{"type":"integer","title":"Ad Placements","description":"Number of distinct answers in which this entity's ad appeared","uniqueKey":"data.items.[INDEX].ad_placements","typeLabel":"integer"},"ad_answers":{"type":"integer","title":"Ad Answers","description":"Total answers in the group containing at least one ad placement","uniqueKey":"data.items.[INDEX].ad_answers","typeLabel":"integer"},"placements_with_self_brand":{"type":"integer","title":"Placements With Self Brand","description":"Ad placements promoting your own brand's product","uniqueKey":"data.items.[INDEX].placements_with_self_brand","typeLabel":"integer"},"unique_advertisers":{"type":"integer","title":"Unique Advertisers","description":"Number of distinct advertisers","uniqueKey":"data.items.[INDEX].unique_advertisers","typeLabel":"integer"},"unique_ad_creatives":{"type":"integer","title":"Unique Ad Creatives","description":"Number of distinct ad creatives","uniqueKey":"data.items.[INDEX].unique_ad_creatives","typeLabel":"integer"},"ad_rank":{"type":"number","title":"Ad Rank","description":"Average position of the ad within the answer (lower is better)","uniqueKey":"data.items.[INDEX].ad_rank","typeLabel":"number"},"avg_quoted_price":{"type":"number","title":"Avg Quoted Price","description":"Average quoted price across ad purchase links","uniqueKey":"data.items.[INDEX].avg_quoted_price","typeLabel":"number"},"avg_quoted_price_currency":{"type":"string","title":"Avg Quoted Price Currency","description":"Currency of avg_quoted_price (e.g. 'USD')","uniqueKey":"data.items.[INDEX].avg_quoted_price_currency","typeLabel":"string"},"previous_ad_visibility":{"type":"number","title":"Previous Ad Visibility","description":"ad_visibility over the comparison date range (present only when a comparison range was requested)","uniqueKey":"data.items.[INDEX].previous_ad_visibility","typeLabel":"number"},"previous_share_of_ad_placements":{"type":"number","title":"Previous Share Of Ad Placements","description":"share_of_ad_placements over the comparison date range","uniqueKey":"data.items.[INDEX].previous_share_of_ad_placements","typeLabel":"number"},"previous_ad_placements":{"type":"integer","title":"Previous Ad Placements","description":"ad_placements over the comparison date range","uniqueKey":"data.items.[INDEX].previous_ad_placements","typeLabel":"integer"},"previous_ad_answers":{"type":"integer","title":"Previous Ad Answers","description":"ad_answers over the comparison date range","uniqueKey":"data.items.[INDEX].previous_ad_answers","typeLabel":"integer"},"previous_placements_with_self_brand":{"type":"integer","title":"Previous Placements With Self Brand","description":"placements_with_self_brand over the comparison date range","uniqueKey":"data.items.[INDEX].previous_placements_with_self_brand","typeLabel":"integer"},"previous_unique_advertisers":{"type":"integer","title":"Previous Unique Advertisers","description":"unique_advertisers over the comparison date range","uniqueKey":"data.items.[INDEX].previous_unique_advertisers","typeLabel":"integer"},"previous_unique_ad_creatives":{"type":"integer","title":"Previous Unique Ad Creatives","description":"unique_ad_creatives over the comparison date range","uniqueKey":"data.items.[INDEX].previous_unique_ad_creatives","typeLabel":"integer"},"previous_ad_rank":{"type":"number","title":"Previous Ad Rank","description":"ad_rank over the comparison date range","uniqueKey":"data.items.[INDEX].previous_ad_rank","typeLabel":"number"},"previous_avg_quoted_price":{"type":"number","title":"Previous Avg Quoted Price","description":"avg_quoted_price over the comparison date range","uniqueKey":"data.items.[INDEX].previous_avg_quoted_price","typeLabel":"number"}},"type":"object","title":"AdsDataRow","description":"A single row of ads report data.","uniqueKey":"data.items.[INDEX]","typeLabel":"AdsDataRow · object"},"type":"array","title":"Data","description":"Array of ad data rows grouped by the requested dimensions","uniqueKey":"data","typeLabel":"AdsDataRow · object[]"}},"type":"object","title":"AdsReportResponse","description":"Response containing ads report data.","uniqueKey":"","typeLabel":"AdsReportResponse · object"},"examples":{"Example":{"title":"Example","value":{"info":{"total_rows":123,"query":{"metrics":["\u003cstring>"],"start_date":"2023-11-07T05:31:56Z","end_date":"2023-11-07T05:31:56Z","order_by":{},"pagination":{},"filters":{},"comparison_start_date":"2023-11-07T05:31:56Z","comparison_end_date":"2023-11-07T05:31:56Z"}},"data":[{"topic_id":"\u003cstring>","topic_name":"\u003cstring>","tag_id":"\u003cstring>","tag_name":"\u003cstring>","market_id":"\u003cstring>","market_name":"\u003cstring>","model_id":"\u003cstring>","model_name":"\u003cstring>","query_id":"\u003cstring>","query_name":"\u003cstring>","date":"\u003cstring>","website_id":"\u003cstring>","website_name":"\u003cstring>","branded":true,"product_id":"\u003cstring>","product_name":"\u003cstring>","product_image":"\u003cstring>","product_link":"\u003cstring>","brand_id":"\u003cstring>","brand_name":"\u003cstring>","brand_url":"\u003cstring>","brand_logo":"\u003cstring>","brand_is_self":true,"product_source_type":"\u003cstring>","placement_type":"\u003cstring>","advertiser_id":"\u003cstring>","advertiser_name":"\u003cstring>","advertiser_url":"\u003cstring>","advertiser_logo":"\u003cstring>","advertiser_is_self":true,"ad_visibility":123,"share_of_ad_placements":123,"ad_placements":123,"ad_answers":123,"placements_with_self_brand":123,"unique_advertisers":123,"unique_ad_creatives":123,"ad_rank":123,"avg_quoted_price":123,"avg_quoted_price_currency":"\u003cstring>","previous_ad_visibility":123,"previous_share_of_ad_placements":123,"previous_ad_placements":123,"previous_ad_answers":123,"previous_placements_with_self_brand":123,"previous_unique_advertisers":123,"previous_unique_ad_creatives":123,"previous_ad_rank":123,"previous_avg_quoted_price":123}]}}},"exampleType":"generated"}},"exampleType":"generated"},"e87de02c-86d1-42fb-a6a4-134a8981699c":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"},"input":{"oneOf":[{"title":"Input"}],"uniqueKey":"detail.items.[INDEX].input","typeLabel":"any"},"ctx":{"type":"object","title":"Context","uniqueKey":"detail.items.[INDEX].ctx","typeLabel":"Context · object"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>","input":"\u003cunknown>","ctx":{}}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"3bf10f38-a770-4694-a534-e8a0dc2445c3":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[],"schemeName":"APIKeyHeader"}}},"servers":{"9c01b566-187d-43fe-b854-b1240f8f9075":{"url":"https://api.writesonic.com","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"X-API-KEY","scopes":[],"schemeName":"APIKeyHeader"},"schema":{"title":"X-API-KEY","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"APIKeyHeader","name":"X-API-KEY"}],"title":"APIKeyHeader"}]},"originalFileLocation":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD"},"subdomain":"writesonic","siteName":"Writesonic Docs","title":"Get Ads Report - Writesonic Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-05T05:22:48.058Z","originalFileLocation":"api-reference/reports/get-ads-report.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: \u0026quot;Which advertisers bid against my brand, by topic?\u0026quot; Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard\u0026#x27;s Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser\u0026#x27;s placements / all tracked advertisers\u0026#x27; placements, the definition behind the Ads dashboard KPI card. The dashboard\u0026#x27;s Advertisers table labels ad_placements / ad_answers as \u0026quot;share of ad placements\u0026quot;; that column is ad_visibility here - ad_placements counts distinct answers in which the entity\u0026#x27;s ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_ fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values. Filter values: markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Writesonic Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Get Ads Report - Writesonic Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: \u0026quot;Which advertisers bid against my brand, by topic?\u0026quot; Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard\u0026#x27;s Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser\u0026#x27;s placements / all tracked advertisers\u0026#x27; placements, the definition behind the Ads dashboard KPI card. The dashboard\u0026#x27;s Advertisers table labels ad_placements / ad_answers as \u0026quot;share of ad placements\u0026quot;; that column is ad_visibility here - ad_placements counts distinct answers in which the entity\u0026#x27;s ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_ fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values. Filter values: markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Writesonic Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://writesonic.mintlify.site/_mintlify/api/og/v2?division=Reports\u0026amp;title=Get+Ads+Report\u0026amp;description=Sponsored-placement+metrics+grouped+by+one+or+more+dimensions.+This+is+the+report+behind+the%0AUI+Ads+screen+%E2%80%94+use+it+for+ad+visibility%2C+share+of+ad+placements+an\u0026amp;theme=a19733924f789986a692f3c4\u0026amp;signature=378e46dec978c4d522644ff73ab32c92e0c57df60a8fea676c05ce1f3129449d\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Get Ads Report - Writesonic Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: \u0026quot;Which advertisers bid against my brand, by topic?\u0026quot; Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard\u0026#x27;s Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser\u0026#x27;s placements / all tracked advertisers\u0026#x27; placements, the definition behind the Ads dashboard KPI card. The dashboard\u0026#x27;s Advertisers table labels ad_placements / ad_answers as \u0026quot;share of ad placements\u0026quot;; that column is ad_visibility here - ad_placements counts distinct answers in which the entity\u0026#x27;s ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_ fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values. Filter values: markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://writesonic.mintlify.site/_mintlify/api/og/v2?division=Reports\u0026amp;title=Get+Ads+Report\u0026amp;description=Sponsored-placement+metrics+grouped+by+one+or+more+dimensions.+This+is+the+report+behind+the%0AUI+Ads+screen+%E2%80%94+use+it+for+ad+visibility%2C+share+of+ad+placements+an\u0026amp;theme=a19733924f789986a692f3c4\u0026amp;signature=378e46dec978c4d522644ff73ab32c92e0c57df60a8fea676c05ce1f3129449d\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/writesonic/MlW01xdJYx4ttlxz/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Writesonic Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#FF6719\">\u003clink data-mint-head rel=\"canonical\" href=\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/reports/get-ads-report.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://apidocs.writesonic.com/#organization\",\"name\":\"Writesonic Docs\",\"url\":\"https://apidocs.writesonic.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/writesonic/pJXgH59hJ3fQBw5s/images/logo/logo-light.svg?fit=max\u0026auto=format\u0026n=pJXgH59hJ3fQBw5s\u0026q=85\u0026s=12c1c23ddbb7e4ef1e6a1243503b4114\"}},{\"@type\":\"WebSite\",\"@id\":\"https://apidocs.writesonic.com#website\",\"name\":\"Writesonic Docs\",\"url\":\"https://apidocs.writesonic.com\",\"publisher\":{\"@id\":\"https://apidocs.writesonic.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report#webpage\",\"url\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report\",\"name\":\"Get Ads Report\",\"description\":\"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: \\\"Which advertisers bid against my brand, by topic?\\\" Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard's Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels ad_placements / ad_answers as \\\"share of ad placements\\\"; that column is ad_visibility here - ad_placements counts distinct answers in which the entity's ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_ fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values. Filter values: markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.\",\"dateModified\":\"2026-11-05T05:22:48.058Z\",\"isPartOf\":{\"@id\":\"https://apidocs.writesonic.com#website\"},\"breadcrumb\":{\"@id\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Reports\",\"item\":\"https://apidocs.writesonic.com/api-reference/reports/get-performance-report\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Get Ads Report\",\"item\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report#apireference\",\"headline\":\"Get Ads Report\",\"name\":\"Get Ads Report\",\"description\":\"Sponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: \\\"Which advertisers bid against my brand, by topic?\\\" Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard's Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels ad_placements / ad_answers as \\\"share of ad placements\\\"; that column is ad_visibility here - ad_placements counts distinct answers in which the entity's ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_ fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values. Filter values: markets takes a market id or contains with a region code such as us (names like United States and labels like us - en match nothing); tags, topics and platform match by name or id. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). Notes: Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). AD_SHOPPING placements count in both this report and the other one, so shopping and ad totals are not additive.\",\"url\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report\",\"mainEntityOfPage\":{\"@id\":\"https://apidocs.writesonic.com/api-reference/reports/get-ads-report#webpage\"},\"dateModified\":\"2026-11-05T05:22:48.058Z\",\"publisher\":{\"@id\":\"https://apidocs.writesonic.com/#organization\"},\"isPartOf\":{\"@id\":\"https://apidocs.writesonic.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Writesonic Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Writesonic Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/reports/get-ads-report.md","siteName":"Writesonic Docs","nav":{"global":{"anchors":[{"anchor":"Open Writesonic","icon":"arrow-up-right-from-square","href":"https://app.writesonic.com/?utm_source=docs"},{"anchor":"Book a demo","icon":"headset","href":"https://writesonic.com/?demo=open"}]},"tabs":[{"tab":"Platform","icon":"book-open","pages":[{"title":"Platform","href":"/docs/geo-getting-started"}]},{"tab":"Agents","icon":"sparkles","pages":[{"title":"Agents","href":"/agents/overview"}]},{"tab":"Writesonic REST API","icon":"square-terminal","groups":[{"group":"Getting Started","pages":[{"title":"Authentication","href":"/api-reference/authentication"}]},{"group":"Generic","pages":[{"title":"Get All Projects","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/projects","href":"/api-reference/generic/get-all-projects"},{"title":"Get All Prompts","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/prompts","href":"/api-reference/generic/get-all-prompts"},{"title":"Get All Topics","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/topics","href":"/api-reference/generic/get-all-topics"},{"title":"Get Tags","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/tags","href":"/api-reference/generic/get-tags"},{"title":"Get All Citations","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/citations","href":"/api-reference/generic/get-all-citations"},{"title":"Get Websites","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/websites","href":"/api-reference/generic/get-websites"},{"title":"Get Keywords","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/keywords","href":"/api-reference/generic/get-keywords"},{"title":"Get AI Models","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/models","href":"/api-reference/generic/get-ai-models"},{"title":"Get Markets","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/markets","href":"/api-reference/generic/get-markets"},{"title":"Get Domain Reports","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/business/domains","href":"/api-reference/generic/get-domain-reports"}]},{"group":"Reports","pages":[{"title":"Get Performance Report","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/performance","href":"/api-reference/reports/get-performance-report"},{"title":"Get Citation Report","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/citations","href":"/api-reference/reports/get-citation-report"},{"title":"Get Sentiment Report","description":"Keyword sentiment metrics grouped by one or more dimensions.\n\n**Example:** \"Show positive keyword trends by topic, broken down monthly.\"\n\n**Dimensions** (at least 1 required): `topic`, `tag`, `market`, `model`, `query`, `date`, `website`, `shopping`, `ads`, `branded`, `persona`, `intent_stage`, `locality`, `search_intent`, `theme`, `subtheme`, `keyword`\n- `date` supports optional `date_aggregation_interval`: `day` (default) | `week` | `month`\n- `website` auto-sets `website_type` to `SELF+COMPETITORS` (default is `SELF`)\n- `website` rows carry `website_url`, `website_logo` and `is_self` (true for your own brand) alongside `website_id` / `website_name`\n- `persona` / `intent_stage` / `locality` group by the prompt targets attached to each query; a query with several targets of one type counts once per target (like `tag`), and untargeted queries land in a null bucket\n- `search_intent` is the query's dominant intent: `transactional`, `navigational`, `informational` or `commercial`\n- Dimensions not listed here are rejected with 400\n- `theme`, `subtheme`, `keyword` group keyword occurrences by the sentiment taxonomy; `theme` / `subtheme` only cover classified keywords (occurrences whose keyword has no subtheme are excluded), `keyword` covers every keyword\n- keywords belong to the brand they were mined for, so `website_type` scopes them: the default `SELF` counts your own brand's keywords only, `SELF+COMPETITORS` and `ALL` add the tracked competitors'\n\n**Measures** (omit for all): `total_keyword_occurrences`, `total_positive_keyword_occurrences`, `unique_positive_keywords`, `total_unique_keywords`\n\n**Filters:** `topics`, `prompts`, `tags`, `markets`, `intent`, `branded`, `platform`, `has_shopping_card`, `volume`, `visibility`, `rank`, `website_mentioned_in_answer`, `cited_page_url`, `cited_domain`, `website_mentioned_in_citation`, `status`.\n- `volume` is numeric (`eq`/`neq`/`gt`/`gte`/`lt`/`lte`) on the prompt's monthly search volume; prompts without a known volume never match\n- `rank` / `visibility` are numeric and keep only answers where your brand's mention matches (e.g. `rank lte 3` = answers where you rank top 3)\n- `sentiment` (this report only) is numeric on the keyword sentiment score (0-100) and keeps only matching keyword occurrences, so every measure is computed over them (e.g. `gte 70` = positive keywords only). As an `advanced_filters` leaf it instead keeps answers containing at least one matching keyword\n\n**Sort fields:** Any measure name, plus `date`, `search_intent`, `theme_name`, `subtheme_name`, `keyword_name`. Other dimension names (query, website, topic, market, model, tag, persona, intent stage, locality) are rejected with 422; sort the returned rows yourself. `pct_positive` and `sentiment` are not sortable here either.\n\n**Dates:** If no dates provided, defaults to latest run date range. Provide `start_date` and `end_date` in ISO 8601 format to specify a custom range.\n\n**Comparison:** Provide `comparison_start_date` and `comparison_end_date` (ISO 8601, both required together) to also compute every measure over a past range — each row then gains `previous_\u003cmeasure>` fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the `date` dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\n\n**Filter values:** `markets` takes a market id or `contains` with a region code such as `us` (names like `United States` and labels like `us - en` match nothing); `tags`, `topics` and `platform` match by name or id.\n\n**Pagination:** Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting.\n\n**Response:** Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters).","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/sentiments","href":"/api-reference/reports/get-sentiment-report"},{"title":"Get Ads Report","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/ads","href":"/api-reference/reports/get-ads-report"},{"title":"Get Shopping Report","description":"Shopping-placement metrics grouped by one or more dimensions. This is the report behind the\nUI Shopping screen — use it for shopping visibility, direct-link share, product rank and\nper-product or per-merchant breakdowns. `/reports/performance` cannot produce these.\n\n**Example:** \"Which merchants carry purchase links for my products, by topic?\"\n\n**Dimensions** (at least 1 required): `topic`, `tag`, `market`, `model`, `query`, `date`, `website`, `branded`, `product`, `placement_type`, `merchant`\n- `product` rows also carry `product_image`, `product_link`, `brand_id` / `brand_name` / `brand_url` / `brand_logo`, `brand_is_self` and `product_source_type` (owned | competitor | third_party | unconfigured); `merchant` rows carry `merchant_url`, `merchant_logo`, `merchant_is_self`\n- `date` supports optional `date_aggregation_interval`: `day` (default) | `week` | `month`; buckets on the placement date\n- `website` is the brand that owns the product, and auto-sets `website_type` to `SELF+COMPETITORS`; `product` / `merchant` auto-set it to `ALL`, like the dashboard's All Products / Merchants pages (default otherwise is `SELF`)\n- `website_type: ALL` also returns untracked third-party brands, with a null `website_id` and an empty `website_name`\n\n**Measures** (omit for all): `shopping_visibility`, `direct_link_share`, `share_of_shopping_voice`, `product_rank`, `answers_with_product`, `product_mentions`, `shopping_answers`, `unique_products`, `unique_merchants`, `buy_link_count`, `buy_link_share`, `avg_price`\n- `shopping_visibility` = answers featuring this entity / `shopping_answers` (all answers in the group holding any shopping placement)\n- `direct_link_share` = this entity's placements whose purchase link points back at the product's own brand, over its own placements\n- `share_of_shopping_voice` = this brand's placements / all tracked brands' placements — placements, not answers, so a brand with three product cards in one answer counts three, as on the dashboard's Share of Voice chart\n- `avg_price` also returns `avg_price_currency`\n\n**Filters:** `topics`, `prompts`, `tags`, `markets`, `intent`, `branded`, `platform`, `website_mentioned_in_answer`, `cited_page_url`, `cited_domain`, `website_mentioned_in_citation`, `products`, `brands`, `merchants`, `placement_type`, `source_type`, `price`, `product_rank`, `has_direct_link`.\n- `has_shopping_card`, `has_ads_data`, `visibility`, `rank` and `status` are accepted for compatibility with the other report endpoints and ignored here.\n- `platform` matches the model that produced the answer (stricter than `/reports/performance`, which matches prompts that ever ran on a platform).\n\n**Sort fields:** Any measure name, plus `date`, `query_name`, `topic_name`, `market_name`, `model_name`, `website_name`, `tag_name`, `product_name`, `merchant_name`, `placement_type`.\n\n**Dates:** If no dates provided, defaults to latest run date range. Provide `start_date` and `end_date` in ISO 8601 format to specify a custom range.\n\n**Comparison:** Provide `comparison_start_date` and `comparison_end_date` (ISO 8601, both required together) to also compute every measure over a past range — each row then gains `previous_\u003cmeasure>` fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the `date` dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_* values.\n\n**Filter values:** `markets` takes a market id or `contains` with a region code such as `us` (names like `United States` and labels like `us - en` match nothing); `tags`, `topics` and `platform` match by name or id.\n\n**Pagination:** Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting.\n\n**Response:** Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters).\n\n**Notes:** Days with no placements are omitted rather than zero-filled. Grouping by `merchant`/`advertiser` fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive.","deprecated":null,"version":null,"openapi":"https://api.writesonic.com/v1/oauth/openapi.json?client_secret=Tfib%7Dre-%2BQHyP9WKNJ1GXY3bzwuCQhbD post /v2/geo/reports/shopping","href":"/api-reference/reports/get-shopping-report"}]}]},{"tab":"Writesonic MCP Server","icon":"plug","pages":[{"title":"Writesonic MCP Server","href":"/mcp/mcp-server"}]},{"tab":"Agents REST API","icon":"code","pages":[{"title":"Agents REST API","href":"/api-reference/agents/authentication"}]},{"tab":"Agents MCP Server","icon":"plug","pages":[{"title":"Agents MCP Server","href":"/agents-mcp/mcp-server"}]}]},"basePath":"","title":"Get Ads Report - Writesonic Docs","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CiUHMMOm.js","snippetPresets-BgfXU7Bw.js","utils-DWvOwgy_.js","style-to-object-BY3JEAdk.js","utils-BN7RXSMJ.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-CFw8bq89.js","conditional-requirements-CFM0id0Q.js","cloneDeep-CAwdfOU2.js","_Uint8Array-BJr8e-ZL.js","isObject-FP1Yky1u.js","ApiExamples-XX0UgMZK.js","usePlaygroundInputsStore-DXDFSa1V.js","shallow-CdX5aREi.js","isEqual-CoOaxexF.js","CodeSnippets-Cg2wpzWm.js","CodeSnippet-D_HwgQO_.js","getApiPlaygroundDisplay-CmCoerhe.js","Page-CVJ-f_k1.js","DynamicMarkdown-CQM9Bhbv.js","SectionHeading-DpbrP8nQ.js","icon-BPCgijHy.js","MethodPill-GQ8DuY0c.js","getPastedJson-Cb5mT31m.js","Check2Icon-a7bUI6e8.js","axios-CsQoIw0U.js","Markdown-CX2QY19L.js","AssistantPageLink-CY3bFglh.js","dist-Dl6_zDnT.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}