Tools - Promptwatch API Documentation

The Promptwatch MCP server exposes the tools below. You usually don’t need tool names, just ask in plain English. Use this page when you’re writing a skill, debugging a workflow, or want to know exactly what the server can do. Most are read-only (they only query your data); a smaller set create, update, or delete records and are marked accordingly. Every tool carries machine-readable annotations (readOnlyHint, destructiveHint, idempotentHint) so MCP clients can surface and gate them appropriately.

All tools are scoped to the organization and project(s) tied to your API key or OAuth session and require a valid projectId (except listProjects, createProject, setupProject, getUsage, and listModels).

Projects & models

Tool	Access	Description
`listProjects`	Read	List all projects in your organization with their ids, names, and websites
`createProject`	Create	Create a new project (a brand/website to track)
`setupProject`	Create	Create a project, enrich it from its website, and generate up to 3 monitors with prompts
`getUsage`	Read	Organization usage and effective limits (plan, custom overrides, add-ons) plus per-project breakdown (organization-level key required)
`listModels`	Read	List the LLM models Promptwatch can monitor

Monitors

Tool	Access	Description
`listMonitors`	Read	List monitors (recurring prompt-run configurations) with their visibility metrics
`getMonitor`	Read	Get a single monitor’s configuration and metrics
`createMonitor`	Create	Create a new monitor; optionally pass `initialPrompts` and/or `generatePrompts`
`updateMonitor`	Update	Update a monitor’s name, models, active state, or location
`deleteMonitor`	Delete	Delete a monitor and stop its scheduled runs

Prompts

Tool	Access	Description
`listPrompts`	Read	List tracked prompts with pagination, search, and filters
`getPrompt`	Read	Get a single prompt by ID
`createPrompt`	Create	Create a new prompt to track in a monitor
`createPromptsBulk`	Create	Create multiple prompts at once
`deletePrompt`	Delete	Delete a prompt
`deletePromptsBulk`	Delete	Delete multiple prompts
`activatePrompts`	Update	Activate prompts so they run in monitors
`deactivatePrompts`	Update	Deactivate prompts (history is kept)
`attachTagsToPrompt`	Update	Attach tags to a prompt
`attachTagsToPromptsBulk`	Update	Attach tags to multiple prompts

Visibility & sentiment

Tool	Access	Description
`getVisibilityTimeSeries`	Read	Brand visibility score over time, with model/prompt/monitor filters
`listEvents`	Read	Project events grouped by UTC day (prompts added/deleted, actions completed); page/size paginate completed actions
`getSentimentTimeSeries`	Read	Brand sentiment score over time, with model/prompt/monitor filters

Citations

Tool	Access	Description
`getCitations`	Read	Citation analytics: domain/URL frequency, traffic, and authority scores
`getSelfCitationFrequency`	Read	How often AI answers cite your own domain over time
`getCitationDomainsOverTime`	Read	Citation counts per cited domain over time
`getCitationRankAnalysis`	Read	Your domain’s rank among all cited domains over time
`getCitationTopPages`	Read	Most-cited pages with citation counts and average rank
`getCitationLlmSources`	Read	Top cited sources with per-source citation stats
`getCitationDomainsByLlm`	Read	Domain citations broken down by LLM model

Page tracker

Watch specific URLs and see which prompts and AI answers cite them. Date filters default to today only and reject future dates.

Tool	Access	Description
`listPageTrackers`	Read	List tracked URLs with citation totals (uncited pages stay, at zero)
`getPageTracker`	Read	Get one tracked URL with its citation totals for a period
`addPageTracker`	Create	Track up to 100 URLs; already-tracked URLs are skipped
`removePageTracker`	Delete	Stop tracking a URL (past responses and citations are kept)
`listPageTrackerResponses`	Read	AI responses that cited a tracked URL, newest first
`listPageTrackerPrompts`	Read	Prompts whose answers cited a tracked URL

Responses

Tool	Access	Description
`listResponses`	Read	List collected AI responses with pagination and filters
`getResponse`	Read	Get a single AI response with its full text and citations
`getResponsesSummary`	Read	Total responses and brand mentions for a date range
`getMentionsTimeSeries`	Read	Brand and competitor mentions over time
`getTopCompetitors`	Read	Competitors mentioned most in AI responses
`getResponseSentimentDistribution`	Read	Positive/neutral/negative split of responses
`getResponseSentimentTimeSeries`	Read	Response sentiment over time

Brands & competitors

Tool	Access	Description
`listBrands`	Read	List brands detected in AI answers (own brand, competitors, others)
`createBrand`	Create	Create or link a brand with its relation to your brand
`updateBrand`	Update	Update a brand’s relation (e.g. competitor, ignored)
`getBrandVisibilityOverTime`	Read	Visibility over time for all tracked brands, for comparison. The SELF brand is always included unless excludeSelf is true
`getCompetitorHeatmap`	Read	Brands-by-models visibility list
`getPerformanceHeatmap`	Read	Heatmap for two axes and one metric. Axes are Brands, Models, Topics, and Countries. Metrics are Visibility, Sentiment, Position, Share of Voice, and Win Rate. Defaults to Brands by Models with Visibility

Content gaps & content

Tool	Access	Description
`getContentGapStats`	Read	How well your site content covers the topics your prompts ask about
`listContentGapPrompts`	Read	Prompts with content-coverage scores, to find gaps
`getContentGapLatest`	Read	Latest content-coverage analysis for a prompt
`getContentGapRecommendations`	Read	Recommendations for closing a prompt’s coverage gap
`listQueryFanouts`	Read	Prompts with query fanouts extracted from AI responses (sub-queries the model searched)
`listContent`	Read	List AI-generated content documents (summary fields)
`getContent`	Read	Get a content document including its full markdown body, title, and nullable `metaTitle`
`createContent`	Create	Generate new content, or refresh (optimize) an existing page

Reports

Generate PDF Reports of a project’s dashboard. Creation is asynchronous — poll getReport until status is complete, then use the returned Download URL. Email delivery is not available through these tools.

Tool	Access	Description
`createReport`	Create	Queue a PDF Report; returns `{ reportId, status }` without waiting for the PDF
`getReport`	Read	Get Report status; when `complete`, includes a fresh Download URL
`listReports`	Read	List project Reports (newest first)

Dashboards

Build and change custom dashboards from widgets, saved filters and widget settings, or start from a template. New dashboards are personal unless you pass scope: TEAM; API keys can only create team dashboards. updateDashboard replaces the whole widget list or filters, so read the dashboard first and pass its version.

Tool	Access	Description
`listDashboards`	Read	List team dashboards and your personal ones, with filters and widgets
`getDashboard`	Read	Get one dashboard with its filters, widgets and current version
`createDashboard`	Create	Create a dashboard from widgets or a template
`updateDashboard`	Update	Change a dashboard’s widgets, filters, name or icon

Publishing

Take a generated document live and start tracking the published page. setContentPublication and publishContentLive both add the resulting URL to your page tracker, so citations to it are picked up from then on.

Tool	Access	Description
`listCmsConnections`	Read	List Webflow/Framer connections and whether each can publish
`getContentPublishStatus`	Read	A document’s CMS push history, plus the most recent record
`setContentPublication`	Create	Record the live URL of a page published outside a CMS, and track it
`clearContentPublication`	Delete	Unlink a document from its published URL (the tracked page is kept)
`pushContentDraft`	Create	Write a document to the connected CMS as an unpublished draft
`publishContentLive`	Create	Publish a staged CMS draft to the live site

publishContentLive makes content publicly visible on your site and cannot be undone from Promptwatch. Connections themselves are set up in the dashboard — the tools can publish through them, but not create or reconfigure them.

Tags & personas

Tool	Access	Description
`listTags`	Read	List tags with prompt counts
`createTags`	Create	Create tags for grouping prompts
`renameTag`	Update	Rename a tag
`deleteTag`	Delete	Delete a tag
`listPersonas`	Read	List personas (audience profiles)
`getPersona`	Read	Get a single persona
`createPersona`	Create	Create a persona for monitors and content generation, including optional age, education, and gender
`updatePersona`	Update	Update a persona
`deletePersona`	Delete	Delete a persona

Action items

Tool	Access	Description
`listActionItems`	Read	List paginated GEO action items (page/size; defaults to non-dismissed page 1, size 50; pass status=dismissed for dismissed actions)
`updateActionItemStatus`	Update	Update an action item status (accept, dismiss, complete, etc.)

Site audit

Tool	Access	Description
`listSiteAuditRuns`	Read	Audit runs, newest first, with health score, coverage and issue totals by severity
`getSiteAuditRun`	Read	One run’s health score, coverage, response-time averages and per-check summaries. Omit `runId` for the newest finished run
`listSiteAuditIssues`	Read	URLs a run flagged, errors first. Filter with `issues`, `severity` or `search`. Response includes `runId`; pass it back with `cursor`
`listSiteAuditFailingUrls`	Read	URLs the run could not fetch, with status, timing and how many consecutive runs each has been failing. Response includes `runId`; pass it back with `cursor`
`getSiteAuditLinkInsights`	Read	Link findings. `kind` is `orphans`, `brokenLinks`, `coverageGaps` or `navOnly`. Response includes `runId`; pass it back with `cursor`
`getSiteAuditContentInsights`	Read	Content findings. `kind` is `thin`, `duplicates`, `stale`, `changed` or `duplicateTitles`. Response includes `runId`; pass it back with `cursor`
`getSiteAuditProfile`	Read	Link profile, content profile and the slowest pages by time to first byte
`getSiteAuditUrlHistory`	Read	Check history for one URL across runs, newest first

Sitemap

Tool	Access	Description
`getSitemapProgress`	Read	Sitemap crawl progress. `crawlHealthScore` is crawl coverage, not the site audit health score (`getSiteAuditRun`)

Traffic analytics

Tool	Access	Description
`getVisitorTotal`	Read	Total visitor counts over time
`getVisitorTrend`	Read	Visitor trends by referrer over time (see AI-driven traffic)
`getVisitorReferrerStats`	Read	Referrer stats with period-over-period changes
`getVisitorTopPages`	Read	Top pages by visits, filterable to AI-referred traffic
`getVisitorTopSources`	Read	Top visitor sources
`getVisitorTopLocations`	Read	Top visitor locations
`getVisitorTopDevices`	Read	Top visitor devices
`getVisitorTopBrowsers`	Read	Top visitor browsers
`getCrawlerTrend`	Read	AI crawler (GPTBot, ClaudeBot, …) activity over time from server/CDN logs
`getTopCrawlerPages`	Read	Pages AI crawlers request most

Search insights

Google Search Console and Bing Webmaster performance for the project website, one engine at a time. Requires the matching integration to be connected in the dashboard. Google uses the requested calendar window; Bing uses complete Sat–Fri weeks, so the two will not always cover the same days. An unconnected engine returns zeros or empty rows rather than an error.

Tool	Access	Description
`getGoogleSearchInsightsPages`	Read	Google clicks, impressions, and position per pathname (paginated)
`getGoogleSearchInsightsTrend`	Read	Daily Google clicks and impressions (defaults to the last 30 days, max 92)
`getBingSearchInsightsPages`	Read	Bing clicks, impressions, and position per pathname (paginated)
`getBingSearchInsightsTrend`	Read	Daily Bing clicks and impressions (defaults to the last 30 days, max 92)

Ads Radar

Sponsored ads captured in AI answers. Requires the Ads Radar plan feature.

Tool	Access	Description
`listAds`	Read	List captured ads with advertiser, creative, and source response
`listAdPrompts`	Read	Prompts whose AI answers contained ads, with per-prompt ad counts
`listAdDomains`	Read	Advertiser root domains ordered by ad count
`getAdDomainAnalytics`	Read	Top advertiser domains with daily ad counts

Shopping

Product appearances in AI shopping answers, plus your own tracked products. Requires the Shopping insights plan feature.

Tool	Access	Description
`listShoppingItems`	Read	List product appearances with price stats, merchants, and positions
`getShoppingItem`	Read	Get one product with appearance stats and its latest appearance
`getShoppingProductsOverTime`	Read	Daily count of product appearances
`getShoppingProductPositionAnalytics`	Read	Top products with daily average positions
`getShoppingTopMerchantDomains`	Read	Merchant domains ordered by product appearances
`getShoppingTopProducts`	Read	Products ordered by appearances
`listShoppingTrackedProducts`	Read	List tracked products and their matched extracted items
`addShoppingTrackedProducts`	Create	Track products by catalog ID; duplicates are skipped
`updateShoppingTrackedProduct`	Update	Update a tracked product’s name or description
`deleteShoppingTrackedProduct`	Delete	Stop tracking a product

​Projects & models

​Monitors

​Prompts

​Visibility & sentiment

​Citations

​Page tracker

​Responses

​Brands & competitors

​Content gaps & content

​Reports

​Dashboards

​Publishing

​Tags & personas

​Action items

​Site audit

​Sitemap

​Traffic analytics

​Search insights

​Ads Radar

​Shopping

Projects & models

Monitors

Prompts

Visibility & sentiment

Citations

Page tracker

Responses

Brands & competitors

Content gaps & content

Reports

Dashboards

Publishing

Tags & personas

Action items

Site audit

Sitemap

Traffic analytics

Search insights

Ads Radar

Shopping