curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics?timeframe=30d' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "language": "en"},
)
metrics = r.json()["data"]
cur, chg = metrics["today"], metrics["changes"]
print(cur["responseVisibilityRate"], cur["mentionRate"], cur["citationRate"], chg["responseVisibilityRateChange"])
{
"data": {
"today": {
"date": "2026-09-08",
"visible": 28,
"notVisible": 14,
"mentions": 44,
"cited": 22,
"totalResponses": 84,
"position": 22.4,
"sentiment": 78,
"visibilityRate": 66.67,
"responseVisibilityRate": 59.52,
"mentionRate": 52.38,
"citationRate": 26.19
},
"yesterday": {
"date": "2026-08-09",
"visible": 22,
"notVisible": 20,
"mentions": 34,
"cited": 15,
"totalResponses": 76,
"position": 28.1,
"sentiment": 71,
"visibilityRate": 52.38,
"responseVisibilityRate": 50.0,
"mentionRate": 44.74,
"citationRate": 19.74
},
"changes": {
"visibleChange": 6,
"visibilityRateChange": 14.29,
"responseVisibilityRateChange": 9.52,
"mentionsChange": 10,
"citedChange": 7,
"mentionRateChange": 7.64,
"citationRateChange": 6.45,
"positionChange": -5.7,
"sentimentChange": 7
}
}
}
Metrics
Project Metrics (Summary)
GET
/
v1
/
projects
/
{projectId}
/
metrics
curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics?timeframe=30d' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "language": "en"},
)
metrics = r.json()["data"]
cur, chg = metrics["today"], metrics["changes"]
print(cur["responseVisibilityRate"], cur["mentionRate"], cur["citationRate"], chg["responseVisibilityRateChange"])
{
"data": {
"today": {
"date": "2026-09-08",
"visible": 28,
"notVisible": 14,
"mentions": 44,
"cited": 22,
"totalResponses": 84,
"position": 22.4,
"sentiment": 78,
"visibilityRate": 66.67,
"responseVisibilityRate": 59.52,
"mentionRate": 52.38,
"citationRate": 26.19
},
"yesterday": {
"date": "2026-08-09",
"visible": 22,
"notVisible": 20,
"mentions": 34,
"cited": 15,
"totalResponses": 76,
"position": 28.1,
"sentiment": 71,
"visibilityRate": 52.38,
"responseVisibilityRate": 50.0,
"mentionRate": 44.74,
"citationRate": 19.74
},
"changes": {
"visibleChange": 6,
"visibilityRateChange": 14.29,
"responseVisibilityRateChange": 9.52,
"mentionsChange": 10,
"citedChange": 7,
"mentionRateChange": 7.64,
"citationRateChange": 6.45,
"positionChange": -5.7,
"sentimentChange": 7
}
}
}
Returns aggregate AI visibility metrics for the current period vs the previous period of equal length. Use this for dashboards and KPIs for Finseo visibility across ChatGPT, Claude, Perplexity, and other tracked models.
The response carries the current period under
An answer can count toward both
today and the previous period under yesterday (legacy names — each block aggregates the whole period, date is the period’s end date). All rates share the same denominator, totalResponses (see KPIs explained):
| Field | Meaning |
|---|---|
responseVisibilityRate | Visibility — % of answers where the brand is visible: named in the text OR own domain cited as a source (the dashboard “Visibility” KPI) |
mentionRate | Mention Rate — % of answers naming the brand in the answer text |
citationRate | Citation Rate — % of answers citing the own domain (or a configured domain alias) as a source |
mentions / cited | Absolute counts behind Mention Rate and Citation Rate (answers, each counted once) |
visibilityRate | Prompt coverage — % of tracked prompts with at least one visible answer (a different, usually higher number) |
visible / notVisible | Number of prompts with / without a visible answer |
position | Mention depth — how deep in the answer text the mention appears (0 = top), not a ranking |
mentionRate and citationRate, so responseVisibilityRate ≤ mentionRate + citationRate.
Custom range start (
YYYY-MM-DD). Must be combined with endDate; overrides timeframe. The comparison period is the same number of days immediately before the custom range.Entity level (projects with the entity tree switched on):
company (default — sub-brands, products and ingredients count for their company), sub_brands, products (ingredients count for their product), ingredients. Counting never changes between levels, only the grouping; see Entity levels.Which of your own entities counts as “you” on that level (competitor
id from the entity tree, e.g. a sister product). Default: the own entity with the most answers.curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics?timeframe=30d' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/metrics",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "language": "en"},
)
metrics = r.json()["data"]
cur, chg = metrics["today"], metrics["changes"]
print(cur["responseVisibilityRate"], cur["mentionRate"], cur["citationRate"], chg["responseVisibilityRateChange"])
{
"data": {
"today": {
"date": "2026-09-08",
"visible": 28,
"notVisible": 14,
"mentions": 44,
"cited": 22,
"totalResponses": 84,
"position": 22.4,
"sentiment": 78,
"visibilityRate": 66.67,
"responseVisibilityRate": 59.52,
"mentionRate": 52.38,
"citationRate": 26.19
},
"yesterday": {
"date": "2026-08-09",
"visible": 22,
"notVisible": 20,
"mentions": 34,
"cited": 15,
"totalResponses": 76,
"position": 28.1,
"sentiment": 71,
"visibilityRate": 52.38,
"responseVisibilityRate": 50.0,
"mentionRate": 44.74,
"citationRate": 19.74
},
"changes": {
"visibleChange": 6,
"visibilityRateChange": 14.29,
"responseVisibilityRateChange": 9.52,
"mentionsChange": 10,
"citedChange": 7,
"mentionRateChange": 7.64,
"citationRateChange": 6.45,
"positionChange": -5.7,
"sentimentChange": 7
}
}
}