Skip to main content

​
Changelog

​
September 2026

​
Model settings and account limits are now identical in the API and the dashboard

Prompts created via the API could run on models that were not enabled in the project’s Model Settings, so the dashboard filters showed fewer models than the prompts actually tracked. The API now uses the project’s model settings as its source of truth and applies every limit the dashboard applies, with the same error codes. See Automate a pitch for the end-to-end agency flow.
  • PUT /projects/{projectId} accepts models — the API counterpart of the Model Settings page. Replaces the set, re-syncs every prompt of the project (syncedPromptCount) and enforces the plan model cap, the Brand prompt budget and the Agency answer projection (meteredNotice on the top package)
  • GET /projects, GET /projects/{projectId} and POST /projects return models (project setting → account default) and language
  • POST /projects/{projectId}/prompts: models is optional and defaults to the project’s models; an explicit list must be a subset of them, otherwise 400 model_not_enabled. New Agency answer-projection guard, same as the dashboard
  • POST /projects applies the dashboard’s project gates: pitch projects require an Agency account and a free pitch slot, client projects a free slot on Agency packages (agency_limit), and the plan project cap on Brand plans
  • Errors: limit violations now return 403 FORBIDDEN with a machine-readable error.details.reason (agency_limit, prompt_budget_exceeded, prompt_limit, model_limit, model_not_available, pitch_prompt_limit, pitch_expired, pitch_project_limit) instead of a generic 500
  • MCP list_projects returns language, isPitch and models per project

​
Visibility = named OR cited; new Mention Rate and Citation Rate

Finseo now separates the two ways a brand appears in an AI answer — named in the answer text and cited as a source — and reports them as distinct KPIs. See KPIs explained.
  • Visibility redefined: an answer counts as visible when the brand is named in the text or its own domain (or a configured domain alias) is cited as a source. Previously only text mentions counted, so Visibility can be slightly higher than before for brands whose sites are cited without being named
  • New KPIs: Mention Rate (share of answers naming the brand) and Citation Rate (share of answers citing the own domain), both on the same denominator as Visibility. They overlap, so Visibility ≤ Mention Rate + Citation Rate
  • REST /metrics returns mentionRate, citationRate, cited per period plus mentionRateChange, citationRateChange, citedChange; responseVisibilityRate now uses the named-or-cited definition
  • REST /metrics/timeseries adds cited per day (null for days served from rollups without citations)
  • REST /competitors adds mentionRate, mentionRateChange, totalCitations, citationRate, citationRateChange and visibilityIsMentionOnly; visibilityRate/visibleResults now use the named-or-cited definition. Default sortBy is visibility
  • REST /prompts adds mentionRate and citationRate per prompt; isVisible uses the named-or-cited definition
  • MCP: get_visibility_metrics and get_visibility_timeseries return mentionRatePercent, citationRatePercent and ownDomainCitedAnswers; get_competitor_ranking returns mentionRatePercent, citationRatePercent and visibilityIsMentionOnly; list_prompts returns mentionRatePercent and citationRatePercent. visibilityRatePercent everywhere follows the named-or-cited definition and the tool notes explain the split
  • Domain aliases: additional domains for citation matching (e.g. country TLDs, shop subdomains) can be configured per project in the dashboard settings; they apply to all prompts of the project

​
Fix: prompts created via POST /prompts are processed immediately

Prompts added through the REST API were saved but not queued for the workers, so they only got picked up by the nightly sweep — and on a fresh project they were stored without the project’s domain and brand name, which meant the brand could never be recognised in answers.
  • Prompts are now queued right away (enqueued: true in the response); first answers typically arrive within minutes
  • The prompt inherits the project’s domain, brand name (project name), synonyms, domain aliases and tracking frequency. Projects without a websiteUrl are rejected with 400
  • language now defaults to the project language and is normalised to the dashboard spelling (de → DE), so the country filter matches prompts added via the API

​
Pitch projects + required language

  • Pitch projects via API: POST /v1/projects accepts isPitch and pitchDurationDays (1, 7 or 14, default 14) — no project fee, capped at 50 prompts, auto-paused when the pitch window closes. Pitch slots are capped per agency package (250 on Agency Starter, 500 on Agency Studio)
  • Convert won pitches: PUT /v1/projects/{projectId} with {"convertFromPitch": true} turns a pitch into a full client project (checks a free client slot and the plan’s answer budget, then reactivates paused prompts)
  • language is now required on POST /v1/projects — one of 22 supported codes (en, de, fr, es, it, nl, pt, pl, sv, da, tr, ja, no, fi, cs, ru, zh, zh-tw, ko, hi, ar, he). Previously the language was inferred from a site crawl, which often defaulted to English for non-English markets
  • GET /v1/projects now returns isPitch on every project, plus pitchDurationDays and pitchExpiredAt on pitch projects

​
August 2026

​
Clear position semantics + full competitor KPI set

  • MCP get_competitor_ranking now returns the full dashboard KPI set per competitor: avgMentionOrder (ordinal Position KPI, 1 = named first), mentionDepthPercent, shareOfVoicePercent, firstMentionSharePercent, top3MentionSharePercent, head-to-head (h2hYouFirstPercent) and citation share — with a note explaining each metric
  • MCP field renames for clarity: the text-depth metric formerly reported as avgPositionPercent/avgPosition is now mentionDepthPercent across get_visibility_metrics, get_visibility_timeseries, list_prompts and get_prompt_details; get_visibility_timeseries additionally returns the per-day ordinal avgMentionOrder
  • REST /competitors now additionally returns avgMentionOrder (+change), shareOfVoicePercent (+change), firstMentionSharePercent and top3MentionSharePercent; averagePosition (mention depth) is unchanged for backwards compatibility

​
Custom date ranges

  • startDate/endDate query parameters (YYYY-MM-DD, always together) on /metrics, /metrics/timeseries, /competitors, /sources and /export — absolute ranges that override the relative timeframe
  • MCP tools accept startDate/endDate on all analytics tools (get_visibility_metrics, get_visibility_timeseries, get_competitor_ranking, get_top_sources, get_query_fanouts, get_competitor_gap_analysis, get_competitor_h2h, get_sentiment_overview)
  • /metrics compares a custom range against the equally long period immediately before it

​
March 2026

​
v1.0.0 - Initial Release

  • Customer API with 14 endpoints for projects, prompts, metrics, competitors, sources, tags, and export
  • API Key authentication with granular scopes (read, write, export) and project restrictions
  • Rate limiting per plan (Starter: 60/min, Pro: 180/min, Enterprise: 600/min)
  • MCP Server for Claude Desktop and Cursor integration