Segment Visibility by model, region, or persona

GET/domains/{domainId}/topics/{topicId}/visibility/aggregated

The segment switcher on the Visibility tile — a score per segment along three axes: models via a query filter, region via the per-market topic, and persona via prompt tags.

How this example works

For a by-model split you may not need models=. modelBreakdown[] already returns per-model scores in one unfiltered call — reach for models= only for a fully filtered payload (chart, competitors, mentions scoped to that model).
Regions are segmented by topic, not by query param. Topics carry their own market + language — a multi-market brand has a sibling topic per market (List topics), so the region axis is "call the same recipe with that market's topicId". Topic visibility ignores marketLanguageCodePairId; that param filters the domain-level endpoints (visibility/aggregated, visibility/scores, competition/win-rate/aggregated, mint-score/aggregated, sentiment/aggregated, alignment/aggregated, raw results). Domain visibility and win rate keep only the topics measured in that pair's market and language.
There is no persona query param, and the domain's personas[] are not tags. To segment by persona, create one tag per persona and assign it to that persona's prompts (Brand Setup → Tag Management, or POST /domains/{domainId}/tags); nothing does this for you. Then list them with GET /domains/{domainId}/tags (a bare array, returns { id, name, ... }), then pass the tag id values as tagIds — they are UUIDs, OR semantics; non-UUID values are rejected with a 400. A tag library belongs to one domain, so use the same domainId you query visibility for.

curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/tags" -H "X-API-Key: $MINT_API_KEY"

curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$TOPIC_ID/visibility/aggregated?models=chatgpt" \
  -H "X-API-Key: $MINT_API_KEY"
curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$US_TOPIC_ID/visibility/aggregated" \
  -H "X-API-Key: $MINT_API_KEY"
curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$TOPIC_ID/visibility/aggregated?tagIds=7c9e6679-7425-40de-963d-1d8f0a3c2e11" \
  -H "X-API-Key: $MINT_API_KEY"

Response — GET /domains/{domainId}/tags returns that domain's tag library; each segment call returns a scoped report (trimmed; full shape in API reference):

[
  {
    "id": "7c9e6679-7425-40de-963d-1d8f0a3c2e11",
    "name": "Buyer persona",
    "organizationId": "fe0b1256-05e6-4214-81db-a5f1f88616b4",
    "domainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2026-06-01T09:00:00.000Z",
    "updatedAt": "2026-06-01T09:00:00.000Z"
  }
]

The scoped report below was filtered with models=chatgpt. Note that only the headline fields (averageScore, scoreVariation) honour the filter — availableModels and modelBreakdown always describe the full catalogue with each model's own unfiltered score (verified against the live API):

{
  "averageScore": 74,
  "scoreVariation": 2.1,
  "availableModels": ["gpt-interface", "perplexity", "copilot-interface", "grok", "google-ai-overview", "chatgpt", "claude", "gemini"],
  "modelBreakdown": [
    { "model": "chatgpt", "score": 74, "variation": 2.1 },
    { "model": "claude", "score": 61, "variation": -1.2 },
    { "model": "gemini", "score": 48, "variation": 0 }
  ]
}

Query parameters

Prop

Type

Variations

Change	Effect
Combine `models` + `tagIds`	Each filter narrows the payload further; multiple `tagIds` match with OR semantics
Read `modelBreakdown[]`	By-model split without one filtered call per model
`marketLanguageCodePairId` on a domain-level endpoint	Region split for domain-level metrics (`<marketCode>-<languageCode>`, e.g. `"US-en"`)
Pass `topicId` on a domain-level endpoint	Scope a domain-wide aggregate down to a single topic

Common follow-ups

Conventions

Base URL, auth, ISO dates, default window, and array encoding.

Visibility Score for one asset

The single-number headline this recipe splits into segments.

GET/domains/{domainId}/topics/{topicId}/visibility/aggregated

The segment switcher on the Visibility tile — a score per segment along three axes: models via a query filter, region via the per-market topic, and persona via prompt tags.

How this example works

For a by-model split you may not need models=. modelBreakdown[] already returns per-model scores in one unfiltered call — reach for models= only for a fully filtered payload (chart, competitors, mentions scoped to that model).
Regions are segmented by topic, not by query param. Topics carry their own market + language — a multi-market brand has a sibling topic per market (List topics), so the region axis is "call the same recipe with that market's topicId". Topic visibility ignores marketLanguageCodePairId; that param filters the domain-level endpoints (visibility/aggregated, visibility/scores, competition/win-rate/aggregated, mint-score/aggregated, sentiment/aggregated, alignment/aggregated, raw results). Domain visibility and win rate keep only the topics measured in that pair's market and language.
There is no persona query param, and the domain's personas[] are not tags. To segment by persona, create one tag per persona and assign it to that persona's prompts (Brand Setup → Tag Management, or POST /domains/{domainId}/tags); nothing does this for you. Then list them with GET /domains/{domainId}/tags (a bare array, returns { id, name, ... }), then pass the tag id values as tagIds — they are UUIDs, OR semantics; non-UUID values are rejected with a 400. A tag library belongs to one domain, so use the same domainId you query visibility for.

curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/tags" -H "X-API-Key: $MINT_API_KEY"

curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$TOPIC_ID/visibility/aggregated?models=chatgpt" \
  -H "X-API-Key: $MINT_API_KEY"
curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$US_TOPIC_ID/visibility/aggregated" \
  -H "X-API-Key: $MINT_API_KEY"
curl "https://api.getmint.ai/api/domains/$DOMAIN_ID/topics/$TOPIC_ID/visibility/aggregated?tagIds=7c9e6679-7425-40de-963d-1d8f0a3c2e11" \
  -H "X-API-Key: $MINT_API_KEY"

Response — GET /domains/{domainId}/tags returns that domain's tag library; each segment call returns a scoped report (trimmed; full shape in API reference):

[
  {
    "id": "7c9e6679-7425-40de-963d-1d8f0a3c2e11",
    "name": "Buyer persona",
    "organizationId": "fe0b1256-05e6-4214-81db-a5f1f88616b4",
    "domainId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdAt": "2026-06-01T09:00:00.000Z",
    "updatedAt": "2026-06-01T09:00:00.000Z"
  }
]

{
  "averageScore": 74,
  "scoreVariation": 2.1,
  "availableModels": ["gpt-interface", "perplexity", "copilot-interface", "grok", "google-ai-overview", "chatgpt", "claude", "gemini"],
  "modelBreakdown": [
    { "model": "chatgpt", "score": 74, "variation": 2.1 },
    { "model": "claude", "score": 61, "variation": -1.2 },
    { "model": "gemini", "score": 48, "variation": 0 }
  ]
}

Query parameters

Prop

Type

Variations

Change	Effect
Combine `models` + `tagIds`	Each filter narrows the payload further; multiple `tagIds` match with OR semantics
Read `modelBreakdown[]`	By-model split without one filtered call per model
`marketLanguageCodePairId` on a domain-level endpoint	Region split for domain-level metrics (`<marketCode>-<languageCode>`, e.g. `"US-en"`)
Pass `topicId` on a domain-level endpoint	Scope a domain-wide aggregate down to a single topic