Get sentiment comparison across entities

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/sentiment/by-entity \
  --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,
  "entityTypes": [
    "owned",
    "primary",
    "competitor"
  ],
  "entityIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/sentiment/by-entity"

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,
    "entityTypes": ["owned", "primary", "competitor"],
    "entityIds": ["550e8400-e29b-41d4-a716-446655440000", "f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}
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,
    entityTypes: ['owned', 'primary', 'competitor'],
    entityIds: ['550e8400-e29b-41d4-a716-446655440000', 'f47ac10b-58cc-4372-a567-0e02b2c3d479']
  })
};

fetch('https://api.mentionlab.io/api/analytics/sentiment/by-entity', 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/analytics/sentiment/by-entity",
  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,
    'entityTypes' => [
        'owned',
        'primary',
        'competitor'
    ],
    'entityIds' => [
        '550e8400-e29b-41d4-a716-446655440000',
        'f47ac10b-58cc-4372-a567-0e02b2c3d479'
    ]
  ]),
  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/analytics/sentiment/by-entity"

	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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\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/analytics/sentiment/by-entity")
  .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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/sentiment/by-entity")

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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n  ]\n}"

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

[
  {
    "displayKey": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Acme Corp",
    "isOwned": true,
    "isPrimary": true,
    "isCompetitor": false,
    "sentimentScore": 72.3,
    "positive": 52,
    "neutral": 18,
    "negative": 10,
    "mentionCount": 80
  }
]

{
  "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

sentiment

by-entity

Get sentiment comparison across entities

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/sentiment/by-entity \
  --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,
  "entityTypes": [
    "owned",
    "primary",
    "competitor"
  ],
  "entityIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/sentiment/by-entity"

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,
    "entityTypes": ["owned", "primary", "competitor"],
    "entityIds": ["550e8400-e29b-41d4-a716-446655440000", "f47ac10b-58cc-4372-a567-0e02b2c3d479"]
}
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,
    entityTypes: ['owned', 'primary', 'competitor'],
    entityIds: ['550e8400-e29b-41d4-a716-446655440000', 'f47ac10b-58cc-4372-a567-0e02b2c3d479']
  })
};

fetch('https://api.mentionlab.io/api/analytics/sentiment/by-entity', 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/analytics/sentiment/by-entity",
  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,
    'entityTypes' => [
        'owned',
        'primary',
        'competitor'
    ],
    'entityIds' => [
        '550e8400-e29b-41d4-a716-446655440000',
        'f47ac10b-58cc-4372-a567-0e02b2c3d479'
    ]
  ]),
  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/analytics/sentiment/by-entity"

	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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\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/analytics/sentiment/by-entity")
  .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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/sentiment/by-entity")

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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"550e8400-e29b-41d4-a716-446655440000\",\n    \"f47ac10b-58cc-4372-a567-0e02b2c3d479\"\n  ]\n}"

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

[
  {
    "displayKey": "550e8400-e29b-41d4-a716-446655440000",
    "displayName": "Acme Corp",
    "isOwned": true,
    "isPrimary": true,
    "isCompetitor": false,
    "sentimentScore": 72.3,
    "positive": 52,
    "neutral": 18,
    "negative": 10,
    "mentionCount": 80
  }
]

{
  "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

entityTypes

enum<string>[]

Filter which entity types to include in results. Accepted values: "owned", "primary", "competitor". Defaults to all types when omitted.

Available options:

owned,

primary,

competitor

Example:

["owned", "primary", "competitor"]

entityIds

string[]

Scope to specific entity IDs. If omitted, returns all non-blacklisted entities.

Example:

[
  "550e8400-e29b-41d4-a716-446655440000",
  "f47ac10b-58cc-4372-a567-0e02b2c3d479"
]

Response

displayKey

string

required

Canonical entity ID.

Example:

"550e8400-e29b-41d4-a716-446655440000"

displayName

string

required

Entity display name.

Example:

"Acme Corp"

isOwned

boolean

required

Whether the entity is owned by the project.

Example:

true

isPrimary

boolean

required

Whether this is the primary project entity.

Example:

true

isCompetitor

boolean

required

Whether this is a competitor entity.

Example:

false

sentimentScore

number

required

Average sentiment score (0–100).

Example:

72.3

positive

number

required

Count of positive-sentiment mentions.

Example:

52

neutral

number

required

Count of neutral-sentiment mentions.

Example:

18

negative

number

required

Count of negative-sentiment mentions.

Example:

10

mentionCount

number

required

Total mention count for this entity.

Example:

80

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

Get sentiment comparison across entities

Headers

Body

Response