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
Listar Concorrentes
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
}
}
}
Retorna os concorrentes ranqueados por visibilidade em IA: visibilidade, mention rate, citation rate, Mentions, Share of Voice, posição e Sentiment. Use isto para ver como a Finseo se compara a outras marcas nas respostas do ChatGPT, Claude e Perplexity.
Três taxas de presença são retornadas por concorrente, todas como parcela de
totalResults (veja KPIs explicados):
visibilityRate— Visibility: % de respostas em que a marca está visível, ou seja, nomeada no texto da resposta OU com seu domínio citado como fonte (a coluna “Visibility” do dashboard;visibleResultsé a contagem).visibilityIsMentionOnly: truesinaliza linhas em que o componente de citações não pôde ser resolvido e o valor é igual à taxa baseada apenas em menções.mentionRate— Mention Rate: % de respostas que nomeiam a marca no texto (totalMentionsé a contagem).citationRate— Citation Rate: % de respostas que citam o domínio da marca como fonte (totalCitationsé a contagem);nullquando as citações não puderam ser resolvidas para a marca.
mentionRate quanto para citationRate, então visibilityRate ≤ mentionRate + citationRate.
Duas métricas de posição são retornadas por concorrente:
avgMentionOrder— o KPI ordinal Position: posição média entre todas as marcas nomeadas em uma resposta (1 = nomeada primeiro, quanto menor, melhor). É o valor no estilo#2.3exibido na página de concorrentes do dashboard.averagePosition— Mention Depth: a que profundidade do texto da resposta a menção aparece (0% = bem no topo). Não é uma posição de ranking; mantido com este nome por compatibilidade retroativa.
string
obrigatório
Identificador do projeto.
string
padrão:"30d"
Janela de análise, por exemplo
7d, 30d.string
Filtre os resultados de Tracking para um único modelo.
string
Filtre os Prompts por idioma.
string
Array JSON ou Tags de Prompt separadas por vírgula.
string
Filtre por parte do nome ou domínio do concorrente.
string
padrão:"visibility"
Um de
visibility (nomeada OU citada), mentions, position, sentiment, name.string
padrão:"desc"
asc ou desc.integer
padrão:"1"
Número da página.
integer
padrão:"50"
Tamanho da página (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
}
}
}