--- title: Promptwatch API Integration on Truto slug: promptwatch category: Analytics canonical: "https://truto.one/integrations/detail/promptwatch/" --- # Promptwatch API Integration on Truto **Category:** Analytics **Status:** Generally available ## MCP-ready AI tools Truto exposes 69 tools for Promptwatch that AI agents can call directly. - **list_all_promptwatch_auth_validates** — Validate the API key and return associated project and organization details. For organization-level keys, optionally provide X-Project-Id header to validate access to a specific project. - **list_all_promptwatch_brands** — Get all brands for the project. Favicons are available from a separate public endpoint (not part of API v2). See Brand icons. - **create_a_promptwatch_brand** — Create or connect a brand to the project. - **update_a_promptwatch_brand_by_id** — Update brand relationship. - **list_all_promptwatch_brands_visibility_over_times** — Get brand visibility over time. - **list_all_promptwatch_citations** — Get citation analytics including top cited domains, URLs, and authority metrics - **promptwatch_citations_list_domains_by_llm** — Get domain citations grouped by LLM source - **promptwatch_citations_list_domains_over_time** — Get domain citation frequency over time for top domains - **promptwatch_citations_list_llm_sources** — Get top LLM sources with citation statistics - **promptwatch_citations_list_rank_analysis** — Get citation rank analysis for your domain over time - **promptwatch_citations_list_self_frequency** — Get self-citation frequency over time (citations pointing to your own domain) - **promptwatch_citations_list_top_pages** — Get top cited pages with average rank - **list_all_promptwatch_competitor_heatmaps** — Get competitor visibility heatmap data showing visibility percentages across different models and competitors. Returns a structured matrix ready for heatmap visualization. - **list_all_promptwatch_content_gap_stats** — Get aggregate content coverage statistics for the project - **list_all_promptwatch_contents** — Paginated list of content documents for the project. Filter by mode (CREATE or OPTIMIZE) and/or status (PENDING, IN_PROGRESS, COMPLETED, FAILED, STOPPED) to narrow results. Each row includes status, mode, title, linked prompt id/text, and timestamps but omits the full markdown content body — use GET /content/:id for the complete document. Pagination uses size (page length) with total/page/totalPages in the response, matching other v2 list endpoints. - **get_single_promptwatch_content_by_id** — Returns the full detail of a content document including its current generation status, content body (when available), linked prompt, and timestamps. Use this endpoint to poll after POST /content/create. Status progresses as: PENDING (queued) → IN_PROGRESS (AI generating) → COMPLETED | FAILED | STOPPED. During IN_PROGRESS, title and content fields may be present but are incomplete — content streams in progressively and should not be treated as final. Both fields are null while PENDING and only fully reliable once status reaches COMPLETED. STOPPED documents may retain partial content. The failedAt/failedReason fields are populated when status is FAILED; stoppedAt is set when STOPPED. - **create_a_promptwatch_content** — Starts asynchronous AI content generation in one of two modes: CREATE (generate new content from a prompt) or OPTIMIZE (rewrite an existing page URL for better AI visibility). Returns the document id and PENDING status immediately — the document then transitions through IN_PROGRESS while the AI generates content, and reaches a terminal state of COMPLETED (success), FAILED (error), or STOPPED (manually cancelled). Poll GET /content/:id to track progress. Requires project API key (or org key + X-Project-Id). Prerequisites: GET /prompts (promptId), GET /personas (personaId); optional recommendation ids from content-gap endpoints. - **list_all_promptwatch_crawlers_events** — List individual AI crawler HTTP requests (event log) for the project, with pagination and filters. Same data as the in-product crawler activity explorer. - **list_all_promptwatch_crawlers_top_pages** — Get top pages requested by crawlers - **list_all_promptwatch_crawlers_trends** — Get crawler activity trends over time. If the crawlers query parameter is omitted, the response includes all known AI crawler types that have data in the selected range (the server queries the full set of allowed crawler keys). - **list_all_promptwatch_models** — List all available LLM models supported by Promptwatch - **list_all_promptwatch_monitors** — Get all active monitors for the current project with average visibility and response counts in a date range - **get_single_promptwatch_monitor_by_id** — Get a single monitor by ID with full details - **create_a_promptwatch_monitor** — Create a new monitor - **delete_a_promptwatch_monitor_by_id** — Soft-delete a monitor - **update_a_promptwatch_monitor_by_id** — Update an existing monitor - **create_a_promptwatch_persona** — Create a new persona for the project - **get_single_promptwatch_persona_by_id** — Get a specific persona by ID - **update_a_promptwatch_persona_by_id** — Update an existing persona - **list_all_promptwatch_personas** — List all personas for the project. - **delete_a_promptwatch_persona_by_id** — Delete a persona by its ID. - **list_all_promptwatch_projects** — List all projects for the organization. - **create_a_promptwatch_project** — Create a new project (requires org-level API key, X-Project-Id header NOT required) - **list_all_promptwatch_prompts** — Get paginated list of prompts with search and filtering options - **get_single_promptwatch_prompt_by_id** — Get a single prompt by ID - **update_a_promptwatch_prompt_by_id** — Update a prompt's type and intent - **delete_a_promptwatch_prompt_by_id** — Soft-delete a prompt by ID - **promptwatch_prompts_bulk_create** — Create multiple prompts in a single request (max 100) - **promptwatch_prompts_bulk_delete** — Soft-delete multiple prompts by IDs - **promptwatch_prompts_bulk_activate** — Activate multiple prompts - **promptwatch_prompts_bulk_deactivate** — Deactivate multiple prompts - **promptwatch_prompts_attach_tag** — Attach tags to a prompt (creates tags if they don't exist) - **promptwatch_prompts_bulk_tags** — Attach tags to multiple prompts (creates tags if they don't exist) - **create_a_promptwatch_prompt** — Create a new prompt with specified text, type, and monitor association - **list_all_promptwatch_query_fanouts** — Get paginated list of prompts with extracted ChatGPT query fanout keywords - **list_all_promptwatch_responses** — Get paginated list of responses with search and filtering options - **get_single_promptwatch_response_by_id** — Get a single response by ID with full citations - **promptwatch_responses_list_competitors** — Get top competitor mentions from LLM responses - **promptwatch_responses_list_mentions_time_series** — Get brand and competitor mentions over time - **promptwatch_responses_list_sentiment_distribution** — Get sentiment distribution of LLM responses - **promptwatch_responses_list_sentiment_time_series** — Get sentiment changes over time for brand mentions - **promptwatch_responses_list_summary** — Get response summary including total responses and brand mentions - **list_all_promptwatch_sentiment_time_series** — Get brand sentiment time series data - **list_all_promptwatch_sitemap_progreses** — Get sitemap crawl progress with counts, percentage, HTTP status breakdown, and crawl health score. - **list_all_promptwatch_tags** — Get all tags for the project with prompt counts - **create_a_promptwatch_tag** — Create one or more tags for the project - **delete_a_promptwatch_tag_by_id** — Delete a tag and remove it from all prompts - **update_a_promptwatch_tag_by_id** — Rename an existing tag - **list_all_promptwatch_visibility_time_series** — Get brand visibility time series data - **list_all_promptwatch_visitors_referrer_stats** — Get referrer comparison stats with period-over-period changes - **list_all_promptwatch_visitors_top_browsers** — Get top browsers by visitor count - **list_all_promptwatch_visitors_top_devices** — Get top devices by visitor count - **list_all_promptwatch_visitors_top_locations** — Get top geographic locations by visitor count - **list_all_promptwatch_visitors_top_pages** — Get top pages by visitor count - **list_all_promptwatch_visitors_top_sources** — Get top referrer sources by visitor count - **list_all_promptwatch_visitors_totals** — Get total visitor counts over time - **list_all_promptwatch_visitors_trends** — Get visitor trends grouped by referrer - **list_all_promptwatch_content_gap_prompts** — List content_gap_prompts in Promptwatch. Returns id, prompt, type, intent, languageCode, createdAt, responseCount, and latestContentGap with score, date, and sitemap details. Date range cannot exceed 60 days. - **list_all_promptwatch_latest_content_coverage** — Get the latest content coverage for a prompt in Promptwatch. Requires prompt_id. Returns fields such as id, contentCoverageScore, explanation, report, sources, queryFanouts, sitemapTotalUrls, sitemapCrawledUrls, createdAt, and recommendations. ## How it works 1. **Link your customer's Promptwatch account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Promptwatch.** The Proxy API is a 1-to-1 mapping of the Promptwatch API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Add a Generative Search Module to an SEO Platform** — Traditional SEO tools need to track how brands appear in ChatGPT, Claude, Gemini, and Perplexity, not just Google. Embedding Promptwatch through Truto lets your platform offer AI visibility, citation ranking, and competitor heatmap data as a native GEO tier. - **Power AI-Aware Content Workflows in a CMS** — Content platforms want writers to publish drafts optimized for LLM citation, not just human readers. Promptwatch's content gap, query fanout, and optimization endpoints turn your CMS into a co-pilot that tells writers what to cover and rewrites drafts for better AI ingestion. - **Monitor AI Sentiment and Hallucinations in Reputation Tools** — PR and brand monitoring SaaS need to track what LLMs say about their customers' brands in real time. With Promptwatch, you can surface sentiment shifts, competitor mentions, and visibility drops across models as first-class signals alongside social and news monitoring. - **Correlate AI Crawler Activity with Web Analytics** — Web analytics and technical SEO platforms can ingest Promptwatch's AI crawler logs to show customers which pages GPTBot, ClaudeBot, and other agents are actually consuming. This closes the loop between bot scraping, citation appearances, and downstream referral traffic. - **Build an Editorial Planning Tool Driven by Real LLM Prompts** — Content strategy platforms can replace guesswork with the actual prompts users are asking AI models. Pulling content gap prompts and coverage scores from Promptwatch lets your tool auto-generate briefs targeted at topics where the customer's brand is currently invisible. ## What you can build - **AI Share of Voice Dashboard** — Visualize brand vs. competitor visibility across LLMs using competitor heatmaps and visibility time series, refreshed on a schedule via Truto. - **One-Click 'Optimize for AI Search' Action** — Trigger Promptwatch's content creation endpoint in OPTIMIZE mode from your editor to rewrite an existing URL for higher LLM citation likelihood. - **Citation Rank Tracker** — Surface domain-level citation rank analysis and top-cited pages per LLM so customers can monitor whether they're gaining or losing source authority over time. - **Content Gap Brief Generator** — Pull content gap prompts with low coverage scores along with their query fanouts to auto-generate editorial briefs targeting unanswered LLM queries. - **AI Crawler Traffic Reports** — Ingest crawler events, trends, and top crawled pages to show customers which AI bots are hitting their site, how often, and on which URLs. - **Real-Time Sentiment Alerting** — Poll sentiment distribution and sentiment time series endpoints to fire alerts when LLM sentiment toward a tracked brand shifts negatively. ## FAQs ### How do end users authenticate their Promptwatch account? Truto handles the Promptwatch connection flow for your users, including credential validation via the auth validate endpoint. You don't need to build or store auth logic yourself — your users connect once and Truto manages the token lifecycle. ### What entities can I read and write through this integration? You can read brands, projects, prompts, personas, monitors, responses, citations, crawler events, visibility and sentiment time series, competitor heatmaps, content gap data, and visitor analytics. You can create and update brands, projects, prompts (including bulk create/delete/activate/tag operations), personas, monitors, tags, and content generation/optimization jobs. ### How fresh is the data I get from Promptwatch? Data freshness depends on Promptwatch's own monitor schedule for LLM querying and crawler log ingestion. Truto pulls on demand or on a polling cadence you configure, so the data your product surfaces is as current as the most recent Promptwatch run for that brand or monitor. ### Is content generation synchronous or asynchronous? The create content endpoint is asynchronous — it kicks off a CREATE or OPTIMIZE job. Your integration should submit the job, then poll the content endpoint by ID to retrieve the finished output once Promptwatch has completed processing. ### Can I manage prompts in bulk? Yes. Promptwatch supports bulk create, bulk delete, bulk activate/deactivate, and bulk tag operations on prompts, which is useful when onboarding a new customer's full prompt set or syncing large editorial calendars into monitors. ### Does Truto normalize Promptwatch data into a unified schema? There is no unified API for this category yet, so Promptwatch is exposed as a native integration with its own resource shapes. You get full access to Promptwatch-specific fields like citation rank, query fanouts, and content coverage scores without lossy normalization.