Get Ads Report
curl --request POST \
--url https://api.writesonic.com/v2/geo/reports/ads \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"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": "<topic-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"
}
'import requests
url = "https://api.writesonic.com/v2/geo/reports/ads"
payload = {
"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": "<topic-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"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: '<topic-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'
})
};
fetch('https://api.writesonic.com/v2/geo/reports/ads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.writesonic.com/v2/geo/reports/ads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => '<topic-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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.writesonic.com/v2/geo/reports/ads"
payload := strings.NewReader("{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.writesonic.com/v2/geo/reports/ads")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.writesonic.com/v2/geo/reports/ads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}"
response = http.request(request)
puts response.read_body{
"info": {
"total_rows": 123,
"query": {
"metrics": [
"<string>"
],
"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": "<string>",
"topic_name": "<string>",
"tag_id": "<string>",
"tag_name": "<string>",
"market_id": "<string>",
"market_name": "<string>",
"model_id": "<string>",
"model_name": "<string>",
"query_id": "<string>",
"query_name": "<string>",
"date": "<string>",
"website_id": "<string>",
"website_name": "<string>",
"branded": true,
"product_id": "<string>",
"product_name": "<string>",
"product_image": "<string>",
"product_link": "<string>",
"brand_id": "<string>",
"brand_name": "<string>",
"brand_url": "<string>",
"brand_logo": "<string>",
"brand_is_self": true,
"product_source_type": "<string>",
"placement_type": "<string>",
"advertiser_id": "<string>",
"advertiser_name": "<string>",
"advertiser_url": "<string>",
"advertiser_logo": "<string>",
"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": "<string>",
"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
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Reports
Get Ads Report
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
productrows also carryproduct_image,product_link,brand_id/brand_name/brand_url/brand_logo,brand_is_selfandproduct_source_type;advertiserrows carryadvertiser_url,advertiser_logo,advertiser_is_selfdatesupports optionaldate_aggregation_interval:day(default) |week|month; buckets on the placement datewebsiteis the advertised brand, and auto-setswebsite_typetoSELF+COMPETITORS;product/advertiserauto-set it toALL, like the dashboard’s Advertisers page (default otherwise isSELF)productis 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, wheread_answerscounts answers in the group holding at least one ad from any advertiser — matching the Ads dashboardshare_of_ad_placements= this advertiser’s placements / all tracked advertisers’ placements, the definition behind the Ads dashboard KPI card. The dashboard’s Advertisers table labelsad_placements / ad_answersas “share of ad placements”; that column isad_visibilityheread_placementscounts distinct answers in which the entity’s ad appeared, not individual placementsavg_quoted_pricealso returnsavg_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,rankandstatusare accepted for compatibility with the other report endpoints and ignored here.platformmatches 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.
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.
POST
/
v2
/
geo
/
reports
/
ads
Get Ads Report
curl --request POST \
--url https://api.writesonic.com/v2/geo/reports/ads \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"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": "<topic-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"
}
'import requests
url = "https://api.writesonic.com/v2/geo/reports/ads"
payload = {
"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": "<topic-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"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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: '<topic-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'
})
};
fetch('https://api.writesonic.com/v2/geo/reports/ads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.writesonic.com/v2/geo/reports/ads",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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' => '<topic-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'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.writesonic.com/v2/geo/reports/ads"
payload := strings.NewReader("{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.writesonic.com/v2/geo/reports/ads")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.writesonic.com/v2/geo/reports/ads")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"dimensions\": [\n \"website\"\n ],\n \"start_date\": \"2026-01-01T00:00:00Z\",\n \"end_date\": \"2026-01-31T23:59:59Z\",\n \"current_from\": \"2023-11-07T05:31:56Z\",\n \"current_to\": \"2023-11-07T05:31:56Z\",\n \"comparison_start_date\": \"2026-07-25T00:00:00Z\",\n \"comparison_end_date\": \"2026-07-31T23:59:59Z\",\n \"previous_from\": \"2023-11-07T05:31:56Z\",\n \"previous_to\": \"2023-11-07T05:31:56Z\",\n \"order_by\": [\n {\n \"field\": \"visibility_score\",\n \"order\": \"desc\"\n }\n ],\n \"pagination\": {\n \"limit\": 10,\n \"offset\": 0\n },\n \"measures\": [\n \"ad_visibility\",\n \"share_of_ad_placements\"\n ],\n \"filters\": {\n \"topics\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n },\n {\n \"operator\": \"contains\",\n \"value\": \"SEO\"\n }\n ]\n },\n \"prompts\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"best AI tools\"\n }\n ]\n },\n \"tags\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"markets\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"United States\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"United Kingdom\"\n }\n ]\n },\n \"intent\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"informational\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"commercial\"\n }\n ]\n },\n \"branded\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": false\n }\n ]\n },\n \"platform\": {\n \"condition\": \"OR\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ChatGPT\"\n },\n {\n \"operator\": \"is\",\n \"value\": \"Perplexity\"\n }\n ]\n },\n \"has_shopping_card\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"has_ads_data\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": true\n }\n ]\n },\n \"visibility\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 50\n }\n ]\n },\n \"rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"volume\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"gte\",\n \"value\": 1000\n }\n ]\n },\n \"website_mentioned_in_answer\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"cited_page_url\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"/blog/\"\n }\n ]\n },\n \"cited_domain\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"writesonic.com\"\n }\n ]\n },\n \"website_mentioned_in_citation\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"550e8400-e29b-41d4-a716-446655440000\"\n }\n ]\n },\n \"advanced_filters\": {\n \"conditions\": [\n {\n \"field\": \"topics\",\n \"operator\": \"is\",\n \"value\": \"<topic-id>\"\n },\n {\n \"field\": \"platform\",\n \"operator\": \"is\",\n \"value\": \"Grok\"\n }\n ],\n \"join\": \"or\"\n },\n \"status\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"ACTIVE\"\n }\n ]\n },\n \"products\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"running shoe\"\n }\n ]\n },\n \"brands\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"Nike\"\n }\n ]\n },\n \"placement_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"SHOPPING_CARD\"\n }\n ]\n },\n \"source_type\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"is\",\n \"value\": \"owned\"\n }\n ]\n },\n \"price\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 100\n }\n ]\n },\n \"product_rank\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"lte\",\n \"value\": 3\n }\n ]\n },\n \"advertisers\": {\n \"condition\": \"AND\",\n \"items\": [\n {\n \"operator\": \"contains\",\n \"value\": \"shopify\"\n }\n ]\n }\n },\n \"date_aggregation_interval\": \"week\",\n \"website_type\": \"SELF+COMPETITORS\"\n}"
response = http.request(request)
puts response.read_body{
"info": {
"total_rows": 123,
"query": {
"metrics": [
"<string>"
],
"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": "<string>",
"topic_name": "<string>",
"tag_id": "<string>",
"tag_name": "<string>",
"market_id": "<string>",
"market_name": "<string>",
"model_id": "<string>",
"model_name": "<string>",
"query_id": "<string>",
"query_name": "<string>",
"date": "<string>",
"website_id": "<string>",
"website_name": "<string>",
"branded": true,
"product_id": "<string>",
"product_name": "<string>",
"product_image": "<string>",
"product_link": "<string>",
"brand_id": "<string>",
"brand_name": "<string>",
"brand_url": "<string>",
"brand_logo": "<string>",
"brand_is_self": true,
"product_source_type": "<string>",
"placement_type": "<string>",
"advertiser_id": "<string>",
"advertiser_name": "<string>",
"advertiser_url": "<string>",
"advertiser_logo": "<string>",
"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": "<string>",
"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
}
]
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Authorizations
Body
application/json
Request parameters for the Ads Report API.
Unique identifier of the project to query. Get valid project IDs from get_all_projects.
Minimum string length:
1Example:
"550e8400-e29b-41d4-a716-446655440000"
Dimensions to group ad data by. At least one dimension is required.
Minimum array length:
1Dimensions to group report data by. Each report accepts a subset; unsupported dimensions are rejected with 400.
topic: Group by topic/categorytag: Group by tagmarket: Group by market/regionmodel: Group by AI model (e.g. ChatGPT, Perplexity)query: Group by individual query/promptdate: Group by date (requires date_aggregation_interval)website: Group by tracked websiteshopping: 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 queryintent_stage: Group by the intent-stage prompt target attached to the querylocality: Group by the locality prompt target attached to the querysearch_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 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 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"
Alias for start_date (analytics-tool date naming).
Alias for end_date (analytics-tool date naming).
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"
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"
Alias for comparison_start_date (analytics-tool date naming).
Alias for comparison_end_date (analytics-tool date naming).
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.
Show child attributes
Show child attributes
Examples:
[
{
"field": "visibility_score",
"order": "desc"
}
]
[
{ "field": "mention_count", "order": "desc" },
{ "field": "rank", "order": "asc" }
]
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
Show child attributes
Examples:
{ "limit": 10, "offset": 0 }
{ "limit": 25, "offset": 50 }
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 appearedad_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 productunique_advertisers: Number of distinct advertisersunique_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"]
Narrow results by topics, markets, advertisers, placement type, etc. All filters combine with AND logic.
Show child attributes
Show child attributes
Optional. When using the 'date' dimension, controls time-series bucket size. Defaults to 'day'.
Available options:
day, week, month Examples:
"week"
"month"
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"
Was this page helpful?