List Competitors

curl --request GET \
  --url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
  --header 'Authorization: Bearer sk_live_xxxxxxxx'

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": 412,
        "visibleResults": 186,
        "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": 389,
        "visibleResults": 172,
        "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
    }
  }
}

GET

projects

{projectId}

competitors

curl --request GET \
  --url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
  --header 'Authorization: Bearer sk_live_xxxxxxxx'

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": 412,
        "visibleResults": 186,
        "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": 389,
        "visibleResults": 172,
        "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: mentions, visibility, Share of Voice, position, and sentiment. Use this to see how Finseo stacks up against other brands in ChatGPT, Claude, and Perplexity answers. Two position metrics are returned per competitor (see KPIs explained):

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:"mentions"

One of visibility, 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 sk_live_xxxxxxxx'

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": 412,
        "visibleResults": 186,
        "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": 389,
        "visibleResults": 172,
        "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
    }
  }
}

Projects

Prompts

Metrics

Competitors

Sources

Tags

Fan-outs

Tasks

Export

Attribution

List Competitors