Get a paginated page of per-theme aggregates (Brand Perception & Intelligence)

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/themes/by-theme \
  --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,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "perceptionOnly": true,
  "page": 1,
  "pageSize": 20
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/themes/by-theme"

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,
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "perceptionOnly": True,
    "page": 1,
    "pageSize": 20
}
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,
    entityId: '550e8400-e29b-41d4-a716-446655440000',
    perceptionOnly: true,
    page: 1,
    pageSize: 20
  })
};

fetch('https://api.mentionlab.io/api/analytics/themes/by-theme', 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/themes/by-theme",
  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,
    'entityId' => '550e8400-e29b-41d4-a716-446655440000',
    'perceptionOnly' => true,
    'page' => 1,
    'pageSize' => 20
  ]),
  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/themes/by-theme"

	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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\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/themes/by-theme")
  .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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\n}"

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

{
  "items": [
    {
      "themeId": "<string>",
      "label": "Battery Life",
      "status": "stable",
      "memberCount": 7,
      "mentionCount": 42,
      "sentimentScore": 72,
      "positive": 123,
      "neutral": 123,
      "negative": 123,
      "sharePct": 12.4
    }
  ],
  "page": {
    "totalRecords": 123,
    "limit": 123,
    "currentPage": 123,
    "totalPages": 123,
    "nextPage": 123,
    "prevPage": 123
  },
  "summary": {
    "themeCount": 123,
    "mentionCount": 123,
    "positive": 123,
    "neutral": 123,
    "negative": 123,
    "sentimentScore": 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"
}

Analytics - Themes

Get a paginated page of per-theme aggregates (Brand Perception & Intelligence)

Returns ONE PAGE of the project theme taxonomy (each theme with mention count, sentiment split, average sentiment and share of total) plus a full-set summary (totals, unaffected by paging/bias) for the overview. Pass perceptionOnly=true for Brand Perception (themes from perception-type questions only) or entityId for Brand Intelligence (themes attributed to one brand). bias=praise|criticism splits positive vs negative themes. Never returns the whole taxonomy — page through it. All standard analytics filters apply.

POST

api

analytics

themes

by-theme

Get a paginated page of per-theme aggregates (Brand Perception & Intelligence)

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/themes/by-theme \
  --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,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "perceptionOnly": true,
  "page": 1,
  "pageSize": 20
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/themes/by-theme"

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,
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "perceptionOnly": True,
    "page": 1,
    "pageSize": 20
}
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,
    entityId: '550e8400-e29b-41d4-a716-446655440000',
    perceptionOnly: true,
    page: 1,
    pageSize: 20
  })
};

fetch('https://api.mentionlab.io/api/analytics/themes/by-theme', 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/themes/by-theme",
  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,
    'entityId' => '550e8400-e29b-41d4-a716-446655440000',
    'perceptionOnly' => true,
    'page' => 1,
    'pageSize' => 20
  ]),
  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/themes/by-theme"

	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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\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/themes/by-theme")
  .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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"entityId\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"perceptionOnly\": true,\n  \"page\": 1,\n  \"pageSize\": 20\n}"

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

{
  "items": [
    {
      "themeId": "<string>",
      "label": "Battery Life",
      "status": "stable",
      "memberCount": 7,
      "mentionCount": 42,
      "sentimentScore": 72,
      "positive": 123,
      "neutral": 123,
      "negative": 123,
      "sharePct": 12.4
    }
  ],
  "page": {
    "totalRecords": 123,
    "limit": 123,
    "currentPage": 123,
    "totalPages": 123,
    "nextPage": 123,
    "prevPage": 123
  },
  "summary": {
    "themeCount": 123,
    "mentionCount": 123,
    "positive": 123,
    "neutral": 123,
    "negative": 123,
    "sentimentScore": 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

entityId

string

Restrict to themes attributed to a specific entity (brand) — used by Brand Intelligence. Omit for all themes.

Example:

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

perceptionOnly

boolean

Only themes from perception-type questions (queries.type='perception') — used by Brand Perception (MLENG-357). Combinable with entityId to scope a perception view to one brand.

Example:

true

page

number

Page number (1-based). Default: 1.

Example:

1

pageSize

number

Results per page. Default: 20, max: 100.

Example:

20

bias

enum<string>

Restrict to predominantly-positive ('praise') or predominantly-negative ('criticism') themes. Omit for all themes ranked by frequency.

Available options:

praise,

criticism

Response

items

object[]

required

Show child attributes

page

object

required

Show child attributes

summary

object

required

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

Get a paginated page of per-theme aggregates (Brand Perception & Intelligence)

Headers

Body

Response