Entities detected for one or more tags

curl --request POST \ --url https://api.mentionlab.io/api/v1/analytics/tags/entities \ --header 'Content-Type: application/json' \ --header 'x-project-id: <x-project-id>' \ --data ' { "tagType": "query", "tagIds": [ "42", "43" ], "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", "groupByEntityGroup": true, "entityTypes": [ "owned", "primary", "competitor" ], "limit": 15, "sort": [ { "field": "visibility", "direction": "desc" } ] } '

{ "tags": [ { "tagId": "550e8400-e29b-41d4-a716-446655440000", "resultCount": 340, "entities": [ { "displayKey": "550e8400-e29b-41d4-a716-446655440000", "displayName": "Acme Corp", "isOwned": true, "isPrimary": false, "isCompetitor": true, "mentionCount": 265, "visibility": 77.9, "shareOfVoice": 32.1, "avgRanking": 1.8, "sentimentScore": 74.2, "sentiment": { "positive": 165, "neutral": 72, "negative": 28 } } ] } ] }

Headers

x-project-id

string

required

Project ID to specify the project context

Body

application/json

tagType

enum<string>

required

Which tag system the tagIds belong to

Available options:

query,

execution

Example:

"query"

tagIds

string[]

required

Tag IDs to get entities for

Example:

["42", "43"]

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"

groupByEntityGroup

boolean

default:false

When true, entities in the same group are collapsed into one row, counted once per response (so visibility cannot exceed 100%).

Example:

true

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

limit

number

Max entities returned per tag (top N). Defaults to all.

Example:

15

sort

object[]

Per-tag sort. Defaults to visibility DESC.

Show child attributes

Example:

[
  {
    "field": "visibility",
    "direction": "desc"
  }
]

Headers

Body

Response