Get per-tag brand visibility broken down by model

curl --request POST \ --url https://api.mentionlab.io/api/analytics/tags/models \ --header 'Content-Type: application/json' \ --header 'x-project-id: <x-project-id>' \ --data ' { "tagType": "execution", "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": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "execTagIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "queryTagMode": "or", "execTagMode": "or", "timezone": "Europe/Brussels", "entityIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "tagIds": [ "pricing", "features" ], "groupByEntityGroup": false, "limit": 5, "offset": 0 } '

{ "total": 27, "tags": [ { "tagId": "550e8400-e29b-41d4-a716-446655440000", "tagName": "Week 1", "tagColor": "#4f46e5", "resultCount": 340, "visibility": 40, "models": [ { "model": "gpt-5-mini", "resultCount": 120, "visibility": 42.5 } ] } ] }

Headers

x-project-id

string

required

Project ID to specify the project context

Body

application/json

tagType

enum<string>

required

Which tag system to break down by model (query tags or response/execution tags)

Available options:

query,

execution

Example:

"execution"

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

Example:

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

execTagIds

string[]

Filter by execution tag IDs

Example:

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

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"

entityIds

string[]

Entity IDs for the project brand (defaults to primary non-blacklisted)

Example:

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

tagIds

string[]

Restrict to specific tag IDs (omit for all tags)

Example:

["pricing", "features"]

groupByEntityGroup

boolean

default:false

When true, expand selected entities to include all members of their entity groups.

Example:

false

limit

number

default:5

Max number of tags (rows) to return for this page, ranked by visibility. Defaults to 5.

Example:

5

offset

number

default:0

Number of tags (rows) to skip for pagination. Defaults to 0.

Example:

0

Response

total

number

required

Total number of tags with data in the filtered scope (across all pages). Use with limit/offset for pagination.

Example:

27