Skip to main content
Most tools require a 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 the project_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, use query_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. Unlike get_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"] with month interval — monthly visibility trend
  • ["model"] with website_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"] with website_type: "SELF" — citations by AI platform
  • ["date"] with month interval — 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). 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"] with website_type: "SELF" — sentiment by AI platform
  • ["date"] with month interval — 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. Project-wide visibility trends over time, aggregated across all tracked prompts. Requires graph_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 overall sentiment_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. The prompts 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. Time-series of visibility and mention metrics for one or more tracked prompts. Supports aggregate_level (daily, weekly, monthly) and event overlays. 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 by current_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 a period_filter date-range comparison.

Citation Analytics Tools

Citation analytics scoped to your whole domain or to a single page. Webpage-scoped tools require a cited_page_url filter. Time-series of how often AI platforms cite your domain across all tracked prompts. Supports aggregate_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 example docs., 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. Time-series of how often AI platforms cite a single specific page. Supports aggregate_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 a citation_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. Requires content_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. Requires editor_history_id.

get_optimization_page_answers

Sample AI answers that cite a specific page flagged for optimization. Requires optimization_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. Requires prompt; 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’s history_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 discover portfolio_id values needed by the other portfolio tools.

get_portfolio_info

Get the metadata for a single portfolio (id, name, site id). Requires portfolio_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. Pass portfolio_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. Requires portfolio_name. Write operation.

edit_portfolio

Edit a portfolio’s properties — rename plus add/remove pages in one call. Requires portfolio_id. Write operation.

rename_portfolio

Rename an existing portfolio. Requires portfolio_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 via should_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 discover report_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. Requires report_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 by report_id. Write operation.

bulk_delete_brand_radar_reports

Soft-delete multiple Brand Radar reports in a single call via report_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. How often shopping mode is triggered over time, broken down by AI platform. Time series of shopping visibility or direct-purchase-link share. Requires graph_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 via dimension.

get_shopping_performance_by_topics

Shopping visibility broken down by topic. Deprecated: use get_shopping_performance_breakdown.

get_shopping_top_products

Products surfaced in AI shopping cards, ranked by metric (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, including advertiser: 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 an analytics_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’s analytics_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. Pass period=all for all time. Traffic totals for a period: AI bot visits, human visits, and the number of non-accessible (broken) pages. Daily (or hourly, via unit) 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 into approved 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. Requires facts. 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 a job_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 with article_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. Requires name, 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. Requires query_id. Omitted fields are left unchanged.

bulk_delete_prompts

Delete one or more prompts from the project in a single call via prompt_ids.

bulk_move_prompts

Move many prompts to a different topic in one call. Requires prompt_ids and target_topic_id.

bulk_set_prompt_status

Pause or reactivate many prompts in one call. Requires prompt_ids and status (ACTIVE or INACTIVE).

bulk_tag_prompts

Add and/or remove tags on many prompts in one call. Requires query_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. Requires prompt_ids and target.

create_topic

Create a new topic. Topics are categories used to group prompts for slicing reports. Requires name.

update_topic

Rename an existing topic. Requires topic_id and name.

delete_topic

Delete a topic from the project. Optionally scope the deletion to a single market via market_id.

create_tag

Create a new tag. Tags are user-defined labels used to group prompts and competitors. Requires name.

update_tag

Rename a tag, change its color, or both. Requires tag_id plus at least one of new_name or color.

delete_tag

Delete a tag and all its prompt and competitor associations. Requires tag_id.

add_competitors

Add one or more competitor websites to the project so they appear in side-by-side reports. Requires competitor_market_pairs.

bulk_remove_competitors

Remove one or more tracked competitor websites from the project in a single call. Requires competitor_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. Requires topic_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. Requires question.

execute_plan

Run a multi-step plan as one TypeScript program server-side instead of round-tripping on every intermediate result. Provides tool(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.