Profound

Get the status (and outputs if terminal) of a previously triggered run. Terminal statuses: `succeeded` (outputs populated), `failed` (error populated), `cancelled`, `skipped`. Non-terminal: `queued`, `running`. Poll at most every ~2 seconds. The result carries `steps`: an ordered trace of what the run did — one entry per node that ran, with its kind, human title, status, timing, and (for a conditional) which branch it took. It also carries `narration`: a ready-to-read plain-language summary of that journey. Relay `narration` to the user so they see what the run actually did, not just the final `outputs`. Set `verbose=True` only when they want to inspect each step's raw output payload (a heavier response); the step list and narration always ship. The result's `hint` names the next step for you — poll again while the run is unfinished, or (on a default read of a finished run) re-call with `verbose=True` to see each step's output.

Return information about the authenticated principal — user ID, granted scopes, and the Profound entitlements visible to this session. Use to confirm who Claude is acting as before calling list_* or get_*_report tools. To see the organizations in scope — and to get the ``org_id`` those tools take — call ``list_organizations``.

Tracked categories for an org (e.g. "Banking — Canada"). ``org_id`` is the organization id from ``list_organizations``. Required precursor for tools that take a ``category_id`` argument — this tool is how the LLM discovers the categories available.

Tags defined in a category. Pass the returned tag IDs to ``list_prompts`` via ``tag_ids`` to filter prompts.

Topics defined in a category.

Domains tracked for an org. Use as the input source for the ``domain`` argument of ``get_bots_report`` / ``get_referrals_report``. ``org_id`` is the organization id from ``list_organizations``.

Knowledge bases accessible to the caller (resolver for search). Returns one row per knowledge base with ``id``, ``name``, ``slug``, ``description``, and ``created_at``. The KB ``id`` is the input to ``search_knowledge_base``. Use this when the user wants to enumerate the knowledge bases configured for their account ("what KBs do we have?"). Do NOT use this when the user wants to look up content INSIDE a KB — that's ``search_knowledge_base``. If you are unsure what a Profound knowledge base is or what belongs in one, read the ``knowledge-base`` glossary term and the knowledge base guide resource before acting.

Semantic / full-text search inside a single knowledge base. Returns ranked hits with ``id`` (document or chunk path), ``score`` (relevance), ``content`` (the matched text), and ``metadata`` — including ``folder_path`` (the document's folder; empty string means the KB root), ``source_filename``, and ``filetype``. Useful for grounding an answer in the caller's curated documents, and the only way to discover a KB's existing folder structure. Use this when the user wants to look up CONTENT inside a known KB — "search our docs for X", "what does our handbook say about Y". Do NOT use this when the user wants to enumerate KBs — that's ``list_knowledge_bases``. Pass the KB's UUID directly when you have it (e.g. from a prior ``list_knowledge_bases`` call); pass the KB's name or slug and the tool will resolve it for you. If you are unsure what a Profound knowledge base is or what belongs in one, read the ``knowledge-base`` glossary term and the knowledge base guide resource before acting.

Report that Profound's MCP tools could not fully satisfy the user's request. Call this when you hit a wall: an existing tool fell short of what the user needed, or the user wanted something the Profound product can do but no MCP tool exposes yet. This is how gaps get surfaced to the Profound team for triage — so the signal you provide directly shapes what gets built next. Before calling, work through these four questions — they map one-to-one to the fields below, and the quality of your answers is the whole value of the submission: 1. What did the user *originally* ask for — their real goal, not the narrowed-down version you settled for? 2. What was actually possible with the tools available, and what was NOT? What did you end up doing instead, if anything? 3. Is this a case of an existing tool needing to do more/better (`capability_improvement`), or a capability that exists in Profound with no MCP tool at all (`new_tool_parity`)? 4. How much did this gap actually matter to the user's task (`High` / `Medium` / `Low`)? Answer from your read of the conversation first. If the user is in the loop and one of these is genuinely unclear — you're guessing at their real goal, or unsure how much the gap mattered — ask them one brief clarifying question before submitting. This is optional and best-effort: never block on it, never require a reply, and if the client has no user to ask (headless/automated), just infer and submit. A single high-signal submission with an inferred detail beats stalling. Write `intent` and `outcome` as concrete, situation-specific prose — not boilerplate. Generic filler ("user wanted data, tool didn't have it") is worthless for triage; name the specific data, action, or capability. Good feedback anchors the gap to real Profound capabilities (a report, metric, tool, or UI feature that exists); a vague product wish that ties to nothing is not actionable.

List the integrations your org has connected, to fill a node's `integration_id`. Hub-backed nodes (Google Search Console, WordPress, Google Docs, Gmail, OpenAI Ads) require an `integration_id` — the id of a connection your org made in the Profound web app. This tool returns those connections so you can fill the field with a real id. Call it whenever a graph you are building uses a hub-backed node, before you try to publish. Each connection carries `integration_id`, `provider`, `account`, `label`, `status`, and `level` (`org` or `user`). `account` is the connected account as the provider reports it — a Google address, a WordPress site URL — and is the field that tells two connections of one provider apart. `label` is usually just the connector's name, repeated identically across every row, so never ask a user to choose by it; fall back to it only when `account` is empty. Pass `provider` to narrow to one family, using the exact slug the node declares: `google_search_console`, `wordpress`, `google_docs`, `google_gmail`, or `openai_ads`. Because those are the hub-backed families, an empty list for one of them is a definitive "not connected" — a normal answer, not an error and not a wrong slug; tell the user to connect it in the Profound web app first. Google Docs has no connection of its own — it rides the org's Google Drive connection, so a `google_docs` node is satisfied by a row whose `provider` reads `google_drive`. Ask for `google_docs` anyway; that row is the right one to bind the node to. `google_sheets` resolves to that same Drive row, but there are no Google Sheets nodes to bind it to — a row coming back for it is the Drive connection, never evidence that a Sheets step is available, so do not offer the user one on the strength of it. Choosing which id to write — follow these rules exactly: - Only ever write an `integration_id` this tool returned. NEVER invent one and NEVER copy one from another agent — a wrong id binds the node to an account that is not yours and fails at run time. - If exactly one connection exists for the provider and the field is empty, fill it and tell the user which `account` you used. - If more than one connection exists, always ask the user to choose by `account` — never pick for them. Binding the wrong one is quiet: the graph publishes and the run succeeds, against somebody else's account. - Leaving `integration_id` empty is better than a made-up placeholder: an empty field is a clean "not chosen yet", while a truthy placeholder looks valid and suppresses the builder's own account picker. Returns only active connections. A connection is only usable if its `status` is `active`; do not bind a node to a broken one.

Add ONE new document (inline markdown text) to a knowledge base. Purely additive: this creates a new document and never overwrites one. Revision and deletion are UI-only — when the user wants to change or remove an existing document, direct them to the Profound platform. Typical uses: uploading FactCheck brand source documents during onboarding, and ingesting brand guidelines / product specs / campaign briefs that agents read as context. BEFORE submitting, read the knowledge base guide resource: classify the content's intent (brand-facts, product-spec, faq, policy, or brief), shape ``text`` with the matching markdown + YAML frontmatter template from the guide's templates subresource, and check it clears the guide's minimum bar. The tool accepts inline text only — if you have a URL, fetch and read the content yourself, then submit the resulting markdown. If you are unsure what a Profound knowledge base is, read the ``knowledge-base`` glossary term first. Defaults to preview=True: nothing is ingested; the response echoes the plan (resolved KB, name, folder, text size) plus a non-blocking ``quality_advisory``. Pass preview=False to apply. A duplicate document name is rejected upstream — the response ``hint`` then says to retry under a versioned name (e.g. 'brand-guidelines-v2'). After a successful apply, verify with ``search_knowledge_base`` (content may take a moment to index). NOT idempotent: each apply creates a new document.

AI engines (ChatGPT, Gemini, Perplexity, etc.) the caller has visibility into. The upstream endpoint does not accept an org filter.

List organizations available to the authenticated principal. Wraps the Profound SDK's `organizations.list()`. Returns the sandbox-seeded list when ``MCP_SANDBOX_ENABLED=true``.

List a category's projects as thin triage rows (in backend order). A project is a goal (e.g. "reach visibility rank 3 on Dental Insurance") with a measurable target and a set of tasks. Each row is lightweight — ``title``, ``status``, ``summary``, ``topics``/``task_types``, ``new_task_count``, ``updated_at`` — enough to spot which project is relevant. The **goal, resolved identity, and the tasks themselves are NOT on a list row**: call ``get_project`` to step into one and see its goal and its tasks (each with its own impact). There is no org-wide "list every Project" mode; resolve the target category first with ``list_categories``. Use ``status`` to narrow to ``suggested`` (proposed, not yet committed), ``tracked`` (actively measured), or ``retired`` (archived); omit for all. Paginate with ``offset`` (the backend vends no total count). New to Projects? Read the Profound Projects guide resource for the concepts (a project's goal/``measurement``, the resolved ``identity`` block, task types, and the impact rubric) in full.

Get one project: its goal, why it matters, and its full task list. Returns the goal (``title`` + simplified ``measurement``), the resolved ``identity`` (asset + topics + tracked field) — use it to pull live metrics via ``get_visibility_report`` / ``get_citations_report`` to see where you stand vs. the target — and the ordered ``tasks`` **fully hydrated** (each with its executor ``brief``); there is no separate task-fetch step. The Profound Projects guide resource defines the concepts (``measurement``, ``identity``, task types, impact) in full. The result carries a readable markdown rendering of the project (goal, verify steps, tasks) alongside the structured data.

Get one project's lifecycle and live-generation status. Project status states: ``suggested`` means generated/proposed but not yet committed as tracked work; ``tracked`` means active work being measured against the Project goal; ``retired`` means archived/no longer active. ``live_generation`` appears only when the backend reports a current or recent generation event for the Project. Live generation states: ``queued`` is waiting to start, ``running`` is in progress, ``completed`` means the Project is generated, and ``failed`` means generation failed (check ``live_generation.error`` when present). The result includes a Project deeplink when the ids are known. When generation is ``completed``, call ``get_project`` to inspect the generated goal and tasks.

Preview or kick off a fire-and-forget project generation run in a category. Before calling, run a short interview: what kind of work should this produce (``work_types``), what topic/target is involved, which region/persona/platform matters, what context is available, and what the user wants to do with the output. ``focus`` is required: one concrete sentence naming the Project the user wants generated. Put longer steering detail in ``context``: why now, audience/persona, market constraints, competitors, source-material summaries, examples to emulate or avoid, and success criteria. For every Projects preview/apply write, call with ``preview=True`` first, show the returned plan/diff to the user, then stop. Call with ``preview=False`` only after a separate user reply explicitly confirms that preview. Do not preview and apply in the same assistant turn. ``work_types`` is controlled vocabulary for the kind of work the generated Project should produce: ``publish`` (new owned pages), ``refresh`` (improve existing owned pages), ``earned`` (third-party inclusion/outreach), ``creative`` (campaigns, tools, research, videos, benchmarks), and ``social`` (distribution or YouTube/social roundup work). Defaults to ``preview=True``: this returns the normalized generation plan without creating anything. Pass ``preview=False`` only after that explicit confirmation. Generation runs ~10 minutes: apply returns a ``project_id`` and Project link; poll ``get_project_status`` with ``project_id`` and ``category_id`` until it completes or fails.

Preview or archive (retire) a project — set it aside without deleting it. Non-destructive and reversible: the project and its history are preserved, just marked ``retired``. Defaults to ``preview=True``: this returns the archive plan without changing the project. Ask the user briefly why they're archiving (e.g. not relevant, already done, wrong target, superseded) and pass it as ``reason``. Always call with ``preview=True`` first, show the returned diff to the user, then stop. Call with ``preview=False`` only after a separate user reply explicitly confirms that preview. Do not preview and apply in the same assistant turn.

Preview or add a task ("play") to a project. The ``brief`` is a structured, per-``type`` object (its required keys depend on the type). Prose must avoid raw citation counts (use ranks / relative descriptors) and bare decimals (use ``33%``, ``#2``, ``+1pp``); violations are rejected. Defaults to ``preview=True``: this returns the normalized task plan without changing the project. Always call with ``preview=True`` first, show the returned plan to the user, then stop. Call with ``preview=False`` only after a separate user reply explicitly confirms that preview. Do not preview and apply in the same assistant turn.

Preview or update fields on an existing task (send only what changes). A supplied ``brief`` fully replaces the structured brief. Same prose rules as ``create_project_task`` apply. Defaults to ``preview=True``: this returns the proposed change without mutation. Always call with ``preview=True`` first, show the returned diff to the user, then stop. Call with ``preview=False`` only after a separate user reply explicitly confirms that preview. Do not preview and apply in the same assistant turn.

Preview or transition a task's status. Status values are ``not_started`` / ``in_progress`` / ``done`` / ``abandoned``. Defaults to ``preview=True``: this returns the proposed transition without mutation. This is not a deletion/removal tool. ``abandoned`` keeps the task on the Project as shelved work; use it only when the user asks to shelve, stop, or mark a task abandoned. If the user asks to delete/remove a task and ``delete_project_task`` is not available, tell them deletion is out of scope instead of using this tool as a substitute. Always call with ``preview=True`` first, show the returned diff to the user, then stop. Call with ``preview=False`` only after a separate user reply explicitly confirms that preview. Do not preview and apply in the same assistant turn.

Create one or more prompts in a category. Each prompt requires `prompt` (text), `topic`, `platforms`, and `regions`. Topics and tags referenced by name are AUTO-CREATED if they don't exist — the result's `topics_created` and `tags_created` count those. Defaults to preview=True (no changes persisted; response shows what WOULD happen). Pass preview=False to apply. Each apply call creates NEW prompts — calling twice with the same input creates duplicates (NOT idempotent).

Update one or more existing prompts. Each input requires `id` plus the fields to change. Collection fields (tags, regions, platforms, personas) REPLACE the entire set when provided — they don't merge. `None` = leave alone; `[]` = clear; non-empty list = replace. Preview returns a field-by-field diff (old → new for scalars, added/removed for collections) per prompt. Idempotent: same input applied twice yields the same state. Defaults to preview=True. Pass preview=False to apply.

Bulk activate, disable, or DELETE prompts. status='deleted' permanently deletes prompts AND their historical data. status='disabled' stops future runs but preserves history. status='active' resumes daily runs. There is no separate delete endpoint — deletion is achieved via this tool with status='deleted'. Prompts already in the target status are skipped (idempotent). Defaults to preview=True. Pass preview=False to apply.

Prompts configured in a category, optionally filtered by status/tags/topics. Status accepts ``active``, ``disabled``, or ``all`` (default). Include filters (``tag_ids``, ``topic_ids``) are pushed to the upstream SDK when ``combine='AND'`` (default); ``exclude_tag_ids``, ``exclude_topic_ids``, and ``combine='OR'`` are applied client-side after the fetch. Pass ``cursor`` from a previous response's ``next_cursor`` to page forward. LIMITATIONS: Exclude filters and ``combine='OR'`` are applied client-side after the upstream fetch; for very large categories this can be slow.

Observed AI-engine responses for prompts in a category over a window. Each row carries ``prompt_id``, ``country``, the answering model, the response text, and the observation timestamp. Pass ``prompt_id`` to restrict results to a single prompt. Pass ``country`` or ``region`` (name or UUID; a list means any of those values) for country-level segmentation. Use ``limit``/``offset`` for pagination (default 100 rows, upstream cap 50,000).

Regions (US, UK, CA, etc.) available to the caller. ``org_id`` is optional: omit it to return regions across all organizations the caller belongs to. When set, it is the organization id from ``list_organizations``.

Visibility report for a category over a date window. The response is the v2 shape: an `info` block (query metadata) plus keyed `data` rows. Dates are Eastern Time calendar dates and both start_date and end_date are inclusive (start_date=2026-04-01, end_date=2026-04-30 covers all of April 2026). Metrics (default `visibility_score`): - `visibility_score` — share of answers mentioning the asset. - `share_of_voice` — proportion of all mentions. - `average_position` — mean rank when mentioned (lower is better). MCP returns raw decimals; multiply visibility_score by 100 for the web UI's percentage (0.42 → 42%). Brand scoping: - Every row carries an `asset` (`{name, owned}`), and `asset` is ALWAYS an implicit grouping key: results are one row per asset x group_by bucket, not one row per bucket. Under scope="all" (or with multiple tracked brands) expect a row per asset for each group_by value — sum by `asset.name` yourself for a single row per bucket. Use `assets="YourBrand"` (or a list) to target specific brands, or `scope` to choose `owned` (your tracked brands, the default) vs `all` (includes competitors). Grouping: - `group_by` buckets results server-side. Supported: date, model, topic, region, prompt, persona. Add `date` for a time series. Filtering: - Convenience kwargs (values matched by name): topic_filter=["Personal banking"], tag_filter, region_filter, model_filter=["<model_id-uuid>"] (UUID from list_models), persona_filter=["<persona_id-uuid>"] (UUID). - For advanced conditions pass a raw v2 `filter` tree: filter={"field": "topic", "op": "is", "value": "Personal banking"} filter={"and": [ {...leaf...}, {...leaf...} ]} Convenience kwargs and `filter` are merged under `and`. - Filter values are NEVER captured by analytics. - A filter that matches no tracked data (e.g. a `region_filter` for a region this category doesn't track) returns zero-valued rows, NOT an error — treat all-zero results as "no data for that filter", not a bad request. Pagination: - `limit` caps how many top-level groups come back per page — upstream default 10, max 50. It is NOT a total-row cap: every row is also split per asset (see Brand scoping) and per additional group_by dimension, so a grouped query returns more rows than `limit` (e.g. group_by=["topic"] with limit=10 and two tracked assets is ~10 x 2 = 20 rows; add `date` over a week and it fans out further). - If `info.next_cursor` is present, pass it as `cursor` to fetch the next page with the same query shape. Related tools: - `get_citations_report` — which sources/domains drive that visibility. - `get_sentiment_report` — the tone behind the visible mentions.

Citations report for a category over a date window. The response is the v2 shape: an `info` block (query metadata) plus keyed `data` rows, always ranked most-cited first. Dates are Eastern Time calendar dates and both start_date and end_date are inclusive. Default shape — cited domains: - A citation is a cited DOMAIN, so with NO `group_by` each row is one cited domain: {domain, rank, count, citation_share}, ranked most-cited first (rank 1 = most cited). "Which sites / sources / domains do AI engines cite most" needs no group_by at all — just category_id + a date window. Metrics (default `count`, `citation_share`): - `count` — raw citation frequency. - `citation_share` — share averaged per AI model (comparable across models). - `rank` is on every row (1 = most cited); `first_cited_at` is pages-only. Scope: - `scope="all"` (default) covers every domain; `scope="owned"` narrows to your owned domains. Grouping: - Pass `group_by` to re-bucket results server-side along a different axis than the by-domain default. Supported: page, date, model, topic, region, persona, prompt. Use `group_by=["page"]` for one row per cited page URL (finer than domain); add `date` for a time series; use `topic`/`model`/etc. to break citations down along that axis. - IMPORTANT: `group_by=["page"]` is page-level and CANNOT be combined with `scope="owned"` or with `domain_filter` — the backend rejects it (those narrow to a domain, which is incompatible with per-page rows). To scope to your domains, drop `page` from `group_by` (the default by-domain shape, or any non-page grouping, works with `scope="owned"` / `domain_filter`). Filtering: - Convenience kwargs (values matched by name): domain_filter=["acmebrands.com"] — subdomain-aware domain match page_filter=["https://acmebrands.com/pricing"] citation_category_filter=["owned"] — owned/competition/social/… analysis_type_filter=["visibility"] — visibility/sentiment/factcheck/all topic_filter, region_filter, model_filter=["<model_id-uuid>"], persona_filter=["<persona_id-uuid>"] - For advanced conditions pass a raw v2 `filter` tree: filter={"field": "domain", "op": "is", "value": "acmebrands.com"} filter={"and": [ {...leaf...}, {...leaf...} ]} Convenience kwargs and `filter` are merged under `and`. - Filter values are NEVER captured by analytics — only a boolean `had_filters` flag and the field names are emitted to telemetry. Pagination: - `limit` caps how many top-level groups (e.g. cited pages/domains) come back per page — upstream default 10, max 50. It is NOT a total-row cap: each group also expands across every other group_by dimension, so group_by=["page","date"] with limit=10 over a 7-day window can return up to ~10 x 7 = 70 rows. Groups still come back ranked most-cited first. - If `info.next_cursor` is present, pass it as `cursor` to fetch the next page with the same query shape. Related tools: - `get_visibility_report` — how that citation footprint maps to brand visibility. - `compare_owned_domain_citations` — roll up citation share across a set of owned domains grouped into brand entities.

Visibility report for a category over a date window. Default metric: visibility_score. Supported metrics include visibility_score, share_of_voice, mentions_count, executions, average_position. Useful dimensions: date, region, topic, model, prompt, tag, persona, asset_name. Important visibility_score semantics: - Units: MCP returns raw decimal values. Multiply by 100 to match the web platform's percentage display. Example: a brand-scoped visibility_score of 0.42 means 42% visibility in the web UI. - Brand scoping: if you do not filter to a brand/asset or include asset_name as a dimension, visibility_score is summed across every tracked brand/asset in the category. These category-wide sums can exceed 1.0 (for example, 3.57 means 357 percentage-points across tracked assets, not 357% for one brand). - Single-brand pattern: pass filters=[{"field": "asset_name", "operator": "is", "value": "YourBrandName"}] or asset_filter="YourBrandName". Add asset_name to dimensions with topic when you want per-topic-per-brand rows: dimensions=["topic", "asset_name"]. - Date windows are half-open: start_date is inclusive and end_date is exclusive. To include all of April 2026, use start_date=2026-04-01 and end_date=2026-05-01; end_date=2026-04-30 excludes April 30. Filtering (PRD-007): - Use convenience kwargs for the most common filters: topic_filter=["Personal banking"] — narrow to specific topics model_filter=["<model_id-uuid>"] — single AI model (UUID from list_models; display names like "ChatGPT" are NOT accepted) persona_filter=["<persona_id-uuid>"] — single persona (UUID only; SDK has no persona_name field) tag_filter, region_filter, asset_filter - For advanced filters not covered by convenience kwargs, pass the raw `filters` list directly: filters=[{"field": "topic_name", "operator": "is", "value": "Personal banking"}] Convenience kwargs and `filters` are merged. - Filter values are NEVER captured by analytics. Top-N queries with `limit`: - `limit=10` caps the response to 10 rows (server-side cap, not pagination). When `limit` is set, `next_cursor` is always None — no follow-up call needed. `truncated` reflects whether more rows existed beyond the cap (e.g. `total_rows=1000, returned_rows=10, truncated=true`). Pagination: - Default page_size is 500 (covers most interactive queries without truncating). Maximum is 10000. - If `truncated=true` in the response, either: (a) Follow the `hint` and reformulate with narrower dimensions (preferred — server-side aggregation is faster than client-side filtering). (b) Paginate by passing the returned `next_cursor` back in. Each page takes ~6s (p50) - 14s (p99); stay within your client's tool-call timeout budget. (c) Raise page_size up to 10000 for export-scale queries. - `page_size` only affects the first page; when `cursor` is set, the size encoded in the cursor wins. Version note: this is the v1 (legacy positional-row) tool. A newer version with a richer v2 `info`/`data` response shape — recursive `filter` trees, `group_by`, and `scope`/`assets` scoping — is available at the bare tool name `get_visibility_report`. New integrations should prefer `get_visibility_report`.

Citations report for a category over a date window. Default metrics: count, citation_share. Useful dimensions: hostname, path, root_domain, url, model, topic, prompt, tag, persona. Filtering (PRD-007): - Use convenience kwargs for the most common filters. These are translated to structured filter dicts automatically: root_domain_filter=["acmebrands.com"] — show only your brand's citations hostname_filter=["blog.acmebrands.com"] — narrow to a specific hostname model_filter=["<model_id-uuid>"] — single AI model (UUID from list_models; display names are NOT accepted) persona_filter=["<persona_id-uuid>"] — single persona (UUID only; SDK has no persona_name field) topic_filter, tag_filter, region_filter, citation_category_filter — other supported dimensions - For advanced filters not covered by the convenience kwargs, pass the raw `filters` list directly: filters=[{"field": "root_domain", "operator": "is", "value": "acmebrands.com"}] filters=[{"field": "root_domain", "operator": "in", "value": ["a.com", "b.com"]}] Convenience kwargs and `filters` are merged — both can be used together. - Filters on dimensional fields (root_domain, hostname, etc.) require the corresponding dimension to be in `dimensions`. E.g. `root_domain_filter=["acmebrands.com"]` must be paired with `dimensions=["root_domain"]` — the API returns 422 otherwise. - Filter values are NEVER captured by analytics — only a boolean `had_filters` flag and the field names are emitted to telemetry. Dimensions vs filters: - `dimensions` controls server-side aggregation (grouping): pass `dimensions=["root_domain"]` to get one row per domain across all citations. This is the right choice for "show me all cited domains". - `filters` / convenience kwargs scope the query to a subset of data: `root_domain_filter=["acmebrands.com"]` returns only rows where root_domain is acmebrands.com. This is the right choice for "show me only my brand's citations". Top-N queries with `limit`: - `limit=10` caps the response to 10 rows (server-side cap, not pagination). Use this for "show me the top 10 most-cited domains" — it's faster than fetching a full page and slicing client-side. - When `limit` is set, `next_cursor` is always None — no follow-up call needed. `truncated` reflects whether more rows existed beyond the cap (e.g. `total_rows=26000, returned_rows=10, truncated=true` means there are 26k cited domains but you asked for the top 10). - `limit` and `cursor`/`page_size` are independent: cursor paginates through the full dataset; limit caps the total rows returned. Pagination: - Default page_size is 500 (covers most interactive queries without truncating). Maximum is 10000. - If `truncated=true` in the response, either: (a) Follow the `hint` and reformulate with narrower dimensions (preferred — server-side aggregation is faster than client-side filtering). (b) Paginate by passing the returned `next_cursor` back in. Each page takes ~6s (p50) - 14s (p99); stay within your client's tool-call timeout budget. (c) Raise page_size up to 10000 for export-scale queries. - `page_size` only affects the first page; when `cursor` is set, the size encoded in the cursor wins. Related tools: - `get_visibility_report` — how that citation footprint maps to brand visibility. - `compare_owned_domain_citations` — roll up citation share across owned domains. Version note: this is the v1 (legacy positional-row) tool. A newer version with a richer v2 `info`/`data` response shape — recursive `filter` trees, `group_by`, and `scope` scoping — is available at the bare tool name `get_citations_report`. New integrations should prefer `get_citations_report`.

Sentiment report for one brand/asset. The response contains an `info` block plus keyed `data` rows. Dates are Eastern Time calendar dates and both start_date and end_date are inclusive. Required scoping: - `category_id` selects the Profound category. - `asset` is the brand or competitor name to analyze. It is text, not an asset filter tree. Metrics are chosen automatically: - Aggregate rows return positive_sentiment and negative_sentiment. - Theme/claim driver rows also return occurrence, the percentage of relevant AI responses where that sentiment theme or claim appears. Grouping: - Use `group_by` for server-side buckets. Supported values are date, model, topic, region, prompt, persona, tag, theme, claim. - At most two non-date groupings are allowed; date may be added for a time series. Internal run and competitor groupings are intentionally not exposed. Filtering: - Use `theme` and/or `claim` for exact-match drilldowns. They are combined internally as an AND filter and occurrence is returned automatically. - Filter values are never captured by analytics. Sorting: - Theme/claim driver views are sorted internally by occurrence descending. Other views are sorted internally by positive sentiment descending. Pagination: - `limit` is the page size (default upstream: 10, max: 50). - If `info.next_cursor` is present, pass it as `cursor` to fetch the next page with the same query shape.

FactCheck score report for one category. Use this for FactCheck score, trend, accurate/inaccurate count, or breakdown questions. Required scoping: - `category_id` selects the Profound category. - Dates are Eastern Time calendar dates and both `start_date` and `end_date` are inclusive. - There is no `asset` parameter. FactCheck is category-scoped. Grouping: - Empty `group_by` returns the headline score. - Supported values are date, model, region, persona, prompt, topic, tag, citation, and theme. - Use `["date"]` for a daily series, one dim for a breakdown, and up to two dims for a multi-dimensional breakdown. - `citation` can only be grouped on its own. Filtering: - Exact-match shortcuts are `model`, `topic`, `region`, `persona`, `prompt`, and `tag`; each accepts a string or list of strings. - `topic` must be an exact topic name. If uncertain, call list_topics for the category before filtering instead of guessing a topic label. - `topic_negate=True` negates only the topic filter. - Raw filter trees are intentionally not exposed. Metrics and pagination: - Rows always contain `accuracy`, `accurate`, and `inaccurate`. - `limit` is the page size (default upstream: 100, max: 100). - If `info.next_cursor` is present, pass it back as `cursor` with the same query shape to fetch the next page.

FactCheck inaccurate-claims report for one category. Use this when the user asks which inaccurate claims appeared, why they are inaccurate, which models repeated them, or what evidence/citation sources explain a claim. Required scoping: - `category_id` selects the Profound category. - Dates are Eastern Time calendar dates and both `start_date` and `end_date` are inclusive. - There is no `asset` parameter. FactCheck claims are category-scoped. Grouping: - Empty `group_by` returns a flat paginated list of claim clusters. - Supported values are model, region, persona, prompt, topic, tag, and theme. - At most one grouping dimension is allowed. - `date`, `citation`, and `claim` are not claim groupings. - `group_by=["tag"]` cannot be combined with a tag filter. Filtering: - Exact-match shortcuts are `model`, `topic`, `region`, `persona`, `prompt`, and `tag`; each accepts a string or list of strings. - `topic` must be an exact topic name. If uncertain, call list_topics for the category before filtering instead of guessing a topic label. - `topic_negate=True` negates only the topic filter. - Raw filter trees are intentionally not exposed. Enrichment and pagination: - Claim rows always contain `cluster_id`, `claim`, and `occurrence`. - `occurrence` is the response-share percentage for the claim cluster. - `include` may request theme, reasoning, models, evidence, and citation_sources. - `citation_sources` can be combined with theme, reasoning, evidence, and models in one ungrouped call; it cannot be requested when `group_by` is present. - `citation_sources` is slower because it enriches each claim with cited pages, so when you request it `limit` must be 5 or less. Values above 5 are rejected with an error, not silently clamped. - For broad cited-page mapping, stop after the top claim clusters or about 10-15 unique high-impact cited pages unless the user asks for an exhaustive export. - For score, trend, or accurate/inaccurate count summaries, use get_factcheck_report instead. - `limit` is the page size (default upstream: 25, max: 100 without `citation_sources`; max 5 when `include` contains `citation_sources`). - If `info.next_cursor` is present, pass it back as `cursor` with the same query shape to fetch the next page.

Bot-traffic report for a domain over a date window. Default metrics: count, citations. Choosing ``dimensions``: - For "which AI vendor crawls us the most" questions, use ``dimensions=["bot_provider"]`` — returns ~5-10 vendor rows (OpenAI, Anthropic, Google, Perplexity, ...) with crawls already aggregated server-side. This is the default you almost always want. - Use ``dimensions=["bot_name"]`` only when the user explicitly asks for individual bots (e.g. "GPTBot vs ChatGPT-User"). Returns 30+ per-bot rows that you would otherwise have to group client-side. - Add ``"date"`` for a time series. ``"bot_type"`` partitions by crawler category. ``domain`` must match a value from ``list_domains`` exactly. Domains are tracked at the hostname level — ``www.example.com`` and ``example.com`` are distinct entries. If the user gives a bare domain and you get no rows, call ``list_domains`` and pick the matching row (often the one with the most traffic). Pass ``organization_id`` if your user has multiple orgs and the domain is ambiguous. Filtering (PRD-007): - Use convenience kwargs for the most common filters: bot_provider_filter=["openai"] — single provider; lowercase vendor enum (e.g. openai, anthropic, perplexity, google). Display-name "OpenAI" returns 422. bot_name_filter=["GPTBot"] — individual bot bot_type_filter=["ai_assistant"] — bot category (one of: ai_assistant, ai_training, index, ai_agent) - For advanced filters, pass the raw `filters` list directly. - Filter values are NEVER captured by analytics. Top-N queries with `limit`: - `limit=5` caps the response to 5 rows (server-side cap, not pagination). When `limit` is set, `next_cursor` is always None — no follow-up call needed. `truncated` reflects whether more rows existed beyond the cap. Pagination: - Default page_size is 500 (covers most interactive queries without truncating). Maximum is 10000. - If `truncated=true` in the response, either: (a) Follow the `hint` and reformulate with narrower dimensions (preferred — server-side aggregation is faster than client-side filtering). (b) Paginate by passing the returned `next_cursor` back in. Each page takes ~6s (p50) - 14s (p99); stay within your client's tool-call timeout budget. (c) Raise page_size up to 10000 for export-scale queries. - `page_size` only affects the first page; when `cursor` is set, the size encoded in the cursor wins.

Referral-traffic report for a domain over a date window. Default metric: visits. Choosing ``dimensions``: - For "which AI vendor sends the most referral traffic" or "compare crawls to visits by vendor" questions, use ``dimensions=["referral_type"]`` — returns a handful of vendor / category rows aggregated server-side. Pair with ``get_bots_report(dimensions=["bot_provider"])`` for crawl-to-visit comparisons; both dimensions align at the vendor level. - Use ``dimensions=["referral_source"]`` only when the user wants individual referrer hosts (e.g. ``chat.openai.com`` vs ``perplexity.ai``). - Add ``"date"`` for a time series. ``domain`` must match a value from ``list_domains`` exactly. Domains are tracked at the hostname level — ``www.example.com`` and ``example.com`` are distinct entries. If the user gives a bare domain and you get no rows, call ``list_domains`` and pick the matching row (often the one with the most traffic). Pass ``organization_id`` if your user has multiple orgs and the domain is ambiguous. Filtering (PRD-007): - Use convenience kwargs for the most common filters: referral_source_filter=["openai"] — referrer vendor; lowercase vendor enum (e.g. openai, anthropic, perplexity). For individual hostnames like "chat.openai.com", use dimensions=["referral_source"] instead — the filter takes vendor enums, not hostnames. referral_type_filter=["referer"] — referral category (one of: internal, referer, utm, none) - For advanced filters, pass the raw `filters` list directly. - Filter values are NEVER captured by analytics. Top-N queries with `limit`: - `limit=5` caps the response to 5 rows (server-side cap, not pagination). When `limit` is set, `next_cursor` is always None — no follow-up call needed. `truncated` reflects whether more rows existed beyond the cap. Pagination: - Default page_size is 500 (covers most interactive queries without truncating). Maximum is 10000. - If `truncated=true` in the response, either: (a) Follow the `hint` and reformulate with narrower dimensions (preferred — server-side aggregation is faster than client-side filtering). (b) Paginate by passing the returned `next_cursor` back in. Each page takes ~6s (p50) - 14s (p99); stay within your client's tool-call timeout budget. (c) Raise page_size up to 10000 for export-scale queries. - `page_size` only affects the first page; when `cursor` is set, the size encoded in the cursor wins.

Brand visibility inside AI shopping results for a category. How often each brand appears when an AI engine returns a shopping or product-comparison surface — the shopping counterpart to `get_visibility_report`, which measures visibility across all answers. Response is the v2 shape: an `info` block (query metadata) plus keyed `data` rows. Dates are Eastern Time calendar dates and both start_date and end_date are inclusive. Use this when the user asks about brand presence in shopping, product, or buying-intent results. Use `get_shopping_products_report` when the question is about specific products rather than the brand overall, and `get_visibility_report` when it isn't shopping-specific at all. Metrics (all three returned by default): - `visibility_score` — share of shopping answers mentioning the brand. - `average_position` — mean rank when mentioned (lower is better). - `visibility_rank` — the brand's rank against the others (1 = best). Scores are raw decimals; multiply visibility_score by 100 for the web UI's percentage (0.42 -> 42%). Brand scoping: - Every row carries an `asset` (`{name, owned}`), and `asset` is ALWAYS an implicit grouping key: results are one row per asset x group_by bucket, not one row per bucket. Use `assets="YourBrand"` (or a list) to target specific brands, or `scope` to choose `owned` (your tracked brands, the default) vs `all` (includes competitors). Grouping: - `group_by` buckets results server-side. Supported: date, topic, region, prompt. Add `date` for a time series. Filtering: - Convenience kwargs (values matched by name): topic_filter, region_filter, persona_filter, prompt_filter, tag_filter. Values must name something the category actually tracks — an unknown topic/region/prompt is rejected upstream, not silently ignored, so resolve names with `list_topics` / `list_regions` / `list_prompts` first if you are unsure. - For advanced conditions pass a raw v2 `filter` tree: filter={"field": "topic", "op": "is", "value": "Running shoes"} filter={"and": [ {...leaf...}, {...leaf...} ]} Convenience kwargs and `filter` are merged under `and`. - Filter values are NEVER captured by analytics. Pagination: - `limit` caps how many top-level groups come back per page — upstream default 10, max 50. It is NOT a total-row cap: rows also split per asset and per additional group_by dimension. - If `info.next_cursor` is present, pass it as `cursor` for the next page. A category with no shopping executions in the window returns zero rows — treat that as "no shopping data for this window", not an error. Check `get_shopping_trigger_rate_report` to confirm whether shopping surfaces triggered at all. The response `hint` names the next step — the drill-down grain to reach for, or, on zero rows, how to tell "no shopping surface" apart from "not present in it". Read it before deciding what to call next. Related tools: - `get_shopping_products_report` — which individual products show up. - `get_shopping_merchants_report` — which retailers carry those results. - `get_shopping_trigger_rate_report` — how often shopping triggers at all.

Individual product visibility inside AI shopping results for a category. One row per product (plus any `group_by` bucket), carrying how visible that product is, where it ranks, and its rating. Response is the v2 shape: an `info` block plus keyed `data` rows. Dates are Eastern Time calendar dates, both ends inclusive. Use this when the user asks which products surface in AI shopping answers, or how one product compares to its competitors. Use `get_shopping_brands_report` when the question is about the brand overall rather than specific SKUs. Metrics (ALL of the following are returned by default — pass `metrics` only to narrow): - `visibility_score` — share of shopping answers featuring the product. - `average_position` — mean rank when featured (lower is better). - `visibility_rank` — the product's rank against the others (1 = best). - `position1_percentage` / `position2_percentage` / `position3_percentage` / `position_above3_percentage` — how often it lands in each slot, which is how you tell "always shown, always fourth" from "sometimes shown first". - `product_rating` / `product_num_reviews` — the rating and review count AI engines are seeing for the product. Product focus: - `target_product="Acme Trail Runner"` switches to the item view: that product plus its closest competitors, which is the shape to use for "how does my product stack up?". - `include_merchants=True` inlines each product's offers (merchant name, price, url, image). Off by default because it multiplies response size; turn it on when the user asks where a product is sold or at what price. Grouping: - `group_by` supported: date, topic, prompt. Add `date` for a time series. Note there is no `region` grouping here (unlike the brands report). Filtering: - Convenience kwargs: topic_filter, region_filter, persona_filter, prompt_filter, tag_filter, plus two this report alone supports — brand_filter (one brand's products) and merchant_filter (the products one retailer surfaces). Values must name something the category tracks; an unknown value is rejected upstream rather than ignored. - For advanced conditions pass a raw v2 `filter` tree; convenience kwargs and `filter` merge under `and`. Filter values are NEVER captured by analytics. Pagination: - `limit` caps top-level groups per page — upstream default 10, max 50, and NOT a total-row cap. Follow `info.next_cursor` via `cursor`. The response `hint` names the next step, including which of the two extras above is worth adding for the question at hand. Related tools: - `get_shopping_brands_report` — brand-level rollup of the same surface. - `get_shopping_merchants_report` — which retailers carry these products.

Which retailers AI engines surface for a category's shopping results. Response is the v2 shape: an `info` block plus keyed `data` rows. Dates are Eastern Time calendar dates, both ends inclusive. Pick the `view` to match the question — each returns a different row grain and its own metrics: - `"distribution"` (default) — one row per merchant: that merchant's share of all shopping results. Answers "which retailers dominate this category?" Set `by_date=True` to get it as a time series (this view only). - `"brand_share"` — one row per merchant x brand: how each brand's presence splits within a merchant. Answers "whose products does this retailer show?" - `"top_products"` — one row per merchant x product: the products each merchant surfaces most. Answers "what does this retailer actually list?" `metrics` defaults per view, and a metric must be valid for the view you chose — distribution returns the merchant_share/merchant_visibility family, brand_share returns `brand_share` (plus `merchant_share` and `visibility_rank`), top_products returns `product_visibility`/`product_rank` (plus `merchant_visibility`). Leave it unset unless you need to narrow; an invalid pairing is rejected upstream. `info.view` echoes the resolved view so you can confirm which shape you got. Filtering: - Convenience kwargs: topic_filter, region_filter, persona_filter, prompt_filter, tag_filter. There is deliberately NO merchant/product filter — this report does not support filtering on either, so narrow by topic/region/persona/prompt/tag and read the merchant rows that come back. Values must name something the category tracks; an unknown value is rejected upstream rather than ignored. - For advanced conditions pass a raw v2 `filter` tree; convenience kwargs and `filter` merge under `and`. Filter values are NEVER captured by analytics. (Filtering by `brand` is possible via the raw tree, but ONLY in the distribution view — the other two views reject it.) Pagination: - `limit` caps top-level groups per page — upstream default 10, max 50, and NOT a total-row cap: the brand_share and top_products views expand each merchant across every brand/product. Follow `info.next_cursor` via `cursor`. The response `hint` is keyed on the view that actually came back and names the natural next cut from there. Related tools: - `get_shopping_products_report` with `include_merchants=True` — the inverse cut: per-product offers rather than per-merchant rows. - `get_shopping_brands_report` — brand visibility independent of retailer.

How often prompts make an AI engine return a shopping surface at all. The denominator behind the other three shopping reports: of all the runs in this category, what share produced a shopping or product-comparison result. Response is the v2 shape: an `info` block plus keyed `data` rows. Dates are Eastern Time calendar dates, both ends inclusive. Use this to establish whether a category has a shopping surface worth optimizing, to find which topics or prompts trigger shopping most, or to explain why another shopping report came back empty or thin. Metrics (all three returned by default): - `total_runs` — every run in the window. - `shopping_triggered_runs` — the subset that returned a shopping surface. - `trigger_rate_percentage` — the ratio of the two. DESPITE THE NAME this is a decimal fraction between 0 and 1, not a 0-100 percentage: 0.17 means 17%. Multiply by 100 to display it, exactly like `visibility_score`. It equals shopping_triggered_runs / total_runs, so you can always verify it. Grouping: - `group_by` supported: date, topic, region, persona, prompt. Group by `prompt` or `topic` for the per-prompt / per-topic trigger rate — the cut that tells you where shopping intent actually lives. Add `date` for a time series. Filtering: - Convenience kwargs: topic_filter, region_filter, persona_filter, prompt_filter, tag_filter. Values must name something the category tracks; an unknown value is rejected upstream rather than ignored. - For advanced conditions pass a raw v2 `filter` tree; convenience kwargs and `filter` merge under `and`. Filter values are NEVER captured by analytics. Pagination: - `limit` caps top-level groups per page — upstream default 10, max 50, and NOT a total-row cap. Follow `info.next_cursor` via `cursor`. The response `hint` restates the rate at display scale, flags a thin sample or a low rate (little surface to optimize), and names the drill-down worth making — read it before drawing a conclusion. Related tools: - `get_shopping_brands_report` — brand visibility within the triggered runs. - `get_shopping_products_report` — the products those runs surfaced.

List all available resources and resource templates. Returns JSON with resource metadata. Static resources have a 'uri' field, while templates have a 'uri_template' field with placeholders like {name}.

Read a resource by its URI. For static resources, provide the exact URI. For templated resources, provide the URI with template parameters filled in. Returns the resource content as a string. Binary content is base64-encoded.