> ## 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.

# Introduction

> The Finseo API gives you programmatic access to your AI visibility tracking data.

# Finseo API

Track how your brand appears across ChatGPT, Claude, Perplexity and other AI platforms. The Finseo Customer API lets you retrieve visibility metrics, manage prompts, analyze competitors, and export data.

## Base URL

```
https://api.finseo.ai/v1
```

## Quick example

<CodeGroup>
  ```bash cURL theme={"system"}
  curl --request GET \
    --url https://api.finseo.ai/v1/projects/YOUR_PROJECT_ID/metrics?timeframe=30d \
    --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```python Python theme={"system"}
  import requests

  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  response = requests.get(
      "https://api.finseo.ai/v1/projects/YOUR_PROJECT_ID/metrics",
      headers=headers,
      params={"timeframe": "30d"}
  )

  data = response.json()["data"]
  print(f"Visibility Rate: {data['current']['visibilityRate']}%")
  print(f"Mentions: {data['current']['mentions']}")
  print(f"Change: {data['changes']['visibilityRateChange']:+.1f}%")
  ```

  ```javascript Node.js theme={"system"}
  const response = await fetch(
    "https://api.finseo.ai/v1/projects/YOUR_PROJECT_ID/metrics?timeframe=30d",
    { headers: { Authorization: "Bearer YOUR_API_KEY" } }
  );

  const { data } = await response.json();
  console.log(`Visibility: ${data.current.visibilityRate}%`);
  console.log(`Mentions: ${data.current.mentions}`);
  ```
</CodeGroup>

**Response:**

```json theme={"system"}
{
  "data": {
    "current": {
      "visible": 28,
      "notVisible": 14,
      "mentions": 156,
      "visibilityRate": 66.67,
      "position": 22.4,
      "sentiment": 0.78
    },
    "previous": {
      "visible": 22,
      "visibilityRate": 52.38
    },
    "changes": {
      "visibilityRateChange": 14.29,
      "mentionsChange": 38
    }
  }
}
```

## Response format

All endpoints return a consistent JSON envelope:

| Field   | Description                       |
| ------- | --------------------------------- |
| `data`  | The response payload              |
| `meta`  | Pagination info (when applicable) |
| `error` | Error details (only on failure)   |

## Error codes

| Code                    | Status | Description                       |
| ----------------------- | ------ | --------------------------------- |
| `UNAUTHORIZED`          | 401    | Missing or invalid API key        |
| `FORBIDDEN`             | 403    | Insufficient scopes               |
| `NOT_FOUND`             | 404    | Resource not found                |
| `VALIDATION_ERROR`      | 400    | Invalid parameters                |
| `RATE_LIMIT_EXCEEDED`   | 429    | Too many requests                 |
| `PROJECT_ACCESS_DENIED` | 403    | API key can't access this project |
| `INTERNAL_ERROR`        | 500    | Server error                      |

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Create and manage API keys
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/rate-limits">
    Request limits per plan
  </Card>

  <Card title="Customer API" icon="code" href="/api-reference/projects/list">
    Explore all endpoints
  </Card>

  <Card title="MCP Integration" icon="robot" href="/mcp/overview">
    Connect to Claude Desktop or Cursor
  </Card>
</CardGroup>