Finseo API

The Finseo Customer API exposes your tracking data over plain HTTPS with JSON responses. GET /v1/projects lists projects, /v1/projects/{id}/metrics returns the daily visibility KPIs with previous-period changes, /metrics/timeseries returns chart data, /prompts lists tracked prompts with metrics and lets you add new ones, /competitors returns the competitor visibility ranking, /sources returns the citation source ranking, /tags lists and creates tags, /fanouts returns AI query fan-outs, /tasks lists and fetches optimization tasks, /export delivers prompts with nested tracking results for BI tools, and /attribution submits, lists, bulk-imports, and summarizes attribution responses. GET /v1/me verifies a key and returns its account, tier, and scopes. Every response includes X-RateLimit headers.

1. 01

   Warehouse and BI pipelines

   Schedule a daily job that calls /metrics/timeseries and /competitors per project and loads the rows into BigQuery, Snowflake, or Postgres. AI visibility then sits next to Search Console and revenue data in your existing models.

2. 02

   Custom client dashboards for agencies

   Agencies with dozens of projects loop over /v1/projects, pull visibility rate, mentions, and position per client, and render them in their own reporting tool. A read-scoped key restricted to specific projects keeps client data separated.

3. 03

   Automated prompt management

   Use a write-scoped key to add prompts from a product catalog or keyword list through POST /prompts and tag them for branded versus non-branded reporting. The API enforces the same prompt limits as the dashboard.

4. 04

   Tasks in your own workflow

   Poll /tasks for new AI-generated optimization tasks sorted by priority score, then create tickets in your own system with the full description, step-by-step plan, and evidence from /tasks/{taskId}.

5. 05

   Attribution at scale

   Submit "How did you hear about us?" answers and conversions from your backend through POST /attribution or bulk-import historical survey data, then read revenue per AI engine from /attribution/summary.

AI search is a new channel, and most teams already have a reporting stack they trust. If AI visibility data lives only inside another dashboard, it never reaches the models, alerts, and reviews that drive decisions. The Finseo REST API returns exactly the numbers shown in the dashboard, with explicit metric names for visibility rate, mention rate, citation rate, and position, so Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO) can be measured with the same rigor as classic SEO. Bulk export and attribution endpoints close the loop from ChatGPT and Perplexity citations to revenue.

1. 01

   Create an API key

   In the Finseo dashboard, go to Settings, API, and click Create API Key. Choose a name, the scopes you need (read, write, export), and optionally restrict the key to specific projects. Copy the key immediately; it is shown only once.

2. 02

   Verify the key

   Call GET https://api.finseo.ai/v1/me with the header Authorization: Bearer YOUR_API_KEY. The response returns the account, tier, project count, and scopes, and works even before the account has any projects.

3. 03

   List your projects

   Call GET /v1/projects to fetch the project IDs your key can access. Every other endpoint is scoped to a projectId from this list.

4. 04

   Pull metrics and rankings

   Request /v1/projects/{id}/metrics?timeframe=30d for the current KPIs with changes, /metrics/timeseries for daily chart data, /competitors for the ranking, and /sources for top cited domains. Add model or tags parameters to filter.

5. 05

   Automate and respect limits

   Tracking data updates once daily, so cache responses and schedule pulls accordingly. Use /export for bulk data instead of many small calls, and implement exponential backoff on 429 responses using the Retry-After header.

How do I authenticate with the Finseo API?

Send your API key as a Bearer token in the Authorization header on every request to https://api.finseo.ai/v1. Keys are created under Settings, API in the Finseo dashboard, where you pick a name, scopes, and optional project restrictions. An invalid or revoked key returns a 401 with the code UNAUTHORIZED.

Send your API key as a Bearer token in the Authorization header on every request to https://api.finseo.ai/v1. Keys are created under Settings, API in the Finseo dashboard, where you pick a name, scopes, and optional project restrictions. An invalid or revoked key returns a 401 with the code UNAUTHORIZED.

Which endpoints does the API offer?

Endpoint groups cover projects (list, create, get, update), prompts (list with metrics, add), metrics (daily KPIs and timeseries), competitors, sources, tags, fan-outs, tasks, export, and attribution. GET /v1/me returns the account and scopes behind a key. The full reference with a playground lives at docs.finseo.ai.

Endpoint groups cover projects (list, create, get, update), prompts (list with metrics, add), metrics (daily KPIs and timeseries), competitors, sources, tags, fan-outs, tasks, export, and attribution. GET /v1/me returns the account and scopes behind a key. The full reference with a playground lives at docs.finseo.ai.

What scopes and restrictions do keys support?

Keys can carry the read scope for projects, prompts, metrics, competitors, and sources, the write scope to create prompts, update tags, and manage projects, and the export scope for bulk data. A key can also be restricted to specific projects; without a restriction it accesses all projects the account owns.

Keys can carry the read scope for projects, prompts, metrics, competitors, and sources, the write scope to create prompts, update tags, and manage projects, and the export scope for bulk data. A key can also be restricted to specific projects; without a restriction it accesses all projects the account owns.

What are the rate limits?

Limits apply per API key by plan: Creator 60 requests per minute and 5,000 per day, Business 120 per minute and 25,000 per day, Agency 300 per minute and 100,000 per day, Enterprise 600 per minute and 200,000 per day. Exceeding them returns 429 with a Retry-After header.

Limits apply per API key by plan: Creator 60 requests per minute and 5,000 per day, Business 120 per minute and 25,000 per day, Agency 300 per minute and 100,000 per day, Enterprise 600 per minute and 200,000 per day. Exceeding them returns 429 with a Retry-After header.

Do I need a specific plan for API access?

API access requires a paid Finseo plan, Creator or higher. Free accounts cannot create API keys. There is no separate API fee: keys, endpoints, and exports are included in every paid plan, with request and prompt limits scaling by tier.

API access requires a paid Finseo plan, Creator or higher. Free accounts cannot create API keys. There is no separate API fee: keys, endpoints, and exports are included in every paid plan, with request and prompt limits scaling by tier.

Do API numbers match the dashboard?

Yes. Every endpoint returns the same values as the Finseo dashboard for the selected timeframe, AI model, and tags, including visibility rate, mentions, position, citation rate, and sentiment. Tracking data updates once daily, so results are stable within a day and safe to cache.

Yes. Every endpoint returns the same values as the Finseo dashboard for the selected timeframe, AI model, and tags, including visibility rate, mentions, position, citation rate, and sentiment. Tracking data updates once daily, so results are stable within a day and safe to cache.

Can I filter by AI model, timeframe, or tag?

Yes. Endpoints accept a timeframe such as 7d, 30d, 90d, or 365d, or an absolute startDate and endDate pair, plus model and tags query parameters. Filtering server-side by tag is the recommended way to separate branded and non-branded prompts instead of fetching everything.

Yes. Endpoints accept a timeframe such as 7d, 30d, 90d, or 365d, or an absolute startDate and endDate pair, plus model and tags query parameters. Filtering server-side by tag is the recommended way to separate branded and non-branded prompts instead of fetching everything.

How do I export all data for BI tools?

Call GET /v1/projects/{projectId}/export with the export scope. It returns prompts with nested tracking results for the selected timeframe, up to 1,000 prompts, intended for offline analysis, BI tools, or backups. Use it instead of many individual requests when you need full history.

Call GET /v1/projects/{projectId}/export with the export scope. It returns prompts with nested tracking results for the selected timeframe, up to 1,000 prompts, intended for offline analysis, BI tools, or backups. Use it instead of many individual requests when you need full history.