List merchants with citation metrics

curl --request POST \
  --url https://api.mentionlab.io/api/v1/analytics/shopping/merchants \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "startDate": "2025-01-01",
  "endDate": "2025-02-01",
  "countries": [
    "BE",
    "FR"
  ],
  "languages": [
    "en",
    "fr"
  ],
  "models": [
    "gpt-4o",
    "claude-3-5-sonnet"
  ],
  "queryIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTagIds": [
    "42"
  ],
  "execTagIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTagGroupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "execTagGroupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTypes": [],
  "queryTagMode": "or",
  "execTagMode": "or",
  "timezone": "Europe/Brussels",
  "groupByEntityGroup": false,
  "showAllEntities": false,
  "page": 1,
  "pageSize": 50,
  "entityIds": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "merchantName": "amazon",
  "sort": [
    {
      "field": "citationShare",
      "direction": "DESC"
    }
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/v1/analytics/shopping/merchants"

payload = {
    "startDate": "2025-01-01",
    "endDate": "2025-02-01",
    "countries": ["BE", "FR"],
    "languages": ["en", "fr"],
    "models": ["gpt-4o", "claude-3-5-sonnet"],
    "queryIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTagIds": ["42"],
    "execTagIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "execTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTypes": [],
    "queryTagMode": "or",
    "execTagMode": "or",
    "timezone": "Europe/Brussels",
    "groupByEntityGroup": False,
    "showAllEntities": False,
    "page": 1,
    "pageSize": 50,
    "entityIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "merchantName": "amazon",
    "sort": [
        {
            "field": "citationShare",
            "direction": "DESC"
        }
    ]
}
headers = {
    "x-project-id": "<x-project-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-project-id': '<x-project-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    startDate: '2025-01-01',
    endDate: '2025-02-01',
    countries: ['BE', 'FR'],
    languages: ['en', 'fr'],
    models: ['gpt-4o', 'claude-3-5-sonnet'],
    queryIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTagIds: ['42'],
    execTagIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    execTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTypes: [],
    queryTagMode: 'or',
    execTagMode: 'or',
    timezone: 'Europe/Brussels',
    groupByEntityGroup: false,
    showAllEntities: false,
    page: 1,
    pageSize: 50,
    entityIds: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
    merchantName: 'amazon',
    sort: [{field: 'citationShare', direction: 'DESC'}]
  })
};

fetch('https://api.mentionlab.io/api/v1/analytics/shopping/merchants', 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.mentionlab.io/api/v1/analytics/shopping/merchants",
  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([
    'startDate' => '2025-01-01',
    'endDate' => '2025-02-01',
    'countries' => [
        'BE',
        'FR'
    ],
    'languages' => [
        'en',
        'fr'
    ],
    'models' => [
        'gpt-4o',
        'claude-3-5-sonnet'
    ],
    'queryIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTagIds' => [
        '42'
    ],
    'execTagIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTagGroupIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'execTagGroupIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTypes' => [
        
    ],
    'queryTagMode' => 'or',
    'execTagMode' => 'or',
    'timezone' => 'Europe/Brussels',
    'groupByEntityGroup' => false,
    'showAllEntities' => false,
    'page' => 1,
    'pageSize' => 50,
    'entityIds' => [
        'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
    ],
    'merchantName' => 'amazon',
    'sort' => [
        [
                'field' => 'citationShare',
                'direction' => 'DESC'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-project-id: <x-project-id>"
  ],
]);

$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.mentionlab.io/api/v1/analytics/shopping/merchants"

	payload := strings.NewReader("{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-project-id", "<x-project-id>")
	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.mentionlab.io/api/v1/analytics/shopping/merchants")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/v1/analytics/shopping/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-project-id"] = '<x-project-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "totalResponses": 365,
  "totalMerchantCitations": 450,
  "totalBrandMentions": 200,
  "merchants": [
    {
      "merchantId": "550e8400-e29b-41d4-a716-446655440000",
      "merchantName": "Amazon",
      "domain": "amazon.com",
      "mentionCount": 45,
      "citationRate": 28,
      "citationShare": 15,
      "entityCitationShare": 22.5,
      "trueReach": 40,
      "aboveFoldShare": 62.5,
      "avgPosition": 2.4,
      "freeShippingShare": 40,
      "avgShippingPrice": 4.95,
      "inStockShare": 95
    }
  ],
  "page": {
    "totalRecords": 123,
    "limit": 123,
    "currentPage": 123,
    "totalPages": 123,
    "nextPage": 123,
    "prevPage": 123
  }
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

POST

api

analytics

shopping

merchants

List merchants with citation metrics

curl --request POST \
  --url https://api.mentionlab.io/api/v1/analytics/shopping/merchants \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "startDate": "2025-01-01",
  "endDate": "2025-02-01",
  "countries": [
    "BE",
    "FR"
  ],
  "languages": [
    "en",
    "fr"
  ],
  "models": [
    "gpt-4o",
    "claude-3-5-sonnet"
  ],
  "queryIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTagIds": [
    "42"
  ],
  "execTagIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTagGroupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "execTagGroupIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "queryTypes": [],
  "queryTagMode": "or",
  "execTagMode": "or",
  "timezone": "Europe/Brussels",
  "groupByEntityGroup": false,
  "showAllEntities": false,
  "page": 1,
  "pageSize": 50,
  "entityIds": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "merchantName": "amazon",
  "sort": [
    {
      "field": "citationShare",
      "direction": "DESC"
    }
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/v1/analytics/shopping/merchants"

payload = {
    "startDate": "2025-01-01",
    "endDate": "2025-02-01",
    "countries": ["BE", "FR"],
    "languages": ["en", "fr"],
    "models": ["gpt-4o", "claude-3-5-sonnet"],
    "queryIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTagIds": ["42"],
    "execTagIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "execTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
    "queryTypes": [],
    "queryTagMode": "or",
    "execTagMode": "or",
    "timezone": "Europe/Brussels",
    "groupByEntityGroup": False,
    "showAllEntities": False,
    "page": 1,
    "pageSize": 50,
    "entityIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
    "merchantName": "amazon",
    "sort": [
        {
            "field": "citationShare",
            "direction": "DESC"
        }
    ]
}
headers = {
    "x-project-id": "<x-project-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-project-id': '<x-project-id>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    startDate: '2025-01-01',
    endDate: '2025-02-01',
    countries: ['BE', 'FR'],
    languages: ['en', 'fr'],
    models: ['gpt-4o', 'claude-3-5-sonnet'],
    queryIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTagIds: ['42'],
    execTagIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    execTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
    queryTypes: [],
    queryTagMode: 'or',
    execTagMode: 'or',
    timezone: 'Europe/Brussels',
    groupByEntityGroup: false,
    showAllEntities: false,
    page: 1,
    pageSize: 50,
    entityIds: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890'],
    merchantName: 'amazon',
    sort: [{field: 'citationShare', direction: 'DESC'}]
  })
};

fetch('https://api.mentionlab.io/api/v1/analytics/shopping/merchants', 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.mentionlab.io/api/v1/analytics/shopping/merchants",
  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([
    'startDate' => '2025-01-01',
    'endDate' => '2025-02-01',
    'countries' => [
        'BE',
        'FR'
    ],
    'languages' => [
        'en',
        'fr'
    ],
    'models' => [
        'gpt-4o',
        'claude-3-5-sonnet'
    ],
    'queryIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTagIds' => [
        '42'
    ],
    'execTagIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTagGroupIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'execTagGroupIds' => [
        '3fa85f64-5717-4562-b3fc-2c963f66afa6'
    ],
    'queryTypes' => [
        
    ],
    'queryTagMode' => 'or',
    'execTagMode' => 'or',
    'timezone' => 'Europe/Brussels',
    'groupByEntityGroup' => false,
    'showAllEntities' => false,
    'page' => 1,
    'pageSize' => 50,
    'entityIds' => [
        'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
    ],
    'merchantName' => 'amazon',
    'sort' => [
        [
                'field' => 'citationShare',
                'direction' => 'DESC'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-project-id: <x-project-id>"
  ],
]);

$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.mentionlab.io/api/v1/analytics/shopping/merchants"

	payload := strings.NewReader("{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-project-id", "<x-project-id>")
	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.mentionlab.io/api/v1/analytics/shopping/merchants")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/v1/analytics/shopping/merchants")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-project-id"] = '<x-project-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\n  \"countries\": [\n    \"BE\",\n    \"FR\"\n  ],\n  \"languages\": [\n    \"en\",\n    \"fr\"\n  ],\n  \"models\": [\n    \"gpt-4o\",\n    \"claude-3-5-sonnet\"\n  ],\n  \"queryIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagIds\": [\n    \"42\"\n  ],\n  \"execTagIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"execTagGroupIds\": [\n    \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n  ],\n  \"queryTypes\": [],\n  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"page\": 1,\n  \"pageSize\": 50,\n  \"entityIds\": [\n    \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n  ],\n  \"merchantName\": \"amazon\",\n  \"sort\": [\n    {\n      \"field\": \"citationShare\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "totalResponses": 365,
  "totalMerchantCitations": 450,
  "totalBrandMentions": 200,
  "merchants": [
    {
      "merchantId": "550e8400-e29b-41d4-a716-446655440000",
      "merchantName": "Amazon",
      "domain": "amazon.com",
      "mentionCount": 45,
      "citationRate": 28,
      "citationShare": 15,
      "entityCitationShare": 22.5,
      "trueReach": 40,
      "aboveFoldShare": 62.5,
      "avgPosition": 2.4,
      "freeShippingShare": 40,
      "avgShippingPrice": 4.95,
      "inStockShare": 95
    }
  ],
  "page": {
    "totalRecords": 123,
    "limit": 123,
    "currentPage": 123,
    "totalPages": 123,
    "nextPage": 123,
    "prevPage": 123
  }
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Headers

x-project-id

string

required

Project ID to specify the project context

Body

application/json

startDate

string

Start date (inclusive)

Example:

"2025-01-01"

endDate

string

End date (exclusive)

Example:

"2025-02-01"

countries

string[]

Filter by country codes

Example:

["BE", "FR"]

languages

string[]

Filter by language codes

Example:

["en", "fr"]

models

string[]

Filter by AI models

Example:

["gpt-4o", "claude-3-5-sonnet"]

queryIds

string[]

Filter by query IDs

Example:

["3fa85f64-5717-4562-b3fc-2c963f66afa6"]

hasSources

enum<string>

Filter by source presence: "sources" (only with sources), "no_sources" (only without), "all" (no filter). Legacy true/false values are still accepted.

Available options:

all,

sources,

no_sources

hasShopping

enum<string>

Filter by shopping presence: "shopping" (only with shopping), "no_shopping" (only without), "all" (no filter). Legacy true/false values are still accepted.

Available options:

all,

shopping,

no_shopping

queryTagIds

string[]

Filter by query tag IDs (numeric — bigint column)

Example:

["42"]

execTagIds

string[]

Filter by execution tag IDs

Example:

["3fa85f64-5717-4562-b3fc-2c963f66afa6"]

Filter by query tag group IDs — matches rows carrying any tag filed under a selected group. Combines with queryTagIds per queryTagMode.

Example:

["3fa85f64-5717-4562-b3fc-2c963f66afa6"]

Filter by execution tag group IDs — matches rows carrying any tag filed under a selected group. Combines with execTagIds per execTagMode.

Example:

["3fa85f64-5717-4562-b3fc-2c963f66afa6"]

queryTypes

enum<string>[]

Filter by query type. Include "untyped" to also match queries without a type. Results from since-deleted queries are excluded when this filter is set.

Available options:

comparative,

informative,

perception,

untyped

queryTagMode

enum<string>

default:or

Query tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.

Available options:

and,

or

execTagMode

enum<string>

default:or

Execution tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.

Available options:

and,

or

timezone

string

default:UTC

IANA timezone for date bucketing and filtering (e.g. "Europe/Brussels"). Defaults to UTC.

Example:

"Europe/Brussels"

groupBy

enum<string>

Row grouping level for entity results. "none" = one row per entity, "division" = one row per division (entities not in a division get their own row), "group" = one row per top-level group (divisions roll up into their group). Defaults to "none".

Available options:

none,

division,

group

groupByEntityGroup

boolean

deprecated

Deprecated — use groupBy instead. true is equivalent to groupBy="group".

Example:

false

showAllEntities

boolean

Include entities that have only ever been seen in a single AI response. These are mostly one-off extraction noise and are hidden by default.

Example:

false

page

number

default:1

Page number (1-based).

Example:

1

pageSize

number

default:50

Items per page (max 200).

Example:

50

entityIds

string[]

Entity IDs for brand-specific metrics (defaults to primary non-blacklisted).

Example:

["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]

merchantName

string

Case-insensitive substring match on merchant name.

Example:

"amazon"

sort

object[]

Sort order. Allowed fields: merchantName, citationRate, citationShare, entityCitationShare, trueReach, mentionCount.

Show child attributes

Example:

[
  {
    "field": "citationShare",
    "direction": "DESC"
  }
]

Response

totalResponses

number

required

Total AI responses in filtered scope (denominator for citationRate).

Example:

365

totalMerchantCitations

number

required

Sum of mentionCount across all merchants (denominator for citationShare).

Example:

450

totalBrandMentions

number

required

Sum of brand-matched mention counts across all merchants (denominator for entityCitationShare).

Example:

200

merchants

object[]

required

Merchant list, sorted and paginated.

Show child attributes

page

object

required

Pagination metadata.

Show child attributes

Overview

Projects

Queries

Entities

Organisations

Jobs

Tags

Tag Groups

Execution Tags

Theme Analysis

Entity Groups

Source Categories

Job Executions

Analytics - Visibility

Analytics - Tags

Analytics - Sources

Analytics - Shopping

Analytics - Sentiment

Analytics - Queries

Analytics - Models

Analytics - Themes

Analytics - Fan Outs

Analytics - Social

Source Topics

Reference

Shopping Products

List merchants with citation metrics

Headers

Body

Response