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
Elenca i concorrenti
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
}
}
}
Restituisce i concorrenti in classifica per visibilità AI: visibilità, mention rate, citation rate, Mentions, Share of Voice, posizione e Sentiment. Usa questo Endpoint per vedere come Finseo si posiziona rispetto agli altri brand nelle risposte di ChatGPT, Claude e Perplexity.
Per ogni concorrente vengono restituiti tre tassi di presenza, tutti come quota di
totalResults (vedi KPI e metriche):
visibilityRate— Visibility: % di risposte in cui il brand è visibile, cioè nominato nel testo della risposta O con il proprio dominio citato come fonte (la colonna “Visibility” della dashboard;visibleResultsè il conteggio).visibilityIsMentionOnly: truesegnala le righe in cui la componente citazioni non è stata risolta e il valore coincide con il tasso basato sulle sole menzioni.mentionRate— Mention Rate: % di risposte che nominano il brand nel testo (totalMentionsè il conteggio).citationRate— Citation Rate: % di risposte che citano il dominio del brand come fonte (totalCitationsè il conteggio);nullquando le citazioni non sono state risolte per il brand.
mentionRate sia in citationRate, quindi visibilityRate ≤ mentionRate + citationRate.
Per ogni concorrente vengono restituite due metriche di posizione:
avgMentionOrder— il KPI ordinale Position: rango medio tra tutti i brand nominati in una risposta (1 = nominato per primo, più basso è meglio). È il valore in stile#2.3mostrato nella pagina concorrenti della dashboard.averagePosition— Mention Depth: quanto in profondità nel testo della risposta compare la menzione (0% = all’inizio). Non è una posizione in classifica; mantiene questo nome per retrocompatibilità.
string
obbligatorio
Identificatore del progetto.
string
predefinito:"30d"
Finestra di analisi, es.
7d, 30d.string
Filtra i risultati di Tracking su un singolo modello.
string
Filtra i Prompt per lingua.
string
Array JSON o elenco di Tag dei Prompt separati da virgola.
string
Filtra per sottostringa del nome o del dominio del concorrente.
string
predefinito:"visibility"
Uno tra
visibility (nominato O citato), mentions, position, sentiment, name.string
predefinito:"desc"
asc o desc.integer
predefinito:"1"
Numero di pagina.
integer
predefinito:"50"
Dimensione della pagina (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
}
}
}