curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "sortBy": "visibility", "limit": 20},
)
competitors = r.json()["data"]["competitors"]
print([c["name"] for c in competitors if c["isUserBrand"]])
{
"data": {
"competitors": [
{
"id": "c7d8e9f0-a1b2-4345-cdef-678901234abc",
"name": "Finseo",
"domain": "finseo.ai",
"baseDomain": "finseo.ai",
"isStarred": true,
"isUserBrand": true,
"totalMentions": 186,
"visibleResults": 214,
"totalResults": 420,
"visibilityRate": 51.0,
"visibilityChange": 4.2,
"visibilityIsMentionOnly": false,
"mentionRate": 44.3,
"mentionRateChange": 2.1,
"totalCitations": 98,
"citationRate": 23.3,
"citationRateChange": 3.8,
"avgMentionOrder": 2.3,
"avgMentionOrderChange": -0.2,
"firstMentionSharePercent": 44,
"top3MentionSharePercent": 65,
"shareOfVoicePercent": 8.2,
"shareOfVoiceChange": 0.6,
"averagePosition": 17.3,
"sentimentScore": 0.77,
"promptCount": 42
},
{
"id": "d8e9f0a1-b2c3-4456-def0-789012345bcd",
"name": "Competitor A",
"domain": "competitor-a.com",
"baseDomain": "competitor-a.com",
"isStarred": false,
"isUserBrand": false,
"totalMentions": 172,
"visibleResults": 181,
"totalResults": 420,
"visibilityRate": 43.1,
"visibilityChange": -1.4,
"visibilityIsMentionOnly": false,
"mentionRate": 41.0,
"mentionRateChange": -0.9,
"totalCitations": 24,
"citationRate": 5.7,
"citationRateChange": -0.5,
"avgMentionOrder": 3.1,
"avgMentionOrderChange": 0.4,
"firstMentionSharePercent": 23,
"top3MentionSharePercent": 53,
"shareOfVoicePercent": 4.2,
"shareOfVoiceChange": -0.3,
"averagePosition": 21.4,
"sentimentScore": 0.62,
"promptCount": 42
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 15,
"hasMore": false
}
}
}
Competitors
List Competitors
GET
/
v1
/
projects
/
{projectId}
/
competitors
curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "sortBy": "visibility", "limit": 20},
)
competitors = r.json()["data"]["competitors"]
print([c["name"] for c in competitors if c["isUserBrand"]])
{
"data": {
"competitors": [
{
"id": "c7d8e9f0-a1b2-4345-cdef-678901234abc",
"name": "Finseo",
"domain": "finseo.ai",
"baseDomain": "finseo.ai",
"isStarred": true,
"isUserBrand": true,
"totalMentions": 186,
"visibleResults": 214,
"totalResults": 420,
"visibilityRate": 51.0,
"visibilityChange": 4.2,
"visibilityIsMentionOnly": false,
"mentionRate": 44.3,
"mentionRateChange": 2.1,
"totalCitations": 98,
"citationRate": 23.3,
"citationRateChange": 3.8,
"avgMentionOrder": 2.3,
"avgMentionOrderChange": -0.2,
"firstMentionSharePercent": 44,
"top3MentionSharePercent": 65,
"shareOfVoicePercent": 8.2,
"shareOfVoiceChange": 0.6,
"averagePosition": 17.3,
"sentimentScore": 0.77,
"promptCount": 42
},
{
"id": "d8e9f0a1-b2c3-4456-def0-789012345bcd",
"name": "Competitor A",
"domain": "competitor-a.com",
"baseDomain": "competitor-a.com",
"isStarred": false,
"isUserBrand": false,
"totalMentions": 172,
"visibleResults": 181,
"totalResults": 420,
"visibilityRate": 43.1,
"visibilityChange": -1.4,
"visibilityIsMentionOnly": false,
"mentionRate": 41.0,
"mentionRateChange": -0.9,
"totalCitations": 24,
"citationRate": 5.7,
"citationRateChange": -0.5,
"avgMentionOrder": 3.1,
"avgMentionOrderChange": 0.4,
"firstMentionSharePercent": 23,
"top3MentionSharePercent": 53,
"shareOfVoicePercent": 4.2,
"shareOfVoiceChange": -0.3,
"averagePosition": 21.4,
"sentimentScore": 0.62,
"promptCount": 42
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 15,
"hasMore": false
}
}
}
Returns ranked competitors for AI visibility: visibility, mention rate, citation rate, mentions, Share of Voice, position, and sentiment. Use this to see how Finseo stacks up against other brands in ChatGPT, Claude, and Perplexity answers.
Three presence rates are returned per competitor, all as a share of
totalResults (see KPIs explained):
visibilityRate— Visibility: % of answers where the brand is visible, i.e. named in the answer text OR its domain cited as a source (the dashboard “Visibility” column;visibleResultsis the count).visibilityIsMentionOnly: trueflags rows where the citation leg could not be resolved and the value equals the mention-based rate.mentionRate— Mention Rate: % of answers naming the brand in the text (totalMentionsis the count).citationRate— Citation Rate: % of answers citing the brand’s domain as a source (totalCitationsis the count);nullwhen citations could not be resolved for the brand.
mentionRate and citationRate, so visibilityRate ≤ mentionRate + citationRate.
Two position metrics are returned per competitor:
avgMentionOrder— the ordinal Position KPI: average rank among all brands named in an answer (1 = named first, lower is better). This is the#2.3-style value shown on the dashboard competitors page.averagePosition— Mention Depth: how deep in the answer text the mention appears (0% = very top). Not a ranking position; kept under this name for backwards compatibility.
string
required
Project identifier.
string
default:"30d"
Analysis window, e.g.
7d, 30d. Ignored when startDate/endDate are set.string
Custom range start (
YYYY-MM-DD). Must be combined with endDate; overrides timeframe.string
Custom range end (
YYYY-MM-DD). Must be combined with startDate.string
Filter tracking results to one model.
string
Filter prompts by language.
string
JSON array or comma-separated prompt tags.
string
Filter by competitor name or domain substring.
string
default:"visibility"
One of
visibility (named OR cited), mentions, position, sentiment, name.string
default:"desc"
asc or desc.integer
default:"1"
Page number.
integer
default:"50"
Page size (1–500).
curl --request GET \
--url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
--header "Authorization: Bearer $FINSEO_API_KEY"
import requests
r = requests.get(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
params={"timeframe": "30d", "sortBy": "visibility", "limit": 20},
)
competitors = r.json()["data"]["competitors"]
print([c["name"] for c in competitors if c["isUserBrand"]])
{
"data": {
"competitors": [
{
"id": "c7d8e9f0-a1b2-4345-cdef-678901234abc",
"name": "Finseo",
"domain": "finseo.ai",
"baseDomain": "finseo.ai",
"isStarred": true,
"isUserBrand": true,
"totalMentions": 186,
"visibleResults": 214,
"totalResults": 420,
"visibilityRate": 51.0,
"visibilityChange": 4.2,
"visibilityIsMentionOnly": false,
"mentionRate": 44.3,
"mentionRateChange": 2.1,
"totalCitations": 98,
"citationRate": 23.3,
"citationRateChange": 3.8,
"avgMentionOrder": 2.3,
"avgMentionOrderChange": -0.2,
"firstMentionSharePercent": 44,
"top3MentionSharePercent": 65,
"shareOfVoicePercent": 8.2,
"shareOfVoiceChange": 0.6,
"averagePosition": 17.3,
"sentimentScore": 0.77,
"promptCount": 42
},
{
"id": "d8e9f0a1-b2c3-4456-def0-789012345bcd",
"name": "Competitor A",
"domain": "competitor-a.com",
"baseDomain": "competitor-a.com",
"isStarred": false,
"isUserBrand": false,
"totalMentions": 172,
"visibleResults": 181,
"totalResults": 420,
"visibilityRate": 43.1,
"visibilityChange": -1.4,
"visibilityIsMentionOnly": false,
"mentionRate": 41.0,
"mentionRateChange": -0.9,
"totalCitations": 24,
"citationRate": 5.7,
"citationRateChange": -0.5,
"avgMentionOrder": 3.1,
"avgMentionOrderChange": 0.4,
"firstMentionSharePercent": 23,
"top3MentionSharePercent": 53,
"shareOfVoicePercent": 4.2,
"shareOfVoiceChange": -0.3,
"averagePosition": 21.4,
"sentimentScore": 0.62,
"promptCount": 42
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 15,
"hasMore": false
}
}
}