> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finseo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Competitors

Returns ranked competitors for AI visibility: mentions, visibility, average position, and sentiment. Use this to see how Finseo stacks up against other brands in ChatGPT, Claude, and Perplexity answers.

<ParamField path="projectId" type="string" required>
  Project identifier.
</ParamField>

<ParamField query="timeframe" type="string" default="30d">
  Analysis window, e.g. `7d`, `30d`.
</ParamField>

<ParamField query="model" type="string">
  Filter tracking results to one model.
</ParamField>

<ParamField query="language" type="string">
  Filter prompts by language.
</ParamField>

<ParamField query="tags" type="string">
  JSON array or comma-separated prompt tags.
</ParamField>

<ParamField query="search" type="string">
  Filter by competitor name or domain substring.
</ParamField>

<ParamField query="sortBy" type="string" default="mentions">
  One of `visibility`, `mentions`, `position`, `sentiment`, `name`.
</ParamField>

<ParamField query="sortDir" type="string" default="desc">
  `asc` or `desc`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Page size (1–500).
</ParamField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl --request GET \
    --url 'https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/competitors?timeframe=30d&sortBy=mentions&limit=20' \
    --header 'Authorization: Bearer sk_live_xxxxxxxx'
  ```

  ```python Python theme={"system"}
  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"]])
  ```
</RequestExample>

<ResponseExample>
  ```json theme={"system"}
  {
    "data": {
      "competitors": [
        {
          "id": "c7d8e9f0-a1b2-4345-cdef-678901234abc",
          "name": "Finseo",
          "domain": "finseo.ai",
          "baseDomain": "finseo.ai",
          "isStarred": true,
          "isUserBrand": true,
          "totalMentions": 412,
          "visibleResults": 186,
          "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,
          "averagePosition": 21.4,
          "sentimentScore": 0.62,
          "promptCount": 42
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 20,
        "total": 15,
        "hasMore": false
      }
    }
  }
  ```
</ResponseExample>