Get per-tag stats with project brand metrics

curl --request POST \ --url https://api.mentionlab.io/api/analytics/tags/stats \ --header 'Content-Type: application/json' \ --header 'x-project-id: <x-project-id>' \ --data ' { "tagType": "query", "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": [ "3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90" ], "tagIds": [ "tag_123", "tag_456" ], "groupByEntityGroup": false, "limit": 5, "sort": [ { "field": "mentionCount", "direction": "DESC" } ] } '

{ "tags": [ { "tagId": "550e8400-e29b-41d4-a716-446655440000", "tagName": "Pricing", "tagColor": "#4f46e5", "resultCount": 340, "projectBrand": { "mentionCount": 80, "visibility": 40, "avgRanking": 2.5, "sentimentScore": 72.3, "shareOfVoice": 32.1, "sentimentPositive": 52, "sentimentNeutral": 18, "sentimentNegative": 10 } } ] }

Headers

x-project-id

string

required

Project ID to specify the project context

Body

application/json

tagType

enum<string>

required

Which tag system to group by

Available options:

query,

execution

Example:

"query"

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:

["3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"]

tagIds

string[]

Restrict to specific tag IDs (omit for all tags)

Example:

["tag_123", "tag_456"]

groupByEntityGroup

boolean

default:false

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

Example:

false

limit

number

Max number of tags to return (top N by the active sort). Omit for all tags.

Example:

5

sort

object[]

Server-side sort. Allowed fields: tagName, resultCount, mentionCount, visibility, shareOfVoice, avgRanking, sentimentScore. Default: mentionCount descending.

Show child attributes

Example:

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

Headers

Body

Response