project_id. Always call get_all_projects first to get your project ID. Most tools are read-only. The Management Tools section covers prompt, topic, tag and competitor changes; any other tool that creates, updates, or deletes data is marked Write operation.
Common Parameters
Most tools share these optional parameters:Data Fetching Tools
These tools return lists of individual records.get_all_projects
List all projects accessible to the authenticated user. Call this first — every other tool requires theproject_id returned here.
get_all_prompts
Fetch all tracked search queries (prompts) with visibility scores, mention counts, and performance indicators. Use this to discover which queries are being monitored.get_all_topics
Fetch topic categories that group related prompts. Use topic IDs for filtering in other tools.get_all_tags
Fetch custom tag labels applied to prompts. Use tag IDs for filtering in other tools.get_all_citations
Fetch individual citation URLs where the brand was referenced in AI responses. For aggregated counts, usequery_citation_report instead.
get_all_websites
Fetch all tracked websites (your brand + competitors). Use this for competitive benchmarking and to get website IDs for filtering.get_all_keywords
Fetch keywords found in AI responses related to the brand. Useful for content strategy and understanding brand perception.get_all_models
Fetch all tracked AI platforms (ChatGPT, Perplexity, Claude, Gemini, etc.) with per-platform metrics.get_all_markets
Fetch all geographic markets being tracked. Use market IDs for filtering in report queries.get_all_domains
Fetch citing domains aggregated by domain. Unlikeget_all_citations which returns individual URLs, this provides a higher-level view.
get_filter_values
List the values a project actually has for each filter (topic, tag, market, platform and website IDs, prompts, cited domains, and more) and which tools and report dimensions accept each one. Use it to get exact IDs before filtering a report.get_geo_onboarding_status
Full setup status for a project: whether the site is active and tracked, onboarding progress and prompt counts per market, plan access and limits, and whether an analysis run is in progress.Report Query Tools
These tools return aggregated metrics grouped by dimensions you specify.Common Report Parameters
query_performance_report
Aggregated performance metrics: share of voice, citation share, visibility score, and mention counts. This is the main analytics tool for understanding brand performance. Example dimension combinations:["date"]withmonthinterval — monthly visibility trend["model"]withwebsite_type: "SELF"— per-platform brand performance["topic", "date"]— topic performance over time["website", "market"]— compare brand vs competitors by region
query_citation_report
Aggregated citation metrics: citation counts, unique pages, and unique domains grouped by dimensions. Example dimension combinations:["model"]withwebsite_type: "SELF"— citations by AI platform["date"]withmonthinterval — citation trend over time["model", "domain"]— top citing domains per AI model
query_sentiment_report
Sentiment analysis metrics: keyword occurrences and positive sentiment scores.get_sentiment_report
Sentiment of your brand’s keyword mentions in AI answers: positive and negative subtheme counts, a sentiment score and its change, optionally grouped by one attribute (for example topic, platform, or week).get_trends_report
Time series of one metric (visibility_score, share_of_voice, citation_share, citing_answers, citation_count, mention_count, rank, or number_of_answers), as one line per tracked website or per AI platform. Set series_by and interval (day, week, or month). Requires metric.
Example dimension combinations:
["model"]withwebsite_type: "SELF"— sentiment by AI platform["date"]withmonthinterval — sentiment trend["topic"]— sentiment breakdown by topic
Project Overview Tools
High-level dashboards and trends for a whole project.get_kpi_summary
KPI summary card for a project — total visibility, mention count, citations, and sentiment breakdown, plus deltas vs. the previous period. Use this as a single-call dashboard view.get_project_visibility_trends
Project-wide visibility trends over time, aggregated across all tracked prompts. Requiresgraph_type (visibility or citation_share); supports aggregate_level (daily, weekly, monthly).
get_sentiment_overview
Headline brand sentiment, with the same numbers as the Writesonic sentiment dashboard: positive vs negative sentiment counts, the overallsentiment_score, and its period-over-period change. For breakdowns by topic, platform, or date, use query_sentiment_report.
Prompt Analytics Tools
Leaderboards, rankings, and deep-dive analytics for individual tracked prompts.get_all_prompts_with_metrics
Flat list of every tracked prompt with rolled-up metrics — visibility, mention count, citations, last-run date.get_prompts_leaderboard
Ranked leaderboard of tracked prompts, by visibility score by default. Returns prompt text, visibility score, mention count, and search volume.get_prompts_not_mentioning_you
High-volume tracked prompts where your brand is not appearing in AI answers — the gaps to close. Includes the competitors who do appear.get_top_prompts_by_volume
Highest-search-volume tracked prompts in a project. Use this to prioritize the prompts real users ask most.get_top_prompts_driving_visibility
Prompts where your brand appears most often in AI answers — the prompts contributing most to your overall AI visibility.get_prompt_info
Static metadata for a single tracked prompt: text, topic, tags, intent, monthly search volume, branded flag, markets, and platforms. Theprompts filter must resolve to exactly one prompt.
get_prompt_answers
The AI-generated answers for a single tracked prompt, grouped and ranked across runs, with platform, mentioned brands, and citations.get_prompt_citations
Pages that AI platforms cite when answering a single tracked prompt — the source URLs the AI grounded its answer in.get_prompt_snippets
Short text excerpts from AI answers for a prompt, focused on the surrounding context where brand mentions occur, with sentiment polarity.get_prompt_trends
Time-series of visibility and mention metrics for one or more tracked prompts. Supportsaggregate_level (daily, weekly, monthly) and event overlays.
get_prompt_sentiment_trends
Time-series of sentiment polarity (positive / neutral / negative) for AI mentions of brands inside a single tracked prompt.get_prompt_search_queries
Related search queries surfaced for a tracked prompt — the broader query fan-out the AI considered when generating its answer.get_prompt_result_details
Full detail snapshot of a single AI-platform run for one prompt: the raw response text, extracted citations, brand mentions, and run metadata.get_prompt_result_compare
Compare a single prompt result against its baseline (typically the prior run), with citation deltas and mention diffs.get_prompt_results_compare
Diff two specific AI response runs for the same prompt bycurrent_result_id and previous_result_id — side-by-side text, citation, and mention changes.
AI Answer Tools
Browse and analyze the raw AI answers collected across your project.get_all_ai_answers
All AI answers across every tracked prompt that mention your brand or competitors. Useful for bulk export or browsing every mention.get_ai_answer_counts
Aggregate counts of AI answers across the project — total mentions with per-platform and per-mention-type breakdowns.get_ai_answer_changes
Period-over-period change report: which AI answers appeared or disappeared between two date ranges. Use to detect emerging mentions or sudden loss of visibility. Requires aperiod_filter date-range comparison.
Citation Analytics Tools
Citation analytics scoped to your whole domain or to a single page. Webpage-scoped tools require acited_page_url filter.
get_domain_citation_trends
Time-series of how often AI platforms cite your domain across all tracked prompts. Supportsaggregate_level (daily, weekly, monthly).
get_domain_citation_platforms
Which AI platforms cite your domain most, with citation counts and share per platform.get_domain_citation_prompts
Which tracked prompts produce the most AI citations to your domain.get_domain_citation_topics
Topic categories where your domain gets cited most — which themes drive your AI visibility.get_domain_citation_answers
Sample AI answers that cite your domain, for spot-checking the context AI presents alongside your citations.get_domain_pages_cited
Your domain’s most-cited pages, ranked by how often AI platforms cite each page.get_domain_subdomains
Break a cited domain down by subdomain (for exampledocs., help., app.), with each subdomain’s citation share, citing answers, and unique pages cited. www. is folded into the root domain. Requires domain.
get_industry_cited_pages
Pages AI platforms cite in your industry — including competitors and third-party domains. Shows the overall citation landscape, not just your own pages.get_webpage_citation_trends
Time-series of how often AI platforms cite a single specific page. Supportsaggregate_level (daily, weekly, monthly).
get_webpage_citation_platforms
Which AI platforms cite a specific page most often.get_webpage_citation_prompts
Which tracked prompts drive AI citations to a specific page.get_webpage_citation_topics
Topic categories driving AI citations to a specific page.get_webpage_citation_answers
Sample AI answers that cite a specific page.get_webpage_negative_sentiments
AI answers where negative sentiment about your brand was sourced from one cited page, latest first, with the negative sentences highlighted, the prompt, and the platform. Requires acitation_id filter.
get_citation_decay
How your citation share has held up over the last 14 days, by AI platform (default) or by topic: peak share, half-life, days to peak, and a 14-point share trend. Use it to see where citations are fading.Action Center Tools
Actionable recommendations: gaps to close, content to create, pages to fix.get_actionables_dashboard
One-call summary of all actionable recommendations — broken pages, brand gaps, new-content opportunities, and content-optimization suggestions, with counts and estimated impact per category.get_brand_gap_summary
Summary of brand-gap opportunities — AI answers where your competitors are mentioned but you are not, grouped by the third-party site where the mention originated.get_all_brand_gap_opportunities
Paginated list of brand-gap opportunities. Each entry is a third-party page cited by AI where competitors appear but you don’t — a place where outreach or content placement could win the citation.get_brand_gap_impact
Estimated visibility impact if you claim each third-party brand-gap mention — what closing the gap is worth.get_brand_gap_responses
Sample AI responses that cite third-party sites in your brand-gap set, so you can see exactly what AI says alongside the competitor citation.get_brand_gap_existing_mentions
AI answers that mention your brand via a third-party site citation — wins to reinforce rather than gaps to close.get_all_new_content_opportunities
Topics and queries where you should create new content to capture AI visibility — areas where AI is answering but you have no page to be cited.get_new_content_impact
Estimated visibility gains if each new-content opportunity is published. Use to prioritize which content brief to ship first.get_new_content_sample_answers
Sample AI answers from queries that a specific new-content opportunity would address. Requirescontent_id.
get_all_optimization_opportunities
Existing pages on your domain that need optimization — pages AI cites where fixing structural issues would likely lift citation rate or sentiment.get_optimization_fixes
Concrete AI-suggested fixes for the issues detected on an optimization page — rewrites, structural changes, and missing-section recommendations. Requireseditor_history_id.
get_optimization_page_answers
Sample AI answers that cite a specific page flagged for optimization. Requiresoptimization_page_id.
get_all_broken_pages
Broken pages on your domain that AI platforms are citing — pages returning 4xx/5xx or unreachable. Highest-priority fixes, since AI is sending visitors to dead URLs.get_broken_pages_impact
Before/after metrics for broken-page fixes — the citation and visibility lift from pages already marked resolved.Prompt Explorer Tools
Investigate prompts that aren’t yet tracked in your project.get_prompt_explorer_overview
Investigate a single prompt: returns the AI platform’s response text, the prompt’s monthly search-volume estimate, and related prompts. Requiresprompt; optional platforms (default ["chatgpt"]; supports perplexity, google_ai_overview, gemini, copilot). Consumes one Prompt Explorer credit per investigation.
get_prompt_explorer_search_history
List previously-investigated prompts with pagination. Pass an entry’shistory_id to get_prompt_explorer_overview to re-fetch prior results without spending a new credit.
Portfolio Tools
Portfolios group tracked pages (URLs) for cross-page analytics.get_all_portfolios
List every portfolio configured for the project. Use this to discoverportfolio_id values needed by the other portfolio tools.
get_portfolio_info
Get the metadata for a single portfolio (id, name, site id). Requiresportfolio_id.
get_portfolio_overview
Performance metrics for portfolios: citation share, citing answers, citations mentioning your brand, visibility contribution, and totals with period-over-period change. Passportfolio_id to scope to one portfolio.
track_pages
Start tracking page URLs for the project, and optionally attach them to a new or existing portfolio in the same call. Accepts raw URLs, so pages don’t need to be tracked first. Write operation.create_portfolio
Create a new portfolio. Requiresportfolio_name. Write operation.
edit_portfolio
Edit a portfolio’s properties — rename plus add/remove pages in one call. Requiresportfolio_id. Write operation.
rename_portfolio
Rename an existing portfolio. Requiresportfolio_id and portfolio_name. Write operation.
add_pages_to_portfolio
Add one or more tracked pages (URLs) to an existing portfolio, with per-URL add status. Write operation.remove_pages_from_portfolio
Detach one or more tracked pages from a portfolio. The pages remain tracked at the site level. Write operation.delete_portfolio
Delete an entire portfolio. Optionally also stop tracking its pages viashould_stop_tracking (default false). Write operation.
Brand Radar Tools
Brand Radar reports run asynchronous competitor scans across your configured prompts and target domains.list_brand_radar_reports
List the Brand Radar reports for a project. Use this to discoverreport_id values for the other Brand Radar tools.
get_brand_radar_report_filters
The filter values available for a specific Brand Radar report — the citing domains, citing pages, and queries that appear in the report’s data. Requiresreport_id.
create_brand_radar_report
Kick off a new Brand Radar report run. Reports run asynchronously — poll the read tools to track status. Write operation.delete_brand_radar_report
Soft-delete a single Brand Radar report byreport_id. Write operation.
bulk_delete_brand_radar_reports
Soft-delete multiple Brand Radar reports in a single call viareport_ids. Write operation.
Shopping & Ads Tools
How your products and brand appear in AI shopping cards, and which sponsored placements show up in AI answers. These match the Shopping and Ads screens in the dashboard.get_shopping_report
Shopping metrics grouped by one or more dimensions (topic, tag, market, model, query, date, website, branded, product, placement_type, merchant): shopping visibility, direct-link share, product rank, and per-product or per-merchant breakdowns. query_performance_report cannot produce these.
get_shopping_share_of_voice
Your brand’s share of voice and shopping visibility in AI shopping cards, alongside competitors.get_shopping_leaderboard
Brand vs competitor leaderboard for shopping-card visibility.get_shopping_rank
Your brand’s average rank in AI shopping cards (lower is better), as shown on the Shopping screen.get_shopping_mode_rate
The share of AI answers for your prompts that show shopping results (trigger shopping mode). Higher is better.get_shopping_mode_trends
How often shopping mode is triggered over time, broken down by AI platform.get_shopping_visibility_trends
Time series of shopping visibility or direct-purchase-link share. Requiresgraph_type (shopping-visibility or direct-purchase-link); optional aggregate_level (daily, weekly, monthly).
get_shopping_performance_breakdown
Shopping visibility, direct purchase-link share, and average shopping rank, broken down by topic or prompt viadimension.
get_shopping_performance_by_topics
Shopping visibility broken down by topic. Deprecated: useget_shopping_performance_breakdown.
get_shopping_top_products
Products surfaced in AI shopping cards, ranked bymetric (shopping_visibility, direct_purchase_link, or shopping_rank). brand_scope picks all, your own, or competitor products; view picks top, bottom, rising, or falling.
get_shopping_product_coverage
How much of your product catalog appears in AI shopping cards: surfaced with your own buy link, surfaced with competitor or retailer links only, or not surfaced.get_ads_report
Sponsored-placement metrics grouped by one or more dimensions, includingadvertiser: ad visibility, share of ad placements, and advertiser breakdowns. Only covers AI platforms that serve ads (ChatGPT and Google AI Overviews).
AI Analytics Tools
AI crawler and human traffic on your website. These tools take ananalytics_id (from get_ai_analytics_sites) instead of only a project_id.
get_ai_analytics_sites
List the AI traffic tracking sites set up for the project, with each site’sanalytics_id. Call this first for the other AI Analytics tools.
get_ai_analytics_status
Check whether AI traffic tracking is set up and receiving data for a site (Active or Awaiting_Setup), and whether traffic or broken-page data exists yet.
get_ai_analytics_bots_list
List the distinct AI bots and crawlers (ChatGPT, Perplexity, Claude, Googlebot, and more) that have visited the site. Passperiod=all for all time.
get_ai_analytics_trends_summary
Traffic totals for a period: AI bot visits, human visits, and the number of non-accessible (broken) pages.get_ai_analytics_trends_chart
Daily (or hourly, viaunit) AI bot and human visits, broken down by platform, plus non-accessible page hits.
Brand Facts Tools
Brand facts are the statements AI answers are fact-checked against.get_facts
List the project’s brand facts, split intoapproved and suggested. Suggested facts are AI-generated and need review before they count.
add_facts
Add one or more brand facts. Facts you add are approved immediately. Requiresfacts. Write operation.
update_fact_status
Approve (APPROVED) or reject (DISCARDED) facts by id, usually the suggested facts from get_facts. Requires fact_ids and status. Write operation.
Content Tools
Write long-form articles with Writesonic’s article writer. Writing runs in the background, so start it and check back for the result.article_writer
Start writing a new long-form article on a topic: it researches the topic, picks keywords, and produces a title, outline, and full article. Returns ajob_id right away; writing takes several minutes. AI images are off unless requested. Requires topic. Write operation.
article_writer_result
Check on an article started witharticle_writer. Pass its job_id; while the status is generating, check again in a few minutes. When completed, the article is in final_article.
Management Tools
These tools create, update, or delete project configuration. Use with care.create_prompt
Add a new prompt (tracked AI query) to the project. Requiresname, market_id, and topic_id. The prompt runs daily across the configured AI platforms.
update_prompt
Edit a tracked prompt — change its text, topic, market, tags, or intent. Requiresquery_id. Omitted fields are left unchanged.
bulk_delete_prompts
Delete one or more prompts from the project in a single call viaprompt_ids.
bulk_move_prompts
Move many prompts to a different topic in one call. Requiresprompt_ids and target_topic_id.
bulk_set_prompt_status
Pause or reactivate many prompts in one call. Requiresprompt_ids and status (ACTIVE or INACTIVE).
bulk_tag_prompts
Add and/or remove tags on many prompts in one call. Requiresquery_ids and at least one of add_tag_ids or remove_tag_ids.
bulk_set_prompt_target
Assign one existing target (a persona, intent stage, or locality) to many prompts in one call. Requiresprompt_ids and target.
create_topic
Create a new topic. Topics are categories used to group prompts for slicing reports. Requiresname.
update_topic
Rename an existing topic. Requirestopic_id and name.
delete_topic
Delete a topic from the project. Optionally scope the deletion to a single market viamarket_id.
create_tag
Create a new tag. Tags are user-defined labels used to group prompts and competitors. Requiresname.
update_tag
Rename a tag, change its color, or both. Requirestag_id plus at least one of new_name or color.
delete_tag
Delete a tag and all its prompt and competitor associations. Requirestag_id.
add_competitors
Add one or more competitor websites to the project so they appear in side-by-side reports. Requirescompetitor_market_pairs.
bulk_remove_competitors
Remove one or more tracked competitor websites from the project in a single call. Requirescompetitor_market_pairs.
convert_pitch_to_standard
Convert a pitch project to a standard project, keeping only the topics and markets you choose. Validates plan limits and adjusts credits. Requirestopic_ids and market_ids.
Planner Tools
Meta tools that help orchestrate multi-step queries.tools_info
Returns a step-by-step execution plan for a natural-language question — the recommended tool sequence with dimensions, measures, and filters pre-filled. Use this before making tool calls when the right tool isn’t obvious or the question needs multiple tools. Requiresquestion.
execute_plan
Run a multi-step plan as one TypeScript program server-side instead of round-tripping on every intermediate result. Providestool(name, args) and output(value) in an async sandbox with a 30-second timeout. Use only when a plan needs 3+ chained tool calls with loops, joins, or aggregation — for 1–2 calls, call tools directly. Requires code. Write operation when the plan calls a write tool.