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, 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)
`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 for selected models, location, and persona
`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
`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
`getCompetitorHeatmap`	Read	Competitor visibility heatmap per LLM model

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
`createContent`	Create	Generate new content or optimize an existing page

Reports

Generate PDF Reports of project visibility data (dashboard or monitor). 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)

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
`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 health

Tool	Access	Description
`getSiteHealth`	Read	Pages with SEO issues (missing title/description, H1 problems, thin content); optional issueTypes filter

Sitemap

Tool	Access	Description
`getSitemapProgress`	Read	Sitemap crawl progress for your website

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

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

​Publishing

​Tags & personas

​Action items

​Site health

​Sitemap

​Traffic analytics

​Ads Radar

​Shopping

Projects & models

Monitors

Prompts

Visibility & sentiment

Citations

Page tracker

Responses

Brands & competitors

Content gaps & content

Reports

Publishing

Tags & personas

Action items

Site health

Sitemap

Traffic analytics

Ads Radar

Shopping