add_competitors
ChatGPTAdd one or more competitor websites to the project so they appear in side-by-side reports. Example: "Track openai.com and anthropic.com as competitors in my project." Required: project_id (path), request body containing the competitor website ids to promote from suggestions or to create new (CompetitorsAddIdPairsInput). Response: CompetitorsAddStatsOutput summarising how many competitors were added vs. skipped (e.g. already tracked).
add_facts
ChatGPTAdd one or more brand facts manually. Manually-added facts are inserted as already APPROVED (source MANUAL) — no separate approval step is needed. Example: "Add the fact that our free plan includes 5 users." Required: project_id (path), request body with facts (list of non-empty strings). Response: FactsMutationResponse — updated_facts count and the resulting facts (FactSummary list).
add_pages_to_portfolio
ChatGPTAdd pages that are already tracked to one or more existing portfolios. Example: "Add these 5 tracked pricing pages to my 'Competitor Pages' portfolio." Required: project_id. Also pass portfolio_ids (from get_all_portfolios) and pages (page ids, not URLs). Optional: page_type: tracked_page (default; pages holds tracked-page ids) or citation (pages holds citation ids from get_all_citations). To add a URL that isn't tracked yet, use track_pages. Response: the status of each page: added, already present, or failed.
article_writer
ChatGPTWrite a new long-form article on a topic with Writesonic's article writer: it researches the topic, picks keywords, and produces a title, outline and full article with headings. It only creates new articles; it cannot edit an existing one. Example: "Write an article about machine learning applications in healthcare" Starts the article and returns immediately with a job_id. Writing takes several minutes, so do not wait on this call and do not call it again for the same article. Call article_writer_result with the job_id after 5 minutes, and keep calling it every 5 minutes until the status is completed. Required: topic. Everything else is optional, including article_intent (e.g. "Listicles", "How-To Guides", "Comparison Blogs"), which is auto-detected from the topic/title; only pass it if the user asked for a specific article type. - Only call this when the user asked for an article to be written. - If passing outlines, also pass a title. - Use the language of the conversation for language. Response: a job_id to poll with.
article_writer_result
ChatGPTCheck whether an article started with article_writer is ready. Pass the job_id returned by article_writer. While the status is generating, wait 5 minutes and call this tool again. When the status is completed the full article body is in final_article. A failed status puts the reason in message. Response: the job status and, once finished, the generated article.
bulk_delete_brand_radar_reports
ChatGPTSoft-delete multiple Brand Radar reports in a single call. Example: "Delete reports A, B, and C in one batch." Required: project_id (path), request body BrandRadarBulkDeleteRequest with report_ids: list[UUID]. Response: BrandRadarBulkDeleteResponse with the number of reports actually deleted (excludes ids that didn't exist or weren't owned).
bulk_delete_prompts
ChatGPTDelete one or more prompts from the project in a single call. Example: "Stop tracking prompts X, Y, and Z." Required: project_id (path), request body BulkPromptDeleteInput with query_ids: list[UUID] identifying the prompts to remove. Response: the updated full prompts list (AllPromptOutput) for the project.
bulk_move_prompts
ChatGPTMove many prompts to a different topic in ONE call, instead of editing each prompt. Example: "Move these 25 prompts under the 'Competitor Comparison' topic." Required: project_id (path), body with prompt_ids and target_topic_id (get topic IDs from get_all_topics). Response: counts of prompts moved (BulkPromptMoveResponse).
bulk_remove_competitors
ChatGPTStop tracking one or more competitors in specific markets, in a single call. Example: "Stop tracking competitors A and B in the United States market." Required: project_id, competitor_market_pairs: a list of {competitor_id, market_id} objects. Each pair removes that competitor from that one market. Get competitor ids from get_all_websites and market ids from get_all_markets. Response: the project's updated list of tracked competitors.
bulk_set_prompt_status
ChatGPTPause or activate many prompts in ONE call, instead of editing each prompt. Example: "Pause these 30 prompts" / "Reactivate all the prompts I just moved." Required: project_id (path), body with prompt_ids and status (ACTIVE or INACTIVE). Response: counts only — updated_count, unchanged_count, target_status.
bulk_set_prompt_target
ChatGPTAssign one existing target (a persona, intent stage or locality) to many prompts in one call. Example: "Assign the 'Enterprise Buyer' persona to these 20 prompts." Required: project_id, prompt_ids (prompt ids from get_all_prompts), and target: {prompt_target_id}, the id of an existing target. Response: updated_count, the number of prompts changed.
bulk_tag_prompts
ChatGPTAdd and/or remove tags on many prompts in ONE call, instead of editing each prompt one at a time. Example: "Tag these 40 prompts as 'high-priority' and drop the 'archive' tag from them." Required: project_id (path), plus a body with query_ids (the prompts to modify) and at least one of add_tag_ids / remove_tag_ids. Prompt or tag IDs that don't belong to this project are ignored. Create tags first with create_tag to get their IDs. Response: counts only — prompts_updated, tags_added, tags_removed.
convert_pitch_to_standard
ChatGPTConvert a PITCH project to a STANDARD project. Validates plan limits, removes unwanted topics and markets, adjusts credits, and changes the project type. Example: "Convert my pitch project to standard, keeping only the selected topics and markets." Required: project_id (path), request body with topic_ids (list of topic UUIDs to keep) and market_ids (list of source market UUIDs to keep — derived markets are auto-included). Response: the updated project with folders (ProjectWithFolders).
create_brand_radar_report
ChatGPTStart a Brand Radar report: a scan of how a brand and its competitors show up in AI answers. It runs in the background; check its status with list_brand_radar_reports. Example: "Run a Brand Radar report on our brand against our top competitors." Required: project_id, plus brand_id unless the report is driven only by topic_tag_id or search_text. Optional: - brand_url: analyze a brand that has no brand_id. - competitor_ids: competitor brand ids. - auto_add_competitors (default true): pick competitors automatically when none are given and brand_id is set. - topic_tag_id or search_text to focus the report (one or the other, not both). Response: the new report's id and initial status.
create_portfolio
ChatGPTCreate a portfolio: a named group of the project's tracked pages, used for page analytics in the Research Page Tracker. Example: "Create a portfolio called 'Top Competitor Blogs' with these tracked pages." Required: project_id, portfolio_name. Optional: tracked_pages: ids of pages already tracked for this project, not URLs (track new URLs with track_pages first). Or should_add_all_pages=true to add every tracked page, in which case tracked_pages is ignored. Response: the new portfolio's id.
create_prompt
ChatGPTAdd a new prompt (tracked AI query) to the project. The prompt runs daily across the configured AI platforms and produces answers + citations + sentiment. Note: on success the prompt is created with status QUEUED and starts running on the next daily cycle. It will NOT appear in get_all_prompts (which lists prompts that have already run) until after its first run — a successful response here means it was saved, even though it isn't immediately listable. Example: "Track the prompt 'best CRM for startups' under the 'CRM Tools' topic in my 'US' market." Required: project_id (path), request body containing the prompt text and metadata (topic, market, tags, intent — per PromptInputV2). Response: the created prompt used in other tools and reports.
create_tag
ChatGPTCreate a new tag in the project. Tags are user-defined labels used to group prompts and competitors for slicing reports. Example: "Create a tag called 'high-priority' coloured red." Required: project_id (path), request body with name and color. Response: the newly-created tag (GeoPresenceTagsOutput) including the generated id for use as a filter in other tools.
create_topic
ChatGPTCreate a new topic in the project. Topics are categories used to group prompts for slicing reports. Example: "Add a topic called 'AI Coding Tools' so I can group my coding-related prompts under it." Required: project_id (path), request body with topic (the topic name). Response: the updated full topic list (AllTopicOutput) for the project, including the newly-created topic's id.
delete_brand_radar_report
ChatGPTSoft-delete a single Brand Radar report by id. The underlying data is preserved for audit but the report no longer surfaces in lists or analytics. Example: "Remove the obsolete brand-monitor report I created last week." Required: project_id (path), report_id (path). Response: 204 No Content on success.
delete_portfolio
ChatGPTDelete a portfolio. Example: "Delete my 'Old Campaign' portfolio and stop tracking those pages." Required: project_id, portfolio_id (from get_all_portfolios). Optional: should_stop_tracking (default false): also stop tracking the pages that were in it; otherwise they stay tracked. Response: confirmation of the deletion.
delete_tag
ChatGPTDelete a tag and all its prompt and competitor associations. Example: "Remove the 'legacy' tag I no longer track." Required: project_id (path), tag_id (path). Response: 204 No Content on success. The tag is permanently removed along with every prompt-tag and competitor-tag link that referenced it.
delete_topic
ChatGPTDelete a topic from the project. Optionally scope the deletion to a single market via the market_id query parameter. Example: "Remove the 'Legacy Tools' topic from project." Required: project_id (path), topic_id (path). Optional: market_id (query) — when provided, removes the topic only from that market instead of the whole project. Response: the updated full topic list (AllTopicOutput).
edit_portfolio
ChatGPTChange a portfolio in one call: rename it and/or add and remove tracked pages. Example: "Rename my 'Q1 Pages' portfolio to 'Q1 2026' and add these 5 tracked pages." Required: project_id, portfolio_id (from get_all_portfolios). Optional: - portfolio_name: the new name. - pages_to_add / pages_to_remove: tracked-page ids, not URLs (track new URLs with track_pages first). - should_add_all_pages / should_remove_all_pages: add or remove every tracked page instead of listing ids. Response: the updated portfolio.
get_actionables_dashboard
ChatGPTOne-call summary of all actionable recommendations for a project — broken pages, third-party-site brand gaps, new-content opportunities, and content-optimization suggestions, with counts and estimated impact per category. Example: "What should I work on this week? Give me the Action Center summary for my project." Required: project_id (path). Optional: standard common filters. Response: ActionablesDashboardResponse with per-category counts, estimated impact metrics, and pointers to the underlying detail endpoints (broken-pages/items-to-address, third-party-sites-items-to-address, new-content-actionables, optimize-content-actionables).
get_ads_report
ChatGPTSponsored-placement metrics grouped by one or more dimensions. This is the report behind the UI Ads screen — use it for ad visibility, share of ad placements and advertiser breakdowns. Only answers from AI models that serve ads (ChatGPT and Google AI Overviews) are in scope; filtering to any other platform correctly returns no rows. Example: "Which advertisers bid against my brand, by topic?" Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, advertiser - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type; advertiser rows carry advertiser_url, advertiser_logo, advertiser_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the advertised brand, and auto-sets website_type to SELF+COMPETITORS; product / advertiser auto-set it to ALL, like the dashboard's Advertisers page (default otherwise is SELF) - product is the ad creative — a product card (AD_SHOPPING) or a text ad (AD_TEXT) Measures (omit for all): ad_visibility, share_of_ad_placements, ad_placements, ad_answers, placements_with_self_brand, unique_advertisers, unique_ad_creatives, ad_rank, avg_quoted_price - ad_visibility = ad_placements / ad_answers, where ad_answers counts answers in the group holding at least one ad from any advertiser — matching the Ads dashboard - share_of_ad_placements = this advertiser's placements / all tracked advertisers' placements, the definition behind the Ads dashboard KPI card. The dashboard's Advertisers table labels ad_placements / ad_answers as "share of ad placements"; that column is ad_visibility here - ad_placements counts distinct answers in which the entity's ad appeared, not individual placements - avg_quoted_price also returns avg_quoted_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, advertisers, placement_type, source_type, price, product_rank. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, advertiser_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_ values. Pagination: Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting. Response: Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters). Notes:* Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts once (rank and price are not…
get_ai_analytics_bots_list
ChatGPTList the distinct AI bots/crawlers that have visited this site (ChatGPT, Perplexity, Claude, Googlebot, etc.). The number of bots/crawlers tracked is len(bots) in the response — there is no separate count field. Example: "How many AI bots/crawlers are tracked on my site?" Required: analytics_id (from get_ai_analytics_sites). Pass period=all to cover all-time instead of specifying from/to — that's almost always what "how many bots are tracked" means. Response: BotsListResponse — bots (list of bot names).
get_ai_analytics_sites
ChatGPTList the AI-crawler-tracking sites set up for this project, with each site's id — the analytics_id required by get_ai_analytics_status and every other AI Analytics tool. Example: "Which sites do we have AI analytics tracking set up for on this project, and what are their analytics ids?" Required: project_id (query param). Response: AIAnalyticsInfoList — sites (each with id (=analytics_id), domain, status, provider), audit_site.
get_ai_analytics_status
ChatGPTCheck whether AI-crawler visit tracking (AI Analytics) is set up and actively ingesting data for this site — is the integration Active or still Awaiting_Setup, and is any traffic/broken-pages data available yet. Example: "Is AI analytics tracking live for this site, and do we have any data yet?" Required: analytics_id (query param, identifies the tracked site). Response: AnalyticsStatusResponse — status (Active/Awaiting_Setup), domain, provider, has_data, has_broken_pages_data.
get_ai_analytics_trends_chart
ChatGPTDay-by-day (or hour-by-hour, via unit) visit counts for a tracked site — AI bot visits and human visits, each broken down by platform (ChatGPT, Perplexity, Googlebot, etc.), plus non-accessible page hits over the same time buckets. This is the "visitors per day" tool; sum a day's platforms[]. visits for that day's total. Example: "How many visitors did my site get per day over the last 30 days?" Required: analytics_id (from get_ai_analytics_sites). unit defaults to day; pass unit=hour for an hourly breakdown instead. Response: OverviewTrendsChartResponse — date_range, ai_data and human_data (each a list of {date, platforms: [{name, visits}]}), non_accessible_pages_data.
get_ai_analytics_trends_summary
ChatGPTBasic traffic totals for a tracked site over a period: total AI bot visits, total human visits, and non-accessible (broken) page count. One aggregate number per metric for the whole period, not a day-by-day breakdown — use get_ai_analytics_trends_chart for visits per day. Example: "How many visitors has my site had this month, AI bots vs humans?" Required: analytics_id (from get_ai_analytics_sites). Pass period=all for all-time totals instead of specifying from/to. Response: OverviewTrendsSummaryResponse — result.ai_bot_visits, result.human_visits, result.non_accessible_pages.
get_ai_answer_changes
ChatGPTPeriod-over-period change report: which AI answers appeared (or disappeared) between two date ranges. Use to detect emerging mentions or sudden loss of visibility. Example: "What new AI answers appeared this week vs. last week that mention my brand?" Required: project_id (path), period_filter (date range comparison spec). Optional: include_vanished (default true — also returns answers that vanished); standard common filters. Response: AnswersChangesResponse with added and vanished (when included) answer lists.
get_ai_answer_counts
ChatGPTAggregate counts of AI answers across the project — total mentions, breakdown by platform, breakdown by mention type. Headline numbers without the answer text. Example: "How many AI answers mention my brand in total this month?" Required: project_id (path). Optional: standard common filters; has_shopping_data / has_ads_data to scope. Response: PromptsAnswersCountResponse with total counts and per-dimension breakdowns.
get_all_ai_answers
ChatGPTAll AI answers across every tracked prompt that mention your brand or competitors. Useful for bulk export or sample-set browsing of every mention. Example: "Show me every AI answer this week that mentions my brand, across all my tracked prompts." Required: project_id (path). Optional: standard common filters; has_shopping_data / has_ads_data to scope. Response: PromptsAnswersResponse with answer entries: prompt text, answer excerpt, platform, mentioned brands. Note: returns per-run metadata only (rank, visibility, platform, date, mentioned brands, cited-page count) — the full answer text is omitted to keep responses lightweight. Fetch a single run's full answer text + citations with get_prompt_result_details(result_id=<id>).
get_all_brand_gap_opportunities
ChatGPTPaginated list of brand-gap opportunities. Each entry is a third-party page being cited by AI where your competitors appear but you don't — i.e. a place where outreach or content placement could win back the citation. Example: "Show me the paginated list of brand-gap opportunities — pages I should target for outreach." Required: project_id (path). Optional: standard ActionablesFilters — page, size, search, sort, status filter. Response: CustomPage[ThirdPartySitesItemsToAddressResponse] with entries: third-party page URL, prompts citing it, competitors mentioned, sample answers.
get_all_broken_pages
ChatGPTPaginated list of broken pages on your domain that AI platforms are citing — pages returning 4xx/5xx, timing out, or otherwise unreachable. These are highest-priority fixes because AI is sending visitors to dead URLs. Example: "What broken pages on my site are AI platforms still citing? Show me the paginated list." Required: project_id (path). Optional: standard ActionablesFilters — page, size, search, sort_by, sort_order, status_filter, date range. Response: CustomPage[BrokenPagesItemsToAddressResponse] with paginated entries: URL, HTTP status, citation count, sample AI answers.
get_all_citations
ChatGPTList individual citation records (URL, domain, title) found in AI responses. Example: "Show all citations from wikipedia.org." Unlike /reports/citations which returns aggregated counts, this returns raw citation rows. Metrics (optional): citation_share, citing_answers, citing_answers_mentioning_you, visibility_contribution, source_type, platforms, topics, content_last_cited. Omit for the plain listing. Any metric switches to the dashboard's All Citations engine, so values match the app exactly; with comparison_start_date / comparison_end_date the numeric metrics also carry previous_<metric>. Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, domain, url, path. With metrics: path, rank, visibility, has_shopping_card and tree-style advanced_filters are not supported (400), because the All Citations engine does not evaluate them; platform values naming a model widen to that model's provider. Sort fields: domain, url, title for the listing; with metrics, any numeric metric or content_last_cited. Dates: Defaults to all-time when no dates provided. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all individual citations - every specific URL/page where the brand was referenced in AI responses. Use this to audit specific citation sources. For aggregated citation counts grouped by dimensions, use query_citation_report instead. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_domains
ChatGPTBrowse all external domains that appear in AI response citations. Example: "Which domains cite us most across AI platforms?" Metrics (optional): num_answers, platform_count Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, url, name. Sort fields: Any metric name, plus domain. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all domains that cite the brand in AI responses, aggregated by domain. Different from get_all_citations which returns individual URLs - this groups by domain for a higher-level view of citing sources. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_keywords
ChatGPTBrowse keywords that AI models associate with your brand, organized by theme and subtheme. Example: "Which keywords does ChatGPT use when discussing our brand?" Metrics (optional): website_count, subtheme_count, theme_count Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, theme, subtheme, websites, brand_name, keyword. Sort fields: Any metric name, plus keyword, theme, subtheme. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all keywords found in AI responses related to the brand. Use this to discover which words and phrases AI models associate with the brand. Useful for content strategy and understanding brand perception. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_markets
ChatGPTBrowse all geographic markets and their tracking coverage. Example: "Which regions have the most prompts and highest visibility?" Metrics (optional): prompts_count, answers_count, visibility Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, region, subpage. Sort fields: Any metric name, plus name, region. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all geographic markets being tracked. Use this to see performance by region and discover which markets are available for filtering in report queries. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_models
ChatGPTList the AI platforms tracked for this project (ChatGPT, Perplexity, Gemini, etc.): name and icon for each. It returns no performance metrics; for visibility, mentions or citations per platform use query_performance_report with the model dimension. Example: "Which AI platforms are being monitored?" Required: project_id. Optional: filters (e.g. name), order_by on name, pagination (limit 1-100, default 10; offset). Response: data (one row per platform) and info.total_rows.
get_all_new_content_opportunities
ChatGPTTopics 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. Example: "What new content should I create to capture AI visibility I'm missing?" Required: project_id (path). Optional: standard ActionablesFilters. Response: GeoContentActionablesResponse listing content opportunities: topic, target query set, estimated visibility lift, suggested content angle.
get_all_optimization_opportunities
ChatGPTExisting pages on your domain that need optimization — pages AI is citing where the content has structural issues (missing headings, thin coverage, outdated, etc.) that, if fixed, would likely lift the citation rate or sentiment. Example: "Which of my existing pages need content optimization based on how AI is citing them?" Required: project_id (path). Optional: standard ActionablesFilters. Response: GeoOptimizationActionablesResponse listing pages with detected issues, severity, and impact estimate.
get_all_portfolios
ChatGPTList every portfolio configured for the project. Use this to discover portfolio_id values needed by the other portfolio tools (add-pages, remove-pages, rename, delete, edit). Example: "Show me all portfolios in this project." Required: project_id (query). Response: AllPortfoliosResponse with the site_id and the list of portfolios (id, name, site_id per item).
get_all_projects
ChatGPTGet all projects that have geo presence tracking enabled. Every other tool needs a project_id, and this is where it comes from. Example: "List my projects to get project_id values for other endpoints." Only returns projects where a geo presence site has been configured. Projects without tracking setup are excluded. Filters: optional query (substring on name/url). Pagination: limit (1-100, default 50) + offset; projects are sorted by creation date (newest first). Response: data array (each item has id, name, url, created_at, type) plus total (matches before paging), limit, offset. If total > items returned, page with offset — or narrow with query. What `project_id` is and how to use it: - The id field of a project is its project_id. It is a UUID like 699aacd8-f75d-41b9-9fa8-7dde1bd82d02 (not the name or url). - Steps: (1) find the project whose name/url matches the user's request, (2) take that project's id value verbatim, (3) pass it as the project_id argument on every later tool call this conversation (reports, prompts, citations, sentiment, writes). - One lookup per conversation is enough; the same id applies until the user switches projects. - The id is in this response, so the user doesn't need to supply it; a project's name or url is not the id. - When exactly one project is returned, its id is the one to use. Tip: when you only need one project's id (e.g. the user named a brand or domain), pass the query argument (that brand/domain) — it returns just the matching project(s), so the list stays short and the id is always visible. What this does: Fetches all projects accessible to the user. Every other tool takes a project_id, which comes from this tool's response. Each project includes a type field: STANDARD (regular project) or PITCH (agency pitch-workspace project). Use it to answer questions about project type or to filter standard vs pitch projects.
get_all_prompts
ChatGPTList all tracked prompts/queries in your project, each with its topic, market, tags and branded flag. Example: "Show me all prompts with their AI visibility and rank, filtered by a specific topic." Metrics (optional): answers_count, answers, answers_detailed, visibility_score, citation_share, rank, mention_count, citing_answers - Performance metrics are computed for your brand over the date range, with the same definitions as get_performance_report grouped by query. rank is 0 when the brand is never mentioned. - answers_detailed returns each answer with id, mention_self, brands_mentioned, rank and inaccuracies. It is a large payload — use a small limit. - When any metric is requested, platforms lists the AI models that answered the prompt in the range. Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, disabled. - Answer-level filters (rank, visibility, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation) keep only prompts with at least one matching answer in the date range, and metrics are computed over those matching answers. E.g. rank with lte 3 lists the prompts where your brand ranked top 3 in some answer; visibility_score is then 100 by construction, while rank and answers_count describe only the top-3 answers. Paused prompts: Paused (disabled) prompts are excluded by default. Pass disabled with is true to list only paused prompts, or {"condition": "OR", "items": [{"operator": "is", "value": true}, {"operator": "is", "value": false}]} for both. Each row reports its own disabled flag. Sort fields: answers_count, visibility_score, citation_share, rank, mention_count, citing_answers, plus name, search_volume. Sorting by a metric also includes it in every row. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all prompts (search queries) tracked in the project. Use this to browse and discover which queries are being monitored, get their IDs, visibility scores, and mention counts. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_prompts_with_metrics
ChatGPTFlat list of every tracked prompt in a project with rolled-up metrics — visibility, mention count, citations, last-run date. Note: this lists prompts that have run at least once (metrics come from their runs). A newly created prompt is QUEUED and will NOT appear here until after its first run — so its absence right after create_prompt is expected, not a failure. Example: "Give me all my tracked prompts with their headline metrics." Required: project_id (path). Optional: standard common filters; has_shopping_data / has_ads_data to scope to prompts with shopping/ad placements. Response: PromptsAllResponse listing prompts with per-prompt summary metrics.
get_all_tags
ChatGPTList all tags (custom labels attached to prompts). Example: "Show tags with their query counts and associated competitors." Metrics (optional): query_count, competitor_count, queries, competitors Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, slug, competitors. Sort fields: Any metric name, plus name. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all tags in the project. Tags are user-defined custom labels for categorizing prompts. Use this to discover available tags and their IDs for filtering in other tools. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_topics
ChatGPTList all topics (categories that group prompts). Example: "Which topics have the most prompts?" Metrics (optional): prompts_count, prompts Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation. Sort fields: Any metric name, plus name. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all topics in the project. Topics are high-level categories that group related prompts. Use this to see the topic structure and find topic IDs for filtering in other tools. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_all_websites
ChatGPTCompare your brand against competitors with per-website performance metrics. Example: "Benchmark visibility and citation share across all tracked websites." Metrics (optional): mentions_count, citation_share, cited_answers, visibility_score, rank citation_share is the percentage of answers in the period citing one of the website's domains (0-100), the same definition as /reports/performance. Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, url, name. Sort fields: Any metric name, plus name. Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting. Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters). What this does: Fetches all tracked websites (the user's brand + competitors). Use this to see which websites are being tracked, get website IDs, and compare per-website metrics. Call this when the user asks about competitors or competitive benchmarking. How to use: - Requires project_id (get it from get_all_projects first). - Use filters to narrow down to specific items if needed. All filters are optional. - Use order_by to sort results by any field (e.g., [{"field": "visibility_score", "order": "desc"}]). - Use pagination to limit results (e.g., {"limit": 10, "offset": 0}). - Use metrics to request additional computed fields in the response.
get_brand_gap_existing_mentions
ChatGPTAI answers that mention your brand via a third-party site citation. Inverse of brand-gap — these are wins you should reinforce rather than gaps to close. Example: "Show me AI answers where my brand is already mentioned through a third-party site citation." Required: project_id (path). Optional: standard ActionablesFilters. Response: Page[LLMResponseData] with paginated AI response entries that mention your brand through third-party citations.
get_brand_gap_impact
ChatGPTEstimated visibility impact if you claim each third-party brand-gap mention. Quantifies what closing the gap is worth. Example: "For each brand-gap opportunity, what's the estimated visibility lift if I claim it?" Required: project_id (path). Optional: standard ActionablesFilters. Response: Page[ThirdPartySitesImpactsAndResultsResponse] with paginated entries: opportunity, estimated lift in mentions/visibility score, confidence band.
get_brand_gap_responses
ChatGPTSample AI responses that cite third-party sites in your brand-gap set. Use this to see exactly what AI is saying alongside the competitor citation, so you can craft an outreach pitch. Example: "Show me the actual AI answers where third-party sites in my brand-gap set are getting cited." Required: project_id (path). Optional: standard ActionablesFilters. Response: Page[LLMResponseData] with paginated AI response entries: prompt, answer text, platform, third-party site cited.
get_brand_gap_summary
ChatGPTSummary of brand-gap opportunities — AI answers where your competitors are mentioned but you are NOT. Grouped by third-party site (where the competitor mention originated) with totals. Example: "Where am I missing from AI answers that mention my competitors? Give me the summary." Required: project_id (path). Optional: standard ActionablesFilters. Response: MissedAnswersSummaryResponse with per-site counts, top missed prompts, and the competitors you're losing to.
get_brand_radar_report_filters
ChatGPTReturn the set of filter values available for a specific Brand Radar report — the citing domains, citing pages, and queries that appear in the report's data. Use this to populate filter dropdowns before calling the read endpoints. Required: project_id (query), report_id (path). Optional: include_citations (default true), include_queries (default true). Response: BrandRadarReportFiltersResponse with the available filter values.
get_broken_pages_impact
ChatGPTBefore/after metrics for broken-page fixes — for pages already marked resolved, shows the citation/visibility lift you got. Use this to demonstrate ROI of broken-page work. Example: "For broken pages I've already fixed, show me the visibility lift each one produced." Required: project_id (path). Optional: standard ActionablesFilters — pagination, sort, filter by status. Response: Page[BrokenPagesImpactsAndResultsResponse] with paginated entries: URL, fix date, before/after citation count, lift estimate.
get_citation_decay
ChatGPTHow your citation share is holding up over the last 14 days, broken down by AI platform or by topic. Use this to see where your citations are fading and where they are holding. Example: "Is my citation share on Perplexity decaying faster than on ChatGPT?" Required: project_id (path). Optional: dimension (platform default, or topic), standard common filters. Response: CitationDecayDimensionResponse with per-platform (or per-topic) peak share, half-life, days to peak, and a 14-point share trend. decay_coverage reports how many of those 14 days the project actually scanned; null entries in share_trend are days with no scan, not days with no citation.
get_domain_citation_answers
ChatGPTSample AI answers (across tracked prompts) that cite your domain. Useful for spot-checking what context AI is presenting alongside your citations. Example: "Show me 20 recent AI answers that cite my domain — I want to see what they're saying." Required: project_id (path). Optional: standard common filters. Response: DomainAnalyticsAnswersResponse with answer entries: text excerpt, source prompt, platform, the page on your domain cited. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_citation_platforms
ChatGPTWhich AI platforms cite your domain most. Breakdown by platform (ChatGPT, Perplexity, Gemini, Copilot, etc.) with citation counts and share. Example: "Which AI platform sends me the most citations?" Required: project_id (path). Optional: standard common filters. Response: CitationsAnalyticsPlatformResponse with per-platform citation count and share. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_citation_prompts
ChatGPTWhich tracked prompts produce the most AI citations to your domain. Ranks prompts by citation count attributable to your domain. Example: "What prompts is my domain getting cited for most?" Required: project_id (path). Optional: standard common filters. Response: CitationsAnalyticsPromptsResponse listing top prompts with citation counts and sample cited pages. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_citation_topics
ChatGPTTopic categories where your domain gets cited most. Rolls up citations to the parent topic to show which themes drive your AI visibility. Example: "What topics is my domain getting cited for most often?" Required: project_id (path). Optional: standard common filters. Response: CitationsAnalyticsTopicsResponse listing topics ranked by citation count, with prompt and page samples. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_citation_trends
ChatGPTTime-series of how often AI platforms cite your domain across all tracked prompts. Use this to see whether your domain's citation footprint is growing, shrinking, or stable. Example: "Weekly citation count for my domain across ChatGPT and Perplexity over the last 90 days." Required: project_id (path). Optional: aggregate_level (daily default, weekly, monthly), include_events (overlay key events; default true), standard common filters. Response: DomainAnalyticsTrendsResponse with time-bucketed citation counts. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_pages_cited
ChatGPTYour domain's most-cited pages — ranked by how often AI platforms cite each page across tracked prompts. Example: "What pages on my site are AI platforms citing the most?" Required: project_id (path). Optional: standard common filters (platform, date range, etc.). Response: DomainAnalyticsPagesCitedResponse listing your domain's pages with citation count, sample prompts, and platforms citing them. Required: domain (the brand's own website domain, e.g. writesonic.com, from the project's own site in get_all_websites) and the date range. Without domain the result is empty because the argument is missing, not because there are no citations. For domain-level platform and page questions this tool is more direct than query_citation_report.
get_domain_subdomains
ChatGPTBreaks a cited domain down by subdomain (e.g. docs., help., app.). www. is folded into the root domain. Example: "Which subdomains of this domain do AI platforms cite, and how much does each contribute?" Required: project_id (path), domain (query). Optional: standard common filters. Response: DomainAnalyticsSubdomainsResponse with per-subdomain domain share, citation share, citing answers and unique pages cited, sorted by citation share (desc). total is the number of cited subdomains.
get_facts
ChatGPTList the brand facts tracked for this project, split into approved and suggested sections. Suggested facts are AI-generated and need review before they count toward fact-checking; use their ids with update_fact_status to accept (APPROVED) or reject (DISCARDED) them. Example: "What facts do we have for this brand, and which ones are still pending approval?" Required: project_id (path). Response: FactsListResponse — approved and suggested, each a paginated list of facts (id, fact, source, status, created_at, ...).
get_filter_values
ChatGPTDiscover the values that exist in a project — topic, tag, market, platform and website IDs, prompts, cited domains and more — and learn where each value can be used. Report endpoints accept these exact values and IDs. Example: "Which topics and platforms does this project track, and what do I pass to filter a report by them?" Response shape: dimensions is keyed by dimension name. Each entry has: - filter_field — the key(s) under filters on the business endpoints that accept these values. Empty means the dimension can only be used for grouping. - report_dimension — the value to pass in dimensions on /reports/performance, /reports/citations, /reports/sentiments to group by it. - items — the values. Each has name and usually id; some carry extras (domain, language, is_self, branded, count). - total_rows — only on paginated dimensions: total values before pagination. How to use a value: 1. Item has id → {"<filter_field>": {"items": [{"operator": "is", "value": "<id>"}]}} 2. Item has no id (cited_domains, cited_pages) → use name with is or contains. 3. filter_field is [] → pass report_dimension in dimensions on a /reports/* call instead. Worked example: topics.items[0] = {"id": "052e…", "name": "AEC"} and platforms.items[0] = {"id": "f4d0…", "name": "ChatGPT"} → POST /reports/performance {"dimensions": ["topic"], "filters": {"topics": {"items": [{"operator": "is", "value": "052e…"}]}, "platform": {"items": [{"operator": "is", "value": "f4d0…"}]}}} Dimensions: | dimension | filter_field | report_dimension | notes | |---|---|---|---| | topics | topics | topic | | | tags | tags | tag | | | markets | markets | market | name is the region code; language included | | platforms | platform | model | id is the model id; name e.g. "ChatGPT" | | websites | website_mentioned_in_answer, website_mentioned_in_citation | website | your brand (is_self: true) and competitors; domain included | | prompt_types | branded | branded | id "true"/"false" with prompt count — pass as a boolean | | search_intent | intent | search_intent | transactional, navigational, informational, commercial | | source_types | — | source_type | owned, competitor, social_forums, third_party | | personas / intent_stages / localities | — | persona / intent_stage / locality | prompt targets; grouping only | | themes / subthemes | — | theme / subtheme | paginated; sentiment grouping only | | prompts | prompts | query | paginated; branded flag per prompt | | cited_domains | cited_domain | domain | paginated, date-scoped; no id | | cited_pages | cited_page_url | page | paginated, date-scoped; no id; domain included | Selecting dimensions: omit dimensions to get every non-paginated dimension in one call. Ask for prompts, themes, subthemes, cited_domains, cited_pages explicitly. Dates: only cited_domains and cited_pages are date-scoped; without start_date/end_date they use the latest run. Other dimensions ignore dates. Search: search is a case-insensitive substring match on the paginated dimensions — prompt text, theme/subtheme name, cited domain, cited page URL. Other dimensions ignore it. total_rows counts the matches. Ordering: prompts by search volume (highest first), cited_domains / cited_pages by how many answers cite them (most first), the rest by name. Pagination: one pagination (limit 1-100, default 10; offset) applies to every paginated dimension in the request — dimensions: ["prompts", "cited_domains"] with limit: 3 returns the first 3 of each. Read each dimension's total_rows, not the item count, to know how many values exist; page or search to see the rest. Response: dimensions as above, plus info.query echoing the dates and pagination used.
get_geo_onboarding_status
ChatGPTFull setup/tracking status for a project — whether the site is active and tracked, per-market onboarding progress and prompt counts, plan access and limits, and whether an analysis run is currently in flight. Example: "Is my project set up and active? Which markets are still onboarding?" Required: project_id (path). Response: GeoPresenceStatusOutput — is_site_active, is_site_tracked, presence_state, is_onboarding_cron_in_progress, market_data, available_in_plan, limits.
get_industry_cited_pages
ChatGPTPages AI platforms cite in your industry across tracked prompts — INCLUDING competitors and third-party domains. Use this to see the overall citation landscape, not just your own pages. Example: "Show me the top 50 pages AI platforms are citing in my industry, regardless of which domain they belong to." Required: project_id (path). Optional: standard common filters (cited_domain to scope to one domain). Response: DomainAnalyticsCitedPagesResponse listing cited pages with domain, citation count, and sample prompts.
get_kpi_summary
ChatGPTKPI summary card for a project — total visibility, mention count, citations, sentiment breakdown, plus deltas vs. previous period. Use this as a single-call dashboard view. Example: "Give me the headline KPIs for my project this month with deltas vs last month." Required: project_id (path). Optional: standard common filters set the current period; previous-period comparison is automatic when a date range is set. Response: PromptsOverviewTopMetricsResponse with current values, previous values, and deltas for each KPI.
get_new_content_impact
ChatGPTEstimated visibility gains if each new-content opportunity is published. Lets you prioritize which content brief to ship first based on projected lift. Example: "Rank my new-content opportunities by estimated visibility lift." Required: project_id (path). Optional: standard ActionablesFilters. Response: Page[NewContentImpactsAndResultsItem] with paginated entries: opportunity, estimated visibility lift, confidence band.
get_new_content_sample_answers
ChatGPTSample AI answers from queries that would be addressed by a specific new-content opportunity. Lets you see what AI is currently saying about a topic before deciding to create content. Example: "For new-content opportunity X, what is AI currently saying about this topic?" Required: project_id (path), content_id (path — opportunity UUID from /new-content-actionables). Optional: standard ActionablesFilters. Response: LLMResponsesResponse with AI response samples for the queries this opportunity covers.
get_optimization_fixes
ChatGPTConcrete AI-suggested fixes for the issues detected on an optimization page — actionable rewrites, structural changes, missing-section recommendations. Tied to a specific editor history snapshot. Example: "What specific edits does AI recommend for optimization page X based on its current issues?" Required: project_id (path), editor_history_id (path — references the editor history snapshot from the optimization workflow). Response: GetOptimizationFixesResponse with grouped fix suggestions: issue type, current text, proposed text, expected impact.
get_optimization_page_answers
ChatGPTSample AI answers that cite a specific page flagged for optimization. Use this to see what AI is currently quoting from the page so you know what to preserve when rewriting. Example: "For the optimization candidate page X, what is AI currently citing from it?" Required: project_id (path), optimization_page_id (path — page UUID from /optimize-content-actionables). Optional: standard ActionablesFilters. Response: Page[LLMResponseData] with paginated AI response entries citing the page.
get_portfolio_info
ChatGPTGet the metadata for a single portfolio (id, name, site_id). Example: "Show me the details for my 'Competitor Pages' portfolio." Required: project_id (query), portfolio_id (query). Response: PortfolioInfoResponse with the portfolio's id, name, and site_id.
get_portfolio_overview
ChatGPTPerformance metrics for portfolios in a project: citation share, citing answers, citations mentioning your brand, visibility contribution, and totals (with period-over-period change). Pass portfolio_id to scope to a single portfolio. Example: "Give me the portfolio metrics for my 'Docs & API' portfolio." Required: project_id (query). Optional: portfolio_id, date-range filters. Response: PortfolioOverviewResponse with per-portfolio metric items.
get_project_visibility_trends
ChatGPTProject-wide visibility trends over time. Aggregates visibility metrics across all tracked prompts, so you see how the whole project is trending — not a single prompt. Example: "Plot weekly aggregate visibility for my project across all tracked prompts for the last 90 days." Required: project_id (path), graph_type (visibility, mention_count, etc. — see GraphType enum). Optional: aggregate_level (daily default, weekly, monthly), include_events (default true), standard common filters. Response: TrendsPromptsOverviewResponse with time-bucketed values for the chosen metric.
get_prompt_answers
ChatGPTList the AI answers for one tracked prompt across runs, with per-run metadata: rank, visibility, platform, date, mentioned brands and number of cited pages. The answer text itself is not included; get one run's full text and citations with get_prompt_result_details(result_id=...). Example: "How did AI platforms answer 'best CRM for startups', and which brands did they mention?" Required: project_id. Pass the prompt's id as query_id to get that prompt's answers. Optional: the standard filters (dates, markets, topics, providers, ...); has_shopping_data / has_ads_data to keep only answers with product cards or ad placements. Response: the answer runs, ranked.
get_prompt_citations
ChatGPTPages that AI platforms cite when answering a single tracked prompt. Distinct from prompt-answers which gives the text — this returns the source URLs that the AI grounded its answer in. Example: "Which web pages does ChatGPT cite when someone asks 'best CRM for startups'?" Required: project_id (path). Optional: standard common filters (platform, date range, etc.); cited_domain to scope to one domain. Response: PromptCitationsResponse with citation entries: URL, source domain, the answer they appeared in, and the prompt run metadata.
get_prompt_explorer_overview
ChatGPTInvestigate a single prompt: returns the AI platform's response text, the prompt's monthly search volume estimate, and related prompts. Example: "What does ChatGPT say when someone asks 'best CRM for startups'? Show me the response and how often this question is asked." Required: prompt (the natural-language query to investigate), project_id. Optional: platforms (defaults to ["chatgpt"]; supported: chatgpt, perplexity, google_ai_overview, gemini, copilot), prediction_uuid / history_id (to fetch a previously-investigated prompt by ID), folder_id (to scope to a folder of saved prompts). Response: VolumeResultResponse with the AI response, search volume estimate, related prompts, and citation breakdown by platform. Budget note: Each investigation consumes one prompt-explorer credit. Returns 403 when budget is exhausted.
get_prompt_explorer_search_history
ChatGPTList previously-investigated prompts for a project, with pagination. Each entry includes the prompt text, when it was investigated, and a reference ID you can pass to /prompt-explorer (via history_id) to re-fetch the original results without spending a new credit. Example: "What prompts have I already investigated this month?" Required: project_id. Optional: page (default 1), size (default 20, max 100). Response: Paginated PromptExplorerHistoryResponse items with total count, page, size, and items array.
get_prompt_info
ChatGPTStatic metadata for a single tracked prompt: text, topic assignment, attached tags, intent classification, monthly search volume, whether it's branded, the markets and platforms it runs in. Example: "Give me everything you know about the prompt 'best CRM for startups' — its topic, tags, search volume, intent." Required: project_id (path), prompts filter (must resolve to exactly one prompt). Optional: standard common filters scope the lookup. Response: PromptInfoResponse with prompt text, topic, tags, intent, branded flag, volume estimate, market/platform assignments. Returns 404 when no prompt matches the filter.
get_prompt_result_compare
ChatGPTCompare a single prompt result against its baseline (typically the prior run or a fixed baseline run). Lighter-weight than /results-compare which compares two arbitrary result IDs. Example: "How does the latest ChatGPT response for 'best CRM for startups' compare to its baseline?" Required: project_id (path). Optional: standard common filters scope which prompt and which run. Response: ResultCompareResponse with the two compared answers, citation deltas, and mention diffs.
get_prompt_result_details
ChatGPTFull detail snapshot of a single AI-platform run for one tracked prompt: the AI response text, citations extracted from it, structural metadata (which platform produced it, when), and the brand mentions identified. Example: "Show me the most recent ChatGPT response for the prompt 'best CRM for startups' in detail." Required: project_id (path). Optional filters: standard common filters — prompts, topics, tags, markets, platform, intent, branded, date range, etc. Response: ResultDetailsResponse with the raw answer, citations, mention positions, and metadata.
get_prompt_results_compare
ChatGPTDiff two specific AI response runs for the same prompt. Returns side-by-side comparison of text, citations, and brand mentions so you can see what changed between runs. Example: "Compare yesterday's ChatGPT response for 'best CRM for startups' against today's run — what changed?" Required: project_id (path), current_result_id (query), previous_result_id (query). Result IDs come from /result-details or the prompt history. Optional filters: standard common filters. Response: ResultsCompareResponse with both runs' answer text, citation lists, mention deltas, and structural diffs.
get_prompt_search_queries
ChatGPTRelated search queries surfaced for a tracked prompt — the broader query fan-out the AI considered when generating its answer. Useful for understanding adjacent intent the prompt covers. Example: "What related search queries does ChatGPT pull from when answering 'best CRM for startups'?" Required: project_id (path). Optional: standard common filters. Response: PromptSearchQueriesResponse listing related queries with frequency and source attribution.
get_prompt_sentiment_trends
ChatGPTTime-series of sentiment polarity (positive / neutral / negative) for AI mentions of brands inside a single tracked prompt. Use this to see how AI tone around your brand shifts over time. Example: "Plot weekly positive vs negative sentiment for mentions of my brand inside the 'best CRM for startups' prompt over the last 90 days." Required: project_id (path). Optional: aggregate_level (daily default, weekly, monthly), include_events (overlay key events; default true), standard common filters. Response: PromptSentimentTrendsResponse with time-bucketed sentiment counts and percentages per bucket.
get_prompt_snippets
ChatGPTShort text excerpts pulled from AI answers for a single tracked prompt, focused on the surrounding context where brand mentions occur. Useful for surfacing what AI is actually saying about brands without reading full answers. Example: "Pull me the 1-2 sentence excerpts from AI answers about 'best CRM for startups' that mention Salesforce." Required: project_id (path). Optional: standard common filters. Response: PromptSnippetsResponse with excerpts: the surrounding text, the mentioned brand/website, sentiment polarity, and the source answer.
get_prompt_trends
ChatGPTTime-series of visibility and mention metrics for one or more tracked prompts. Useful for trend lines on a single prompt's performance over time. Example: "Plot weekly visibility for 'best CRM for startups' across all AI platforms for the last quarter." Required: project_id (path). Optional: aggregate_level (daily default, weekly, monthly), include_events (overlay key events like prompt edits onto the timeline; default true), standard common filters (prompts, topics, date range, platform, etc.). Response: PromptTrendsResponse with time-bucketed mention counts, visibility scores, and optional event overlay points.
get_prompts_leaderboard
ChatGPTRanked leaderboard of tracked prompts in a project. Default ranking is by visibility score; supports re-ranking via filter sort fields. Example: "Show me my top 25 tracked prompts by visibility this month." Required: project_id (path). Optional: standard common filters (topics, tags, markets, platform, date range, sort options). Response: LeaderboardPromptsOverviewResponse with ranked prompt entries: prompt text, visibility score, mention count, search volume.
get_prompts_not_mentioning_you
ChatGPTOpportunity set — high-volume tracked prompts where your brand is NOT appearing in AI answers. These are the gaps to close. Example: "Show me the top-volume prompts where my brand is missing from AI answers. These are gaps I should target." Required: project_id (path). Optional: standard common filters. Response: PromptsNotMentioningYouResponse listing prompts with monthly volume, the competitors who do appear, and the gap size.
get_sentiment_overview
ChatGPTHeadline brand-sentiment summary - the SAME numbers shown on the Writesonic sentiment dashboard: positive vs negative sentiment counts, overall sentiment_score, and its period-over-period change. Use this for "what is my brand's sentiment?" so the answer matches the UI. For analytical breakdowns by topic/model/date or keyword-occurrence counts, use query_sentiment_report instead (different, report-style numbers). Required: project_id (path). Optional: date-range filters (defaults to the dashboard's window when omitted). Response: SentimentsOverviewResponseV2 (positive/negative sentiment, sentiment_score, sentiment_score_change).
get_sentiment_report
ChatGPTSentiment 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. Example: "How is our brand's sentiment trending week over week?" or "Which themes are AI platforms negative about, compared with last month?" How sentiment is computed: every keyword hit in an answer carries a 0-100 sentiment; 50 and above is positive (neutral counts as positive). Hits are summed per subtheme, and a subtheme is voted positive when its positive hits are greater than or equal to its negative hits, negative otherwise. positive and negative are the numbers of subthemes with each vote, and sentiment_score = positive / (positive + negative) * 100 (null when nothing was voted). The same vote is used for every grouping, so which dashboard screen a row agrees with depends on the grouping — see below. Grouping: group_by = date, platform, website, theme, subtheme or topic; omit it for a single row over the whole range. The vote is re-run inside each group over that group's hits, so rows are not additive: a subtheme positive overall may be negative on one platform, and per-group counts do not sum to the ungrouped row. Consequences: - No group_by, topic and platform match the dashboard's Sentiment overview (summary, topics and platforms cards). platform rows are per provider (ChatGPT, Perplexity, ...), with all of a provider's models combined before the vote. - website matches the Competitors leaderboard vote; it covers your brand plus direct competitors (each website's own keywords), and websites with no hits are omitted rather than returned as 0/0. Every other grouping is your brand only. - theme and subtheme are the vote, not the Themes table, which shows the hit ratio positive hits / total hits * 100. subtheme rows are their own vote: positive + negative = 1 and the score is 0 or 100; theme rows count the theme's subthemes by their vote. Expect them to differ from the Themes table for the same range. - date rows use interval = day (default: one row per day with keyword hits), week or month (every bucket in the range, clipped to it, 0/0 where empty). Week and month rows re-vote over the bucket's hits, never average daily scores. interval is ignored for other groupings. This is a per-bucket re-vote, not the Trends chart, which counts answers with a positive vs. a negative hit per day. Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, status, sentiment. - sentiment is numeric (0-100) and keeps only the keyword hits whose score matches before the vote (e.g. sentiment lt 50 votes over negative hits only). Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (both required together) to also get change on positive and negative and sentiment_score_change, computed for the same groups over the comparison range with identical filters. Without group_by the comparison range is always a baseline (0/0 when nothing was voted, as on the Sentiment overview card), so all three changes are numbers. A grouped row with no comparison row has null change and sentiment_score_change, as on the Competitors leaderboard and Themes table. date rows match the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (bucket-aligned for week/month). Sorting: order_by fields: sentiment_score (default, descending), positive, negative, name; ties break by name. date rows are always chronological. Pagination: Use pagination (limit 1-100, default 10; offset for paging). Not applied to date rows: the whole series is returned. Response: Returns data…
get_shopping_leaderboard
ChatGPTBrand vs competitor leaderboard for shopping-card visibility. Requires project_id.
get_shopping_performance_by_topics
ChatGPTShopping visibility broken down by topic. Requires project_id.
get_shopping_rank
ChatGPTYour brand's average rank in AI shopping-card responses (lower is better). This is the rank shown on the Shopping screen, which query_performance_report does not compute. Requires project_id.
get_shopping_report
ChatGPTShopping-placement metrics grouped by one or more dimensions. This is the report behind the UI Shopping screen — use it for shopping visibility, direct-link share, product rank and per-product or per-merchant breakdowns. /reports/performance cannot produce these. Example: "Which merchants carry purchase links for my products, by topic?" Dimensions (at least 1 required): topic, tag, market, model, query, date, website, branded, product, placement_type, merchant - product rows also carry product_image, product_link, brand_id / brand_name / brand_url / brand_logo, brand_is_self and product_source_type (owned | competitor | third_party | unconfigured); merchant rows carry merchant_url, merchant_logo, merchant_is_self - date supports optional date_aggregation_interval: day (default) | week | month; buckets on the placement date - website is the brand that owns the product, and auto-sets website_type to SELF+COMPETITORS; product / merchant auto-set it to ALL, like the dashboard's All Products / Merchants pages (default otherwise is SELF) - website_type: ALL also returns untracked third-party brands, with a null website_id and an empty website_name Measures (omit for all): shopping_visibility, direct_link_share, share_of_shopping_voice, product_rank, answers_with_product, product_mentions, shopping_answers, unique_products, unique_merchants, buy_link_count, buy_link_share, avg_price - shopping_visibility = answers featuring this entity / shopping_answers (all answers in the group holding any shopping placement) - direct_link_share = this entity's placements whose purchase link points back at the product's own brand, over its own placements - share_of_shopping_voice = this brand's placements / all tracked brands' placements — placements, not answers, so a brand with three product cards in one answer counts three, as on the dashboard's Share of Voice chart - avg_price also returns avg_price_currency Filters: topics, prompts, tags, markets, intent, branded, platform, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, products, brands, merchants, placement_type, source_type, price, product_rank, has_direct_link. - has_shopping_card, has_ads_data, visibility, rank and status are accepted for compatibility with the other report endpoints and ignored here. - platform matches the model that produced the answer (stricter than /reports/performance, which matches prompts that ever ran on a platform). Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, product_name, merchant_name, placement_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_ values. Pagination: Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting. Response: Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters). Notes:* Days with no placements are omitted rather than zero-filled. Grouping by merchant/advertiser fans a placement out to one row per merchant, so column totals can exceed the ungrouped total; within a merchant row each placement still counts onc…
get_shopping_share_of_voice
ChatGPTYour brand's share of voice and shopping visibility in AI shopping-card responses, with competitors. These are the Shopping screen metrics; query_performance_report with a shopping dimension does not compute them. Requires project_id.
get_shopping_top_products
ChatGPTTop products surfaced in AI shopping cards. Set self_only=true for your brand only. Requires project_id.
get_shopping_visibility_trends
ChatGPTTime series of the brand's shopping performance in AI answers that show product cards. Example: "How has our shopping visibility changed week over week?" Required: project_id, graph_type: shopping-visibility or direct-purchase-link (share of answers with a direct purchase link). Optional: aggregate_level (daily, weekly or monthly), dates, and the standard filters (markets, topics, tags, providers, ...). Response: one point per period for the chosen metric.
get_top_prompts_by_volume
ChatGPTHighest-search-volume tracked prompts in a project. Use this to prioritize attention on prompts that real users ask most. Example: "Which tracked prompts have the highest monthly search volume?" Required: project_id (path). Optional: standard common filters. Response: TopPromptsResponse listing prompts ranked by volume, with prompt text, monthly volume estimate, topic, and tags.
get_top_prompts_driving_visibility
ChatGPTPrompts where your brand appears most often in AI answers. Use this to identify the prompts contributing most to your overall AI visibility. Example: "Which tracked prompts mention my brand most often in AI answers?" Required: project_id (path). Optional: standard common filters. Response: TopPromptMentionsResponse listing prompts ranked by mention count, with mention rate and sample answers.
get_trends_report
ChatGPTTime series of one metric, as one line per tracked website or per AI platform. Example: "Plot our weekly visibility score against competitors for the last quarter." or "Show citation share per AI platform by week." Metric (required): visibility_score, share_of_voice, citation_share, citing_answers, citation_count, mention_count, rank, number_of_answers Series: series_by = website (default: your brand plus direct competitors, across all AI platforms) or platform (your brand only, one line per AI model). Interval: interval = day (default: one point per day that has answers), week or month (every bucket in the range, clipped to it, zeros where empty). Week and month values are computed from the summed daily counts, not by averaging daily percentages. Points: every point carries value, count and total. Percentage metrics are count / total * 100; count metrics have value = count; rank is the average rank of the line's ranked mentions (count = ranked mentions; value is omitted when there are none). total is the number of answers in the bucket, except for share_of_voice where it is the mentioned answers across all tracked websites. Each line also has an aggregate over the whole range. Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (both required together) to also get previous_series: the same lines over the comparison range, with points dated in that range. Events: events lists the annotations overlapping the current range; pass include_events: false to skip them. Sorting and pagination: not applicable. All lines are returned, your brand first and then competitors, or platforms by name. Response: Returns series (one line per website or platform) with info metadata containing total_rows (number of lines) and query (applied metric, dates, filters).
get_webpage_citation_answers
ChatGPTSample AI answers that cite a specific page. Webpage-scoped equivalent of /domain/answers. Example: "Show me AI answers that cite my blog post at example.com/best-crm-guide." Required: project_id (path), cited_page_url filter. Optional: standard common filters. Response: DomainAnalyticsAnswersResponse with answer entries: text excerpt, source prompt, platform.
get_webpage_citation_platforms
ChatGPTWhich AI platforms cite a specific page most often. Webpage-scoped equivalent of /domain/platforms. Example: "Which AI platforms are citing my blog post at example.com/best-crm-guide?" Required: project_id (path), cited_page_url filter. Optional: standard common filters. Response: CitationsAnalyticsPlatformResponse with per-platform citation count and share for that page.
get_webpage_citation_prompts
ChatGPTWhich tracked prompts drive AI citations to a specific page. Webpage-scoped equivalent of /domain/prompts. Example: "What prompts is my blog post at example.com/best-crm-guide getting cited for?" Required: project_id (path), cited_page_url filter. Optional: standard common filters. Response: CitationsAnalyticsPromptsResponse listing prompts with citation counts for that page.
get_webpage_citation_topics
ChatGPTTopic categories driving AI citations to a specific page. Webpage-scoped equivalent of /domain/topics. Example: "What topic categories is my blog post at example.com/best-crm-guide getting cited for?" Required: project_id (path), cited_page_url filter. Optional: standard common filters. Response: CitationsAnalyticsTopicsResponse listing topics with citation counts for that page.
get_webpage_citation_trends
ChatGPTTime-series of how often AI platforms cite a single specific page across tracked prompts. Scope to one page via the cited_page_url filter. Example: "Show me weekly citation trend for my blog post at example.com/best-crm-guide over the last 6 months." Required: project_id (path), cited_page_url filter (the exact page URL). Optional: aggregate_level (daily default, weekly, monthly), include_events (default true), standard common filters. Response: CitationsAnalyticsWebpageTrendResponse with time-bucketed citation counts.
get_webpage_negative_sentiments
ChatGPTAI answers where a negative sentiment about your brand was sourced from a specific cited page, latest first. Each row carries the answer snippet with the negative sentence(s), the prompt, the platform, and when it was answered. Example: "Which AI answers picked up negative sentiment about us from example.com/best-crm-guide?" Required: project_id (path), citation_id filter. Optional: standard common filters, search. Response: WebpageSentimentsResponse — the full answer list (client-side pagination) with highlighted negative sentences, prompt, platform, and answered-on date. Note: Positive sentiment is not tracked at the page level; this only surfaces negative-sentiment answers.
list_brand_radar_reports
ChatGPTList the Brand Radar reports for a project. Use this to discover report_id values needed by the per-report read tools and by delete/bulk-delete. Required: project_id (path). Optional: report_ids (filter), limit, offset (pagination). Response: a paginated list of BrandRadarReportSummary.
query_citation_report
ChatGPTCitation metrics grouped by one or more dimensions. Example: "How many unique domains cite us per topic on each AI model?" Dimensions (at least 1 required): topic, tag, market, model, query, date, website, shopping, ads, branded, persona, intent_stage, locality, search_intent, domain, page, source_type - date supports optional date_aggregation_interval: day (default) | week | month - website auto-sets website_type to SELF+COMPETITORS (default is SELF) - website rows carry website_url, website_logo and is_self (true for your own brand) alongside website_id / website_name - persona / intent_stage / locality group by the prompt targets attached to each query; a query with several targets of one type counts once per target (like tag), and untargeted queries land in a null bucket - search_intent is the query's dominant intent: transactional, navigational, informational or commercial - Dimensions not listed here are rejected with 400 - domain, page, source_type group by the cited source (page returns citation_id, page_url, page_title). They always cover every cited source: website_type is ALL and sending SELF or SELF+COMPETITORS with them is a 400. A citation cited by prompts from several topics (or tags) counts once per topic, so [source_type, topic] rows add up to more than [source_type] alone - source_type classifies each cited domain, first match wins: owned (your domain and aliases) > competitor (direct competitor domains) > social_forums (social networks, forums, video and Q&A sites) > third_party (everything else) Measures (omit for all): count, unique_pages, unique_domains Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, volume, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, status, domains, paths. - volume is numeric (eq/neq/gt/gte/lt/lte) on the prompt's monthly search volume; prompts without a known volume never match - rank / visibility are numeric and keep only answers where your brand's mention matches (e.g. rank lte 3 = answers where you rank top 3) Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, persona_name, intent_stage_name, locality_name, search_intent, domain, page_url, source_type. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_ values. Pagination: Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting. Response: Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters). What this does: Queries aggregated citation metrics - citation counts, unique pages, unique domains grouped by dimensions. Use this to understand where and how often the brand is cited. Measures: `count` (total citations), `unique_pages`, `unique_domains`. Friendlier aliases also accepted: `citations` / `total_citations` / `citation_count` -> `count`, `pages` -> `unique_pages`, `domains` -> `unique_domains`. Note:* for share-of-citations as a percentage, use query_performance_report with the citation_share measure instead - that metric…
query_performance_report
ChatGPTBrand performance metrics grouped by one or more dimensions. For shopping-card analytics (shopping share of voice, shopping rank, shopping visibility, top products) use the dedicated get_shopping_* tools — those are the UI Shopping-screen metrics. Grouping this report by a shopping dimension only buckets generic metrics by shopping-card presence; it does not return shopping SoV/rank/visibility. Example: "Show me visibility score by model, broken down by week." Dimensions (at least 1 required): topic, tag, market, model, query, date, website, shopping, ads, branded, persona, intent_stage, locality, search_intent - date supports optional date_aggregation_interval: day (default) | week | month - website auto-sets website_type to SELF+COMPETITORS (default is SELF) - website rows carry website_url, website_logo and is_self (true for your own brand) alongside website_id / website_name - Competitor comparison: dimensions: ["website"] with measures: ["share_of_voice", "visibility_score", "citation_share", "rank", "sentiment"] gives one row per tracked website; add comparison dates for previous_*. Share-of-voice leaderboard: same call with order_by on share_of_voice desc - persona / intent_stage / locality group by the prompt targets attached to each query; a query with several targets of one type counts once per target (like tag), and untargeted queries land in a null bucket - search_intent is the query's dominant intent: transactional, navigational, informational or commercial - Dimensions not listed here are rejected with 400 Measures (omit for all): share_of_voice, citation_share, visibility_score, mention_count, citation_count, rank, citing_answers, number_of_answers, sentiment Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, volume, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, status. - volume is numeric (eq/neq/gt/gte/lt/lte) on the prompt's monthly search volume; prompts without a known volume never match - rank / visibility are numeric and keep only answers where your brand's mention matches (e.g. rank lte 3 = answers where you rank top 3) Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, persona_name, intent_stage_name, locality_name, search_intent. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_ values. Pagination: Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting. Response: Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters). With the `website` dimension, `total_rows` counts every tracked website × bucket row (one bucket per combination of the other dimensions' values that has answers in the range), including rows whose measures are all zero. What this does: Queries aggregated performance metrics - share of voice, citation share, visibility score, mention counts. This is the main analytics tool for understanding brand performance across any dimension. Measures:* share_of_voice, citation_share, mention_count, visibility_score, `ci…
query_sentiment_report
ChatGPTKeyword sentiment metrics grouped by one or more dimensions. Example: "Show positive keyword trends by topic, broken down monthly." Dimensions (at least 1 required): topic, tag, market, model, query, date, website, shopping, ads, branded, persona, intent_stage, locality, search_intent, theme, subtheme, keyword - date supports optional date_aggregation_interval: day (default) | week | month - website auto-sets website_type to SELF+COMPETITORS (default is SELF) - website rows carry website_url, website_logo and is_self (true for your own brand) alongside website_id / website_name - persona / intent_stage / locality group by the prompt targets attached to each query; a query with several targets of one type counts once per target (like tag), and untargeted queries land in a null bucket - search_intent is the query's dominant intent: transactional, navigational, informational or commercial - Dimensions not listed here are rejected with 400 - theme, subtheme, keyword group keyword occurrences by the sentiment taxonomy; theme / subtheme only cover classified keywords (occurrences whose keyword has no subtheme are excluded), keyword covers every keyword - keywords belong to the brand they were mined for, so website_type scopes them: the default SELF counts your own brand's keywords only, SELF+COMPETITORS and ALL add the tracked competitors' Measures (omit for all): total_keyword_occurrences, total_positive_keyword_occurrences, unique_positive_keywords, total_unique_keywords, positive_subtheme_count, negative_subtheme_count Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, volume, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, status. - volume is numeric (eq/neq/gt/gte/lt/lte) on the prompt's monthly search volume; prompts without a known volume never match - rank / visibility are numeric and keep only answers where your brand's mention matches (e.g. rank lte 3 = answers where you rank top 3) - sentiment (this report only) is numeric on the keyword sentiment score (0-100) and keeps only matching keyword occurrences, so every measure is computed over them (e.g. gte 70 = positive keywords only). As an advanced_filters leaf it instead keeps answers containing at least one matching keyword Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name, persona_name, intent_stage_name, locality_name, search_intent, theme_name, subtheme_name, keyword_name. Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range. Comparison: Provide comparison_start_date and comparison_end_date (ISO 8601, both required together) to also compute every measure over a past range — each row then gains previous_<measure> fields calculated with identical dimensions, measures, and filters. Rows match across periods by dimension; with the date dimension, each current bucket matches the comparison bucket exactly (start_date - comparison_start_date) earlier, so use equal-length ranges (and bucket-aligned ones for week/month intervals) — buckets with no counterpart simply omit previous_ values. Pagination: Use `pagination` (`limit` 1-100, default 10; `offset` for paging). Use `order_by` for sorting. Response: Returns `data` array with `info` metadata containing `total_rows` (before pagination) and `query` (applied metrics, dates, sorting, pagination, filters). What this does: Queries sentiment analysis metrics - keyword occurrences and positive sentiment scores. Use this to understand how AI models perceive and present the brand. Measures:* total_keyword_occurrences, total_positive_keyword_occurrences, unique_positive_keywords, total_unique_keywords, `positive_subtheme_count…
remove_pages_from_portfolio
ChatGPTDetach tracked pages from one portfolio. Example: "Remove these 3 tracked pages from my 'Competitor Pages' portfolio." Required: project_id, portfolio_id. Pass the page ids (not URLs) in pages. Optional: page_type: tracked_page (default) or citation (pages holds citation ids). should_stop_tracking (default false): also stop tracking the pages; otherwise they stay tracked and only leave the portfolio. Response: the removal status of each page.
rename_portfolio
ChatGPTRename a portfolio. Example: "Rename my 'Q1 Pages' portfolio to 'Q1 2026 Pages'." Required: project_id, portfolio_id (from get_all_portfolios), portfolio_name (the new name). Response: the portfolio id and its new name.
track_pages
ChatGPTStart tracking page URLs for a project, and optionally attach them to a portfolio in the same call. Example: "Track these pricing-page URLs and put them in a 'Pricing Pages' portfolio." This is the primary way to add pages: it accepts raw URLs (no need to pre-track them). Required: request body BulkInsertCitationTrackedRequest — - project_id, - item_type: clean_uri to track raw URLs (most common), or citation_id to track existing citations by id, - items: the URLs (for clean_uri) or citation ids (for citation_id), - portfolio_metadata (optional): set portfolio_name alone to create a new portfolio and attach the pages, or set portfolio_id + portfolio_name to attach to an existing portfolio. Response: BulkInsertCitationTrackedResponse with per-item tracking status.
update_fact_status
ChatGPTBulk-update the status of specific facts by id. Use this to accept AI-suggested facts (status: APPROVED) or reject them (status: DISCARDED). Get the fact_ids to pass here from get_facts's suggested section. Example: "Accept these 3 suggested facts." (pass their ids with status: APPROVED) Required: project_id (path), request body with fact_ids (list of UUIDs) and status (APPROVED or DISCARDED). Response: FactsMutationResponse — updated_facts count and the resulting facts (FactSummary list).
update_prompt
ChatGPTChange a tracked prompt's topic, tags, prompt type or target. The prompt text itself cannot be changed; to reword a prompt, create a new one with create_prompt. Example: "Move prompt X under the 'CRM Tools' topic and tag it 'high-priority'." Required: project_id, query_id (the prompt's id, from get_all_prompts). Optional (omitted fields are left unchanged): - topic_id: move the prompt to this topic. - tag_ids: the full list of tags the prompt should have; replaces its current tags. - prompt_type: branded, non_branded or branded_and_non_branded. - target: {prompt_target_id} of an existing persona, intent-stage or locality target; replaces the current target, and null clears it. Response: the updated prompt.
update_tag
ChatGPTRename a tag, change its colour, or both. Example: "Rename my 'p1' tag to 'high-priority' and set the colour to blue." Required: project_id (path), tag_id (path), request body containing at least one of new_name or color. A 400 is returned if both are omitted. Response: the updated GeoPresenceTagsOutput.
update_topic
ChatGPTRename an existing topic. Example: "Rename topic 'AI Coding Tools' to 'AI Developer Tools'." Required: project_id (path), topic_id (path), request body with the new topic name. Response: the updated TopicOutput.
