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": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "execTagIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "queryTagMode": "or", "execTagMode": "or", "timezone": "Europe/Brussels", "groupByEntityGroup": true, "entityTypes": [ "owned", "primary", "competitor" ], "entityIds": [ "550e8400-e29b-41d4-a716-446655440000", "f47ac10b-58cc-4372-a567-0e02b2c3d479" ] } '

[ { "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 } ]

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

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

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