API Changelog

Flat and CSV output for BI tools (v1.20.0). Read endpoints now accept an optional output parameter: output=flat returns the same metadata plus rectangular columns and rows, and output=csv returns those rows as text/csv. This lets Tableau (through its REST API Connector), Excel, Google Sheets and warehouse loaders read the API without code that walks the nested JSON. /metrics/sov also accepts view=over_time|current|breakdown. Omitting output returns the exact response existing integrations already receive. Errors are always JSON, percentages stay on the 0-100 scale, paginated endpoints expose X-Total-Count, X-Page and X-Per-Page headers, and flat output is capped at 200,000 rows.

Longer metric history windows. The maximum date window on the metrics endpoints (/metrics/*), the /dimensions/* listings, citation intelligence and AI model insights (REST and their MCP tool twins) is raised from 400 to 1500 days, enabling all-time queries. Search Console endpoints keep their 400-day window, which matches the GSC data retention we store. The Looker Studio connector gains "Last 365 days", "All time" and "Follow report date range" options plus three new report types (Prompt performance, Share of Voice, Top Sources) built on these endpoints.

Write API expansion: launch, update, delete (v1.19.0). Recommendations can now be launched via the API: POST /recommendations (MCP launch_recommendations) starts an async generation and returns the run to poll; the MCP tool no longer requires the in-app chat confirmation card (external clients launch directly, the in-app chat agent still asks for confirmation). New management endpoints, each with an MCP twin: DELETE /prompts/:id, PATCH/DELETE /competitors/:id, PATCH/DELETE /collections/:id, and a full annotations set (GET /annotations, PATCH/DELETE /annotations/:id, Growth+). Deletes are irreversible: rows disappear immediately and historical data is purged in the background. All write endpoints require a read_write API key and respect the team-member permission matrix.

MCP quality pass (from an external agent audit). Unknown model values and reversed from/to windows now return ERR_INVALID_PARAM instead of being silently ignored. GET /metrics/agent_traffic returns the new ERR_AGENT_TRAFFIC_NOT_CONNECTED when no agent-traffic source is connected. GET /metrics/top_sources avg_visibility is now the percentage of responses citing the domain (bounded 0-100). duration_ms fields are now real milliseconds. Additive fields: url_sha256 + created_at on source rows, matching_names on competitor list rows, score on sentiment categories, created_at on created annotations, data_through on Search Console responses (GSC publishes with a 2-3 day lag). MCP tools: list tools accept range, list_answers truncates responses to 1,500 chars by default (full_text=true for more), list_citation_groups url view is compact unless include_page_details=true, cited-URL tools accept a raw url alternative to url_sha256, get_sov defaults to all configured competitors, list_prompts gains a query search param, and not-found errors echo the requested id.

Lapsed subscriptions lose API access. When a self-serve subscription (Starter, Growth or Scale) is cancelled and its paid-through date has passed (after a short grace period), that account's API keys return 403 ERR_ACCOUNT_INACTIVE. Active subscriptions are unaffected, and so are invoice-paid and negotiated plans (Scale+ custom, Partner, Enterprise), which keep working while their billing is handled manually. Re-subscribe from the billing page to restore access. New error code: ERR_ACCOUNT_INACTIVE (403).

Top Sources visibility corrected. avg_visibility (and its avg_mention_rate alias) in GET /metrics/top_sources is now the share of valid responses that cite the domain: distinct citing responses divided by every valid response in the period. It previously counted source rows, so a response citing a domain three times counted three times, and divided only by the responses that had any source, which could report values above 100%. Expect lower, correct percentages. total_responses is unchanged.

Amazon Rufus model (v1.18.0). New AI model amazon_rufus (Amazon Rufus, Amazon's shopping AI assistant) available as an Enterprise add-on. The model filter on metrics, dimensions, answers and sentiments endpoints now accepts amazon_rufus. As with other add-on models, data only appears for accounts where the model is enabled.

Project draft wizard API (v1.17.0). Multi-step project creation with AI suggestions: POST /project_drafts starts a draft and suggests name/description/industry for the URL, PATCH /project_drafts/:id submits each step (details, prompts, competitors, owned media) under strict forward gating and returns suggestions for the next step, GET reads state (cache-only suggestions for safe polling), and POST .../finalize creates the project with the exact fast-mode effects, idempotently. New error codes ERR_DRAFT_NOT_FOUND and ERR_DRAFT_STATE. Drafts expire after 24 hours. Five MCP tool twins ship alongside: create_project, start_project_draft, get_project_draft, update_project_draft and finalize_project_draft, sharing the exact REST services.

Project creation API (v1.16.0). New POST /projects creates a complete project in one call (fast mode): project fields, prompts (queued for immediate execution and categorization), competitors, weekly email subscription. Idempotent replays via external_identifier (embed-enabled accounts) return the existing project with idempotent: true. Optional execute_prompts_immediately: false defers the first run to the next scheduled tracking window. Plan gates and quotas are enforced exactly like the in-app wizard (ERR_LIMIT_REACHED, ERR_QUOTA_EXCEEDED, ERR_PLAN_REQUIRED).

MCP usage guidance + richer project details (v1.15.6). The MCP server now returns usage instructions to connected AI clients on initialize: the recommended workflow, metric naming, efficiency tips, and the brand_kind=non_brand rule for fair brand-vs-competitor comparisons (matching the in-app Overview default). brand_kind and prompt_type filters added to all three GET /reports/ai_model_insights/* endpoints and their MCP tools (get_ai_model_summary, get_ai_model_position_distribution, get_ai_overview_results); invalid values return ERR_INVALID_PARAM. GET /dimensions/projects/:id (and the get_project_details MCP tool) now include stats.prompts_by_brand_kind plus a data_coverage block listing the models, countries and languages that actually have data, so one call replaces separate models/locales lookups.

Citation metric consistency (v1.15.4). Citations and Citation Rate now include visible citations and background source references across Overview, AI Model Insights, REST and MCP. Background citations have no visible rank and remain excluded from avg_position and position distributions. Source ownership now honors exact-subdomain matching consistently. By Domain remains a registrable-domain rollup. Response shapes are unchanged.

MCP Streamable HTTP notifications now return an empty 202 response. Strict clients such as Claude and Codex can complete initialization instead of failing when they parse a JSON null response.

MCP OAuth connections now expire after one year. Access and refresh credentials share one fixed authorization deadline. Refresh responses return the same reusable refresh token to avoid credential loss and concurrency failures in MCP clients.

REST and MCP unified on one shared query layer. The metrics endpoints (/metrics/timeseries, summary, sov, prompt_summary, top_sources, agent_traffic, ai_traffic) and every /dimensions/* listing now execute the same query code as their MCP tool twins, so both surfaces always return identical data. MCP tools gained the filters they were missing: prompt_type / brand_kind on get_prompt_summary, get_top_sources and the listing tools, plus source_type on list_sources (whose rows now include source_type and app-store link flags like REST). MCP input validation now matches REST: unknown collection_id / prompt ids, malformed dates and date windows above 400 days return errors instead of being silently ignored. list_prompts rows now include collection_ids, and REST summary rows now include the metric field MCP already returned. One intentional difference remains: in week/month granularity, MCP leaves periods before the first data point null for rate and position metrics so averages are not dragged down, while REST keeps backfilling 0.0.

Local businesses in answer details. GET /answers/:id (and the MCP tool get_answer) now include a local_businesses array: the businesses ChatGPT displays in its local results widget for local-intent prompts, with title, address, phone, review counts, rating, website domain and ranking position, each matched to your brand or a tracked competitor via is_owned / competitor_id.

Bug fixes. MCP get_timeseries and get_summary now return real values for net_sentiment, the five sentiment_* breakdowns and avg_mention_position (previously every data point was null via MCP; REST was unaffected), matching the REST metrics semantics. GET /dimensions/all_mentions and GET /dimensions/all_citations now paginate in the database with deterministic ordering on created_at ties, so deep pages are fast and stable on large projects; the response shape is unchanged. Custom per-key rate limits are now honored on the global API throttle (the default remains 300 requests/minute; contact us for higher quotas).

AI Traffic API (Scale+). New endpoint GET /metrics/ai_traffic exposes the AI-referred traffic we measure from a project's connected web analytics provider (Google Analytics 4, Adobe Analytics, PostHog, Plausible or Piano): per-day users, sessions and conversions grouped by AI source (ChatGPT, Perplexity, Gemini, Claude and others), with totals and a conversion rate. New MCP tool: get_ai_traffic. Requires the Scale plan or above and a connected provider; projects without one return the new ERR_AI_TRAFFIC_NOT_CONNECTED (404) code.

Search Console API (Growth+). New endpoints expose the Google Search Console performance data we already sync for projects with a connected GSC property: GET /search_console/summary (headline impressions, clicks, CTR, average position, with optional country/device breakdown), GET /search_console/timeseries (day/week/month series), GET /search_console/queries and GET /search_console/pages (top queries/pages ranked by impressions, clicks, CTR or position, paginated). ctr is a 0..1 fraction and position is the impression-weighted average, matching the Search Console API. New MCP tools: get_search_console_summary, get_search_console_timeseries, get_search_console_queries, get_search_console_pages. Projects without a connected property return the new ERR_SEARCH_CONSOLE_NOT_CONNECTED (404) code.

Mention share by citing domain + batch source filters. New endpoint GET /citation_intelligence/mentions_by_domain (and MCP tool get_mentions_by_citing_domain): for the responses where each given source domain is cited, returns the brand-vs-competitor mention share, normalized so each domain's actors sum to 100%. GET /metrics/top_sources and GET /citation_intelligence/groups (and their MCP tools) gain a domains array (exact domain whitelist) and a collection_ids array (filter by several tags at once), so a wide domain x tag matrix is one call instead of one call per cell.

Team-member permission matrix now enforced on the API and MCP. An API key (or MCP/chat-agent session) owned by a restricted team member is gated by the same feature matrix as the web app: endpoints and tools outside the member's granted features return 403 ERR_INSUFFICIENT_PERMISSION (new error code). Account-owner and admin keys are unaffected, so existing integrations keep working unchanged. Outbound webhooks are now their own grantable permission feature (still Scale+).

Correct period aggregates for rate metrics in GET /metrics/summary. The total field for percentage metrics (visibility/mention_rate, citation_rate, ai_visibility_score/weighted_visibility, sentiment shares) is now the average across periods instead of a sum of period rates, which could exceed 100%. Count metrics (mentions, citations, responses) are still summed. Each summary row now includes an aggregation field ("sum" or "average") stating how total was computed. The same fix applies to the MCP get_summary tool, which also stops echoing the full series alongside the summary (call get_timeseries for series data) and gains a group_by argument (model or collection) returning one summary per group in a single call. GET /answers (and the MCP list_answers tool) accept a new query param for case-insensitive full-text search inside AI response texts: total becomes the exact match count and rows return a snippet + match_count instead of the full response text.

Team-member prompt permission and per-project prompt limits. Account owners can now turn off a team member's ability to add or delete prompts. When a member's permission is off, POST /prompts and the create_prompts MCP tool return 403 ERR_INSUFFICIENT_SCOPE for that member's key (read endpoints are unaffected). Owners can also set a per-project prompt limit in Project Settings; once a project reaches it, POST /prompts and create_prompts return ERR_LIMIT_REACHED (alongside the existing account-wide quota check) for everyone, including the owner, until the limit is raised. No new error codes or endpoints.

New MCP tool get_webhook_sample (Scale+), the MCP counterpart of GET /webhooks/sample/:event_type, so MCP clients can preview event payloads before subscribing. Plan gating aligned for the AI bot catalog: REST GET /dimensions/agent_bots now requires Scale or above (ERR_PLAN_REQUIRED below), while the MCP tool list_agent_bots is now available on every plan.

Outbound Webhooks (Scale+, v1.9). New endpoints: POST /webhooks (subscribe a public HTTPS URL to a project event), GET /webhooks (list subscriptions), DELETE /webhooks/:id (unsubscribe), GET /webhooks/sample/:event_type (example payloads for integration editors). Seven event types: mention.created, competitor_mention.created, citation.created, prompt_execution.completed, sentiment.negative_detected, recommendation.completed, intelligence_task.completed. Deliveries are HMAC-SHA256 signed (X-LLMPulse-Signature), retried 5 times with backoff, and subscriptions auto-disable after 20 consecutive failures. Create/delete require a read_write scope key. New MCP tools: create_webhook_subscription, list_webhook_subscriptions, delete_webhook_subscription. Webhooks power the new Zapier, Make and n8n connectors.

Content Intelligence renamed to GEO Writer. The feature and its API section are now labelled GEO Writer across the app and docs. This is a display-only rename: API endpoints (POST/GET /intelligence_tasks, GET /intelligence_tasks/:id), request/response shapes, error codes, and MCP tool names (create_intelligence_task, list_intelligence_tasks, get_intelligence_task) are unchanged. The marketing page moved from /features/content-intelligence to /features/geo-writer with a 301 redirect.

MCP available on every plan via OAuth. The MCP endpoint (POST /api/v1/mcp) now accepts OAuth 2.1 access tokens issued via Dynamic Client Registration (RFC 7591) and PKCE-S256. Any LLM Pulse user, including Starter, Growth and trial users, can connect ChatGPT, Claude, Gemini, Cursor or any other MCP-compatible client to their account by pasting the URL https://api.llmpulse.ai/api/v1/mcp into their client's MCP / connector settings; the client walks the user through an OAuth sign-in flow with no API key required. Per-tool plan gating still applies: write tools and advanced read tools that require Growth or Scale continue to be filtered out of tools/list for users without access. API-key auth (Authorization: Bearer …) is unchanged and remains the recommended path for headless integrations like Data Studio, Zapier and CI scripts (Scale plan and above). Discovery endpoints (/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource, /oauth/jwks.json) and registration/authorize/token endpoints live under /oauth/*.

New recommendation type: Sentiment & Reputation (Scale+). recommendation_type on GET /recommendations (and the launch_recommendations MCP tool) now accepts sentiment_reputation in addition to ai_visibility, social_community and brand_building. It turns the last 30 days of brand sentiment (widening to 90 if sparse), negative themes, comparative gaps where a competitor is praised, the cited sources behind negative answers, and weak reputation dimensions, into actionable recommendations. Requires the Scale plan or above; non-entitled users get ERR_INVALID_PARAM/plan errors.

Prompt categorization filters. Every prompt is now auto-classified by prompt_type (search intent: informational, navigational, commercial, transactional) and brand_kind (brand = your own brand/products, brand_other = competitors or other brands, non_brand = generic, no brand named). Both are accepted as optional filters on /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources and /dimensions/prompts (which now also returns the two fields per prompt). Invalid values return ERR_INVALID_PARAM. The same filters are available as prompt_type / brand_kind args on the MCP tools get_timeseries, get_summary, get_sov and list_prompts.

Agent Write Endpoints (v1.5). API keys now expose a scope (read vs read_write); pre-existing keys treat full as a synonym of read_write. Mutation endpoints (POST/PATCH/PUT/DELETE) now require a read_write scope key and return 403 ERR_INSUFFICIENT_SCOPE otherwise. A second rate-limit bucket (60/min/key) is enforced on writes on top of the global 300/min/key budget. New REST endpoints: POST /competitors, POST /collections, POST /prompts/assign_tags (idempotent bulk tagging), POST /annotations (Growth+), POST /technical_geo_reports (full GEO bundle). New MCP write tools: create_competitor, create_collection, assign_prompt_tags, create_annotation, launch_recommendations (with pre-hoc user confirmation in the chat agent), create_technical_geo_report (idem). New error codes: ERR_INSUFFICIENT_SCOPE (403) for read-only keys hitting writes, ERR_PLAN_REQUIRED (403) for annotations on Starter.

Projects now expose brand_name separately from name in API and MCP payloads. brand_name is the brand label sent to LLMs and shown in customer-facing charts; name remains the internal project label. name is still returned for back-compat. mention_rate accepted as a synonym for visibility in /metrics/* params and in MCP timeseries / summary / top_sources tools. Per-user AI model flags now apply to every read endpoint: API responses, metrics, dimensions, answers, sentiments and citations silently exclude models that aren't enabled for the API key's user (used by add-on models, Copilot, Claude, Grok, DeepSeek, Meta AI, so partners can sell them à la carte). Date-bucketed metrics standardized on Europe/Madrid for daily/weekly/monthly buckets, fixing off-by-one-day rows near midnight UTC.

Agent Analytics API (Scale+, Beta): GET /metrics/agent_traffic and GET /dimensions/agent_bots surface AI bot crawler traffic (GPTBot, PerplexityBot, ClaudeBot, OAI-SearchBot, Google-Extended, and ~25 others) from Cloudflare or CSV uploads. New MCP tool: get_agent_traffic. MCP tools/list is now filtered by your plan, tools you can't use no longer appear in the catalog, and direct calls to gated tools return a clean ERR_PLAN_REQUIRED instead of leaking schema. MCP auth boundaries hardened for member-of-owner access.

Citation Intelligence API: GET /citation_intelligence/groups (cited-URL clusters with source/type filters), GET /citation_intelligence/urls/:url_sha256, /occurrences and /content for per-URL drill-down. AI Model Insights Reports API: GET /reports/ai_model_insights/summary, /position_distribution and /ai_overview_results. Recommendations API: GET /recommendations and GET /recommendations/:id. New MCP tools: list_citation_groups, get_cited_url_details, list_cited_url_occurrences, get_cited_url_content, get_ai_model_summary, get_ai_model_position_distribution, get_ai_overview_results, list_recommendations, get_recommendation, list_competitor_mentions, list_competitor_citations, list_prompt_executions, list_tags. Stricter enum validation across view, order, direction, granularity, model, source_type, sentiment, content_gap, recommendation_type, status, unknown values now return ERR_INVALID_PARAM instead of being silently ignored. source_type filter accepts owned, competitor, third_party in addition to classification lists. AI Overview results bucket by executed_at (not created_at), so retried/backfilled rows land in the correct day.

New POST /prompts endpoint for bulk prompt creation (up to 100 per request). New Content Intelligence API: POST /intelligence_tasks to create tasks, GET /intelligence_tasks to list with filters, GET /intelligence_tasks/:id for full details and results. New MCP tools: create_prompts, create_intelligence_task, list_intelligence_tasks, get_intelligence_task. New error codes: ERR_LIMIT_REACHED (prompt quota), ERR_QUOTA_EXCEEDED (intelligence task quota), ERR_NOT_FOUND (resource not found).

New endpoint GET /metrics/prompt_summary for paginated per-prompt metrics (responses, mentions, citations, visibility, citation_rate) in a single request

Added ai_visibility_score metric (position-weighted visibility). New MCP tools: list_answers, get_answer, list_detailed_sentiments, get_project_details, get_competitor_details. New API endpoints: /answers, /sentiments, /dimensions/projects/:id, /dimensions/competitors/:id. Added responses metric (prompt execution count) and citation_rate metric (citations / responses x 100). API rate limits increased from 100 to 300 requests/minute. Added prompt filter to all metrics and dimensions endpoints.

Added MCP (Model Context Protocol) endpoint for AI integrations with Claude, ChatGPT, and other AI assistants

Sentiment metrics added to /metrics/timeseries (sentiment_very_positive/positive/neutral/negative/very_negative) and documented semantics

Metrics aligned with Overview (period totals with sticky, ratio-of-period-sums for visibility, propagation in avg_position), SOV breakdown, query filter in Top Sources, caching notes, Postman download & environment section

Initial public API docs (v1)