Conventions & gotchas

Every recipe assumes the conventions on this page — when one seems to disagree with your intuition, this page is probably why.

Base URL and auth

All endpoints live under one base URL — note the trailing /api, it is part of the path:

https://api.getmint.ai/api

Authenticate with X-API-Key (API key from your dashboard) or a Bearer session JWT. All cookbook examples use the API key.

Dates and the default window

Omitting startDate ≠ all-time

Aggregated endpoints default to the last 6 months when startDate is missing — there is no all-time window, so pass explicit dates for a precise range.

Dates are ISO YYYY-MM-DD, inclusive on both ends.
Every *Variation field compares your window against the equal-length window immediately before it (June 21 – July 21 → baseline May 21 – June 21).
includeVariation defaults to true; set false to skip the comparison.

Arrays, pagination, scores

Array params (models, tagIds) are comma-separated: models=gpt-5,claude-sonnet-4.
Pagination is 1-indexed (page + limit); responses carry total, totalPages, page, limit. Most (citations, sources) add hasNext/hasPrev, but not all — the mentions leaderboard omits them, so page off page < totalPages.
Visibility scores are 0–100 mention rates, not ranks. Share-of-voice percentages are shares of all brand mentions.
Competitors are configured per topic, not per domain — see List topics.
Persona/segmentation is expressed through prompt tags (tagIds, OR semantics) — see Segment Visibility.

Rate limits

200 req/min per key, shared between REST and MCP. Responses include X-RateLimit-* headers; on 429, back off exponentially. See Rate Limits.

Model ids in models are GetMint's internal catalogue ids (e.g. gpt-5, claude-sonnet-4, gemini-2.5-flash), not provider display names. Every aggregated response lists its availableModels — copy ids from there.

Dates and the default window

Omitting startDate ≠ all-time

Aggregated endpoints default to the last 6 months when startDate is missing — there is no all-time window, so pass explicit dates for a precise range.

Dates are ISO YYYY-MM-DD, inclusive on both ends.

Every *Variation field compares your window against the equal-length window immediately before it (June 21 – July 21 → baseline May 21 – June 21).

includeVariation defaults to true; set false to skip the comparison.

Arrays, pagination, scores

Array params (models, tagIds) are comma-separated: models=gpt-5,claude-sonnet-4.

Pagination is 1-indexed (page + limit); responses carry total, totalPages, page, limit. Most (citations, sources) add hasNext/hasPrev, but not all — the mentions leaderboard omits them, so page off page < totalPages.

Visibility scores are 0–100 mention rates, not ranks. Share-of-voice percentages are shares of all brand mentions.

Competitors are configured per topic, not per domain — see List topics.

Persona/segmentation is expressed through prompt tags (tagIds, OR semantics) — see Segment Visibility.

Rate limits

200 req/min per key, shared between REST and MCP. Responses include X-RateLimit-* headers; on 429, back off exponentially. See Rate Limits.