# Use Cases & Examples Source: https://apidocs.writesonic.com/agents-mcp/examples Real prompts and end-to-end examples for the Writesonic Agents MCP server. Every example below is something you type to your connected assistant in plain language. The assistant picks the tools; the italic lines show the calls it makes under the hood. ## Start every session with your projects Because almost every tool is project-scoped, the assistant resolves your project first. > **You:** What can you do with my Writesonic Agents account? > > *Assistant calls `whoami` → returns your identity and projects, then works within the project you pick.* If you have several projects, name the one you mean ("in my Acme project…"). Otherwise the assistant will ask rather than guess. ## Triage your task list > **You:** How many open tasks do I have, grouped by assignee? > > *Assistant calls `query_tasks` with `view: "counts"` and `group_by: "assignee_id"`.* > **You:** Show me the high-priority tasks that aren't done yet. > > *Assistant calls `query_tasks` with `view: "list"` and a filter on priority and status.* ## Create and manage a task > **You:** Create a task "Refresh the pricing page for AI search" and assign it to me. > > *Assistant calls `create_task`, then `update_task` with `action: "assign"`.* > **You:** Move it to In Progress and add a comment with the target keywords. > > *Assistant calls `update_task` (`action: "transition_status"`) then `comment_on_task`.* ## Follow the work an agent did > **You:** What did the agent do on task ABC-123? Walk me through the steps. > > *Assistant calls `get_agent_runs` with `task_id`, then `run_progress` for the run to show each step.* ## Inspect a playbook and its runs > **You:** List my content playbooks and show the last few runs of the blog one. > > *Assistant calls `list_workflows` (`view: "list"`), then `get_workflow` (`view: "runs"`) for the matching playbook.* ## Read a grid > **You:** What columns are in my "Q3 landing pages" grid, and show the first 20 rows. > > *Assistant calls `list_grids` to find it, then `get_grid_data` (`view: "columns"` then `view: "rows"`).* ## Search your Knowledge Base and Brand Kit > **You:** What does our brand voice guide say about tone? > > *Assistant calls `get_brand_kit` for the voice section, or `search_knowledge` across your sources.* ## Pull a Pages report > **You:** How is our /pricing page doing in AI citations this month? > > *Assistant calls `get_ci_dashboard` (`view: "pages"`) to resolve the page, then `get_page_report` with the AI-citations `report_type`.* ## Chain several reads in one shot For a multi-step question, the assistant can batch the calls instead of round-tripping each one. > **You:** Give me a status snapshot: open task counts, my three most recent playbook runs, and any failing integrations. > > *Assistant uses `execute_batch` to run `query_tasks`, `get_workflow` (runs), and `list_integrations` in one request.* ## Three things to take note of * **Name your project.** Almost every tool is project-scoped, so the assistant resolves it with `whoami` first. Say which project you mean ("in my Acme project…") and it won't have to stop and ask. * **Writes always confirm first.** Only `create_task`, `update_task`, and `comment_on_task` change anything, everything else is read-only. The assistant shows you the change and asks before writing, and each write is reversible in the product. * **Batch multi-step questions.** For a question that needs several reads, ask for the whole thing in one message. The assistant chains the calls with `execute_batch` (or `execute_plan` when there are loops or conditionals) instead of round-tripping each one. ## Where to go next Every tool and its arguments Call the same tools from code # MCP Server Source: https://apidocs.writesonic.com/agents-mcp/mcp-server Connect Writesonic Agents to Claude, ChatGPT, and other MCP-compatible assistants. Manage tasks, playbooks, grids, knowledge base, and pages from chat. ## Overview The Agents MCP server lets an AI assistant work with your [Agents](/agents/overview) workspace directly from a conversation. Ask it to list your tasks, create one, inspect a playbook or grid, search your knowledge base, or pull a pages report, and it calls the right tool for you. **Server URL:** ``` https://mcp.agents.writesonic.com/mcp ``` **Agents is in beta.** Access is currently limited to selected enterprise and agency accounts. To request it, talk to your account manager or [book a demo](https://writesonic.com/?demo=open) with our sales team. This is a different server from the [GEO MCP](/mcp/mcp-server) at `mcp.writesonic.com`. The GEO server answers questions about your AI-search **visibility data**; the Agents server operates your Agents **workspace**: projects, tasks, playbooks, grids, and knowledge base. ## What You Can Do * **Manage tasks**: create tasks, query and filter them, transition status, assign owners, and comment * **Track agent work**: pull agent-run history and step-by-step progress for a task or agent * **Inspect playbooks**: browse a project's playbooks, versions, runs, and the building-block components * **Read grids**: list grids and read their columns, rows, cells, and cell run detail * **Search Knowledge Base**: run semantic search across your project's knowledge base, and read the brand kit * **Pull Pages reports**: get the page dashboard and per-page SEO, citation, funnel, traffic, and SERP reports * **See your setup**: resolve your identity and projects, list integrations, users, labels, skills, and agents * **Handle attachments**: get short-lived download URLs for task and comment attachments ## Connection Methods | Platform | How to Connect | | - | - | | **Claude.ai** | Settings › Connectors › Add custom connector, `https://mcp.agents.writesonic.com/mcp` | | **Claude Desktop** | Add to `claude_desktop_config.json` (see [Setup Guide](/agents-mcp/setup)) | | **Claude Code** | `claude mcp add writesonic-agents --transport http https://mcp.agents.writesonic.com/mcp` | | **ChatGPT** | Settings › Connectors › enable Developer Mode › Create (see [Setup Guide](/agents-mcp/setup#chatgpt)) | Team and Enterprise admins can roll the connector out org-wide, see [Organization Setup](/agents-mcp/setup#organization-setup). ## How It Works 1. **Connect**: add the Agents MCP server URL to your assistant 2. **Authenticate**: sign in with your Writesonic account via OAuth when prompted 3. **Work**: ask in natural language; the assistant calls the tools ### Example Conversation > **You:** What tasks are open in my project, and who's on them? > > **Assistant:** Let me check your Agents workspace. > > *Assistant calls `whoami`, then `query_tasks` with `view: "list"` scoped to your project.* ## Scoping: projects come first Almost every tool needs a `project_id`. Start each session by having the assistant call `whoami`, it returns your identity, your teams, and the projects in your active workspace. The assistant uses a project's `id` from that response for every following call. If more than one project could match, the assistant should ask rather than guess. ## Requirements * A Writesonic account with **Agents access** (beta) * At least one project in your [Agents workspace](https://agents.writesonic.com) ## Available Tools The server exposes 20 tools for reading and operating your Agents workspace, plus two meta-tools (`execute_batch`, `execute_plan`) for chaining calls efficiently. See the [Tools Reference](/agents-mcp/tools-reference) for full details. The core tools to know: | Tool | Description | | - | - | | `whoami` | Your identity, teams, and projects (call this first) | | `query_tasks` | List or count a project's tasks | | `get_task` | Full detail for one task | | `create_task` | Create a task in the project | | `update_task` | Edit fields, transition status, or assign a task | | `comment_on_task` | Comment on a task | | `get_agent_runs` | Agent-run history and per-run progress | | `list_workflows` / `get_workflow` | Browse playbooks and their versions and runs | | `list_grids` / `get_grid_data` | List grids and read their data | | `search_knowledge` | Semantic search over the Knowledge Base | | `get_brand_kit` | Read the project's Brand Kit | | `get_ci_dashboard` / `get_page_report` | Pages dashboard and page reports | ## Next Steps Platform-specific setup instructions Every tool, its purpose, and its REST equivalent Real-world prompts and use cases Call the same tools over HTTP # Setup Guide Source: https://apidocs.writesonic.com/agents-mcp/setup Step-by-step instructions for connecting the Writesonic Agents MCP server to your AI assistant. ## Prerequisites Before connecting, make sure you have: 1. A Writesonic account with **Agents access** (beta, [request it](https://writesonic.com/?demo=open)) 2. At least one project in your [Agents workspace](https://agents.writesonic.com) ## Connection Details Use the same values in any client: | Field | Value | | - | - | | Name | Writesonic Agents | | Description | Writesonic Agents MCP | | Server URL | `https://mcp.agents.writesonic.com/mcp` | | Authentication | OAuth | ## Claude.ai (Web) 1. Go to **Settings** in Claude.ai 2. Navigate to **Connectors** (under **Customize**) 3. Click **Add custom connector** 4. Enter the name `Writesonic Agents` and the server URL `https://mcp.agents.writesonic.com/mcp` 5. Click **Add**, then **Connect**: you'll be redirected to Writesonic to authorize access 6. Sign in and approve the connection 7. You're ready to work with your Agents workspace On a **Team or Enterprise** plan, only Owners can add custom connectors. See [Organization Setup](#organization-setup) below. ## Claude Desktop Add the following to your `claude_desktop_config.json`: ```json macOS theme={"system"} // ~/Library/Application Support/Claude/claude_desktop_config.json { "mcpServers": { "writesonic-agents": { "url": "https://mcp.agents.writesonic.com/mcp" } } } ``` ```json Windows theme={"system"} // %APPDATA%\Claude\claude_desktop_config.json { "mcpServers": { "writesonic-agents": { "url": "https://mcp.agents.writesonic.com/mcp" } } } ``` Restart Claude Desktop after saving. On first use, you'll be prompted to authenticate with Writesonic. ## Claude Code (CLI) Run in your terminal: ```bash theme={"system"} claude mcp add writesonic-agents --transport http https://mcp.agents.writesonic.com/mcp ``` On the first tool call, Claude Code opens a browser window for OAuth authentication. ## ChatGPT Custom connectors in ChatGPT require **Developer Mode**. 1. Open **Settings › Connectors** (ChatGPT prompts you to enable **Developer Mode** if it isn't already on) 2. Click **Create** to open the new connector dialog 3. Enter: * **Name:** `Writesonic Agents` * **Description:** `Writesonic Agents MCP` * **Server URL:** `https://mcp.agents.writesonic.com/mcp` * **Authentication:** OAuth (settings are discovered automatically once a valid URL is entered) 4. Accept the "custom MCP servers introduce risk" notice and click **Create** 5. Click **Connect** and sign in to Writesonic via OAuth For workspace-wide rollout, see [Organization Setup](#organization-setup). ## Organization Setup On **Team**, **Enterprise**, and ChatGPT **Business/Enterprise** plans, only Owners and Admins can add custom connectors. Setting one up at the organization level only makes Writesonic Agents **available** to your team, it does not connect anyone automatically. Each member still connects and authorizes individually, signing in through OAuth with their own Writesonic account, before they can use the tools. ### Claude (Owners & Primary Owners) 1. Open **Settings** and go to **Organization settings** 2. In the left sidebar under **Libraries**, select **Connectors** 3. In the top-right, click the **Add** dropdown and choose **Custom** 4. Enter: * **Name:** `Writesonic Agents` * **Remote MCP server URL:** `https://mcp.agents.writesonic.com/mcp` 5. Leave the **OAuth Client ID** and **OAuth Client Secret** fields (under **Advanced settings**) blank, authorization is handled automatically 6. Click **Add**: Writesonic Agents now appears in your organization's connector list Each member then enables it under **Settings › Connectors** and clicks **Connect** to authenticate with their own account. ### ChatGPT (Workspace Owners & Admins) Custom connectors require **Developer Mode**. If it isn't on, ChatGPT prompts you to enable it during this flow. 1. Open the ChatGPT **admin panel** and go to **Apps** 2. Click **Create** (top-right) to open the **New App** dialog 3. Fill in: * **Name:** `Writesonic Agents` * **Description:** `Writesonic Agents MCP` * **Connection:** keep **Server URL** selected and enter `https://mcp.agents.writesonic.com/mcp` * **Authentication:** leave as **OAuth** 4. Read the risk notice and tick **"I understand and want to continue"** 5. Click **Create**: the app is created as a draft (shown with a **DEV** label) 6. On the draft, click **Publish**, work through both risk reviews until they show **Reviewed**, then click **Publish** again 7. Writesonic Agents moves into your **Enabled apps** list Publishing makes it available to everyone in your workspace, but each user still connects and authorizes it individually via OAuth. ## Authentication The Agents MCP server uses **OAuth 2.0**. When you first connect: 1. Your client redirects you to the Writesonic login page 2. Sign in with your Writesonic credentials 3. Authorize the integration to access your Agents workspace 4. You're redirected back, the session is now active Sessions persist across conversations. You won't need to re-authenticate unless your token expires. Prefer static credentials for a backend integration? Use the [Agents REST API](/api-reference/agents/authentication) with an `X-API-Key` header instead of MCP + OAuth. ## Verifying the Connection After setup, try this prompt: > "List my Writesonic Agents projects" The assistant should call the `whoami` tool and return your project list. If this works, you're all set. ## FAQ You need an account with Agents access, which is in beta and limited to selected enterprise and agency accounts. [Request access](https://writesonic.com/?demo=open) through your account manager. The [GEO MCP](/mcp/mcp-server) (`mcp.writesonic.com`) answers questions about your AI-search visibility data. The Agents MCP (`mcp.agents.writesonic.com/mcp`) operates your Agents workspace: tasks, playbooks, grids, knowledge base, and pages. You can connect both. No. Organization setup only makes it *available*. Each member still connects and authorizes individually via OAuth with their own account. * Confirm your account has Agents access * Disconnect and reconnect the connector * Clear browser cookies for writesonic.com and retry Verify you have at least one project in your [Agents workspace](https://agents.writesonic.com). `whoami` returns projects only for your active workspace. * In Claude Desktop, restart the app after editing `claude_desktop_config.json` * In Claude Code, run `claude mcp list` to verify the server is registered # Tools Reference Source: https://apidocs.writesonic.com/agents-mcp/tools-reference Every tool the Writesonic Agents MCP server exposes, what it does, and its REST equivalent. The Agents MCP server exposes **20 tools**, plus two meta-tools for chaining calls. Every project-scoped tool takes a `project_id` argument, always call [`whoami`](#whoami) first to get it. Each tool maps to one endpoint in the [Agents REST API](/api-reference/agents/authentication); the REST path is listed with each tool (all paths are under `/api/v1/business`). ## Common arguments | Argument | Type | Description | | - | - | - | | `project_id` | string (UUID) | **Required** for project-scoped tools. From `whoami`. | | `view` / `action` / `report_type` | string (enum) | Selects which slice a multi-purpose tool returns or which mutation it performs. | | `filters` / `pagination` / `order_by` | object | Narrow, page, and sort list results. | Most tools are **read-only**. The writes are `create_task`, `update_task`, and `comment_on_task`. *** ## Identity & project ### whoami Return the caller's identity, Agents teams, and the projects in the active workspace. **Call this first**: every project-scoped tool needs a `project_id`, and you get it here. `GET /whoami` ### list\_project\_resources List a project's reference resources by `resource`: `users`, `labels`, `settings`, `skills`, or `agents`. Pass the id `whoami` returned for you as `resource_id` to fetch your own project-scoped record (for example, your role in the project). `POST /project-resources/query` *** ## Tasks ### query\_tasks Query the project's tasks. `view="list"` returns a cursor page of task list items (with filter, sort, and pagination); `view="counts"` returns totals grouped by `group_by` (status, priority, assignee, or creator). `POST /tasks/query` ### get\_task Get one task with full detail, attachments and labels are always included. Pass `include` to also fetch the task's timeline, relations, and/or approvals. `GET /tasks/{task_id}` ### create\_task Create a task in the project. Purely additive: nothing is overwritten, and the task is visible and deletable in the product. `POST /tasks` ### update\_task Update a task: edit fields (`action="update_fields"`), transition its status (`action="transition_status"`), or (re)assign it (`action="assign"`). All changes are reversible. `POST /tasks/update` ### comment\_on\_task Create a comment on a task (`action="create"`). A reversible authoring action. `POST /tasks/comments` *** ## Agent runs ### get\_agent\_runs Get agent-run history for a task or an agent, or step-by-step progress for a single run. Scope `task_runs` needs `task_id`; `agent_runs` needs `agent_id`; `run_progress` needs `task_id` and `run_id`. `POST /agent-runs/query` *** ## Playbooks Playbooks are named `workflow` in the tool and endpoint identifiers below. ### list\_workflows List the project's playbooks or their status counts. Use `view="list"` for the paginated inventory (filter by type, status, or search) or `view="counts"` for totals. `POST /workflows/query` ### get\_workflow Get one playbook and its related data. `view` selects the slice: `detail`, `versions`, `version_detail` (needs `version_id`), `runs` (filter by run status or search), or `run_detail` (needs `workflow_run_id`). `POST /workflows/get` ### list\_workflow\_components List playbook building blocks. `view="components"` is the catalog, `view="batch"` fetches by `capability_ids`, and `view="hub_capabilities"` lists the workflows-hub capabilities. `POST /workflows/components` *** ## Grids ### list\_grids List a project's grids, or read one grid's detail or processing status, via the `view` enum (`detail` and `status` need `grid_id`). `view="column_options"` is the live catalog of column types you can add. `POST /grids/query` ### get\_grid\_data Read a grid's columns, rows, a single cell, a cell's run detail, or search rows via the `view` enum. A playbook column's `workflow_version_id` (from `view="columns"`) names its pinned version, pass it to `get_workflow` (`view="version_detail"`). `POST /grids/data` *** ## Knowledge Base & Brand Kit ### search\_knowledge Semantic search over the project's knowledge base (RAG). Returns the matched chunks and, when `generate_answer` is true, a generated answer; set it false for raw chunks only. Optionally scope the search to specific sources. `POST /knowledge/search` ### get\_knowledge\_source List the project's knowledge base sources, list its folders, or fetch one source's content. Does **not** cover the brand kit, that's a separate resource fetched with `get_brand_kit`. `POST /knowledge/sources` ### get\_brand\_kit Get the project's brand kit. `view="catalog"` lists the available brand-kit section names only; use it to answer "what sections does my brand kit have." Other views compose the full section content. `POST /brand-kit` *** ## Pages ### get\_ci\_dashboard Project-level pages data: page summary, live summary, available filters, countries, the ranked page list, page groups, and the page-list column scope, selected by `view`. `view="pages"` is also how you resolve a page name or URL to a `page_id`. `POST /content-intelligence/dashboard` ### get\_page\_report Per-page report selected by `report_type` (SEO, AI citations, funnels, traffic, SERP, keywords, lifecycle, activity). Some reports require `market_id`. Resolve `page_id` from `get_ci_dashboard` (`view="pages"`). `POST /content-intelligence/page-report` *** ## Integrations & attachments ### list\_integrations List the workspace's connected apps and integration connections. `view="apps"` returns the app catalog; `view="apps_overview"` groups connections by app with active/inactive counts; `view="connections"` lists individual connections. `POST /integrations/query` ### download\_attachment Get a short-lived presigned download URL for a task or comment attachment. Returns the URL plus filename and content type, not the file bytes. For a task attachment, pass `task_id`. `POST /attachments/download-url` *** ## Meta-tools (MCP only) These two tools have no REST equivalent, they orchestrate the tools above in a single request. ### execute\_batch Run up to 10 linear tool calls in one request, passing results between steps. Use it for chains with no loops or conditionals. ### execute\_plan Run server-side TypeScript ("code mode") for plans that need loops, conditionals, or three-plus calls with intermediate data shaping. Never use it to skip resolving which project you mean. The [Agents REST API reference](/api-reference/agents/authentication) documents the exact request body and response shape for each tool's endpoint. # Activity log Source: https://apidocs.writesonic.com/agents/activity-log Every change to a page, and every signal that followed it, on one timeline. Correlation you can read, not attribution you have to trust. The Activity log is the per-page record of what changed and what happened next. Without it, connecting a change to a later result is guesswork. ## One timeline holds the changes and the signals The log records changes to a page, technical and editorial, whoever made them, agent or human. Alongside those it records what happened afterwards from both a search and an AI search perspective. So a single page's timeline might read: on 20 June you refreshed the content and rewrote the title. On 25 June ChatGPT started citing the page for a prompt it had ignored. On 26 June a new keyword entered the top ten. Those events sit next to each other in the order they happened. That's the whole idea. On each page's detail view, Activity sits beside Overview, SEO, AI Search and Content. ## Events are typed, and most carry the numbers Entries are grouped by date and filtered by **All**, **Changes** or **Alerts**, with a legend separating alerts, changes and impact. Each entry names what happened rather than logging a diff. A few real ones: | Event | What it recorded | | - | - | | Ranking improved | Average position for this page improved from 17.0 to 7.0 | | Ranking dropped | Average position for this page dropped from 2.0 to 17.0 | | SERP feature gained | Google added the People Also Ask feature on this page's target query | | SERP feature lost | Google removed the People Also Ask feature on this page's target query | | New keyword in top 10 | A query this page didn't rank for entered the top ten | | Page displaced from SERP | The page lost a result it previously held | The ones with before-and-after values state them inline. The rest carry a **View details** link. Activity log entries grouped by date, showing a lost SERP feature and a ranking improvement with its before and after positions Filter to **Changes** when you want to see only what was done to the page, and to **Alerts** when you want only what happened to it. Reading both together on one timeline is the point. ## It shows correlation, and it says so The log does not claim your change caused the result. It cannot, and nothing that reads a timeline can. What it gives you is the sequence, on the page, with dates. You decide whether the change and the signal are related. That judgement is yours, and it's a better position than the usual one, where the change and the outcome live in different tools and nobody can line them up at all. ## Turn a hunch into an experiment, then scale it The sequence becomes useful when you run it deliberately. Add FAQs to five pages. Wait, then read the five timelines. If all five moved in the same direction, you have something worth believing. Now run the same change across fifty pages, then a hundred, using a [playbook](/agents/playbooks) and a [grid](/agents/grids) so the change is identical every time. That is the difference between an opinion about what works on your site and a result you can repeat. It also means a change that did nothing gets found early, on five pages instead of five hundred. Leaving a comparable set of pages untouched makes the comparison stronger, though it isn't required to get value from the log. ## What's next See where the Activity tab lives. Run a proven change across many pages. # Approvals and review Source: https://apidocs.writesonic.com/agents/approvals Three review modes control how much you check before work is applied. Nothing reaches your live site without a person approving it. Agents change real pages. Review mode is the setting that decides how much of that work you see before it's applied. ## The agents execute, and you control what you review Agents do the work end to end. They don't stop at recommendations. They are autonomous with a human in the loop, and that loop is you. ## One of three review modes applies to every new task Choose a mode in the New Task modal. It "applies to all new tasks until changed." | Mode | What it does | When to use it | | - | - | - | | **Manually review** | Review every task and subtask before it's applied. | Use during your first week or when you want to inspect every step. | | **Skip reviews** | Subtasks run automatically. You only review the main task. | Use once you trust the steps and only want to check the finished work. | | **Review based on agent**
Default | Choose which agents need your review and which run automatically. Setting this opens **Set agent permissions**. | Use when review needs differ by agent. | The three review modes in the New Task modal We recommend **Manually review** for the first week. Then move to **Review based on agent** and let the agents you trust run. ## Set the level once per agent **Set agent permissions** lists every agent in your workspace with one setting each. **Review needed** holds that agent's output until you approve it. **Skip reviews** accepts it automatically. The Agent permissions screen listing the CMO, Content, Design, Research and SEO/GEO agents, each with a Review needed setting Research is the usual first candidate for Skip reviews, since nothing it produces reaches your site on its own. Content and Design are the ones worth holding. ## A task that needs you says so and stops A task showing the review-required banner above its brief and properties ## Nothing publishes on its own Finished work lands in your CMS as a draft. Nothing reaches your live site until a person publishes it. Agent approval and publishing remain separate actions. ## Feedback keeps the work and its context together Comment on the deliverable when something needs to change. The agent revises the existing work with the context it already gathered. Rejecting and rewriting the task from scratch throws that context away. ## What's next Follow the task lifecycle and every status. Connect a CMS so finished work lands as a draft. # Audiences and voices Source: https://apidocs.writesonic.com/agents/brand-kit-audiences-voices Who a piece is written for, and which of your voices it's written in. Two sections, two decisions an agent would otherwise make on your behalf: the reader it's addressing, and the register it uses to address them. ## Audiences tell the agent exactly who it's addressing Audience holds named segments such as Digital Marketing Agencies, Solo Marketers and Freelancers, and Marketing and SEO Teams. Each entry gives the agent a specific reader instead of a blended idea of your whole market. Tag an audience into a task when the work should address that segment. More than one segment can apply to the same task, alongside the other context you add through [task tagging](/agents/tagging-context). ## Voices let one brand sound different when the task requires it Voice defines how your brand sounds. Each named entry records its tone, the rules to follow, and the phrases to use or avoid. A single brand can hold voices such as Growth Engine, Insight Engine, and Founder's Vision side by side. The task decides which one applies, so a founder-led piece doesn't have to sound like a research report or a growth campaign. ## What's next Set the byline and what it's allowed to say. Set the shape each deliverable takes. # Authors Source: https://apidocs.writesonic.com/agents/brand-kit-authors Define who can appear in a byline, what supports their authority, and what they're allowed to say. Authors sits inside Brand Kit. Each entry represents a named individual or the company itself, with a **Type** field distinguishing the two. The section shows when each entry was last edited and includes an **Add author** button for creating another. ## The profile fixes an identity behind every byline A byline needs more than a display name. The identity fields establish who the author is, where they work, and how their name should appear publicly. **Name** identifies the profile inside your workspace. **External name** holds the exact name shown on the author's public byline, while **Title** and **Company** supply the professional context around it. Turn on **Primary** to "Make this the default author whose byline is used unless another is chosen." We recommend setting one primary author so tasks don't fall back to an unspecified byline. The top of an author profile showing the Name, Primary, External name and Title fields ## Three bio lengths keep the same identity usable Each profile holds three bio variants at about 50, 100 and 200 words. That gives the agent an appropriate version for a compact byline, a standard author box, or a page that has room for a fuller background. The three versions should tell the same story at different depths. Keep the name, role and main area of expertise consistent, then use the longer versions to add supporting experience. ## Credentials turn the byline into an E-E-A-T record **Education**, **Previous roles**, and **Notable** capture the evidence behind the author's authority. Previous roles record both the company and the role, so the profile can carry relevant career experience instead of relying on a broad claim of expertise. This is the **E-E-A-T record** behind the byline. Use **Notable** for specific work, recognition, or experience that helps explain why this person can credibly cover the subject. Add **LinkedIn**, **Twitter**, and **Website** under Social so the public identity can be connected to its source profiles. ## Permissions keep founder and company bylines distinct Permissions decide what an author is allowed to do in generated content. Each one is a toggle with a plain description, covering things like making predictions, taking contrarian positions, sharing personal opinions, telling company stories, speaking for the company as "we", making direct recommendations, criticising competitors, and discussing pricing. The Permissions section of an author profile, with a toggle and description for each permission One real profile allows predictions, company stories and direct recommendations, and keeps contrarian positions and personal opinions off. That suits a named founder whose experience supports a forecast but whose published work shouldn't pick fights. A company byline can answer every one of those differently. **Disclosure** sits alongside them. It sets whether content from this author has to carry a disclosure, and what form that disclosure takes. ## Hard prohibitions stop the author crossing known lines **Things this author would never say** is a list of statements that generated content must avoid. It records explicit boundaries that broad voice guidance can miss. Two real entries from one profile: "SEO doesn't matter anymore" and "Traditional search will never change". Write them as direct statements the author rejects. That gives the agent a concrete prohibition instead of asking it to infer one from tone. ## An author tag carries the profile into a task When a task should use a particular byline, tag the author into the task to write as them. The identity, biography, credentials and permissions then travel together as one profile. See [tagging context](/agents/tagging-context) for how to add that author alongside the task's other context. ## What's next Define the register an author should use. Add an author profile to a task. # Business and objectives Source: https://apidocs.writesonic.com/agents/brand-kit-business The facts that anchor every task, and the goals the work is measured against. An agent writing about your company has to know what your company is. Business and Objectives are the two sections that answer that before any task starts. ## Business holds the facts everything else rests on Business holds the facts that anchor everything else. Its fields include Name, Legal name, Tagline, One line pitch, Founded, Headquarters, Website, Company type, Stage, and a B2B or B2C business model. Products sit beneath those company details. Each product has a description, category, target user, and key features. Positioning then records your positioning statement, category, and named competitor entries with the differentiator that sets you apart. Those entries stop an agent inventing your differences when it writes a comparison page. ## Objectives records what the work is for Objectives what you're working toward and how you'll judge the result. You can define a content mission, a content tilt with its unique angle and difference, primary and secondary business objectives, and funnel mapping. The mapping runs stage by stage, including SEE and THINK, with a goal, relevant content types, evaluation metrics, and an optional numeric target for each stage. ## What's next Set who the work addresses and how it sounds. Set the shape each deliverable takes. # Content types Source: https://apidocs.writesonic.com/agents/brand-kit-content-types The format rules for each thing you publish: length, structure, formatting and real examples. A content type describes a deliverable's format, not its subject. Each entry has a name, a one-line description, and a Primary toggle for the format you publish most. It also sets a minimum and maximum target word count, a Structure list, and a CTA pattern. For a LinkedIn post, the Structure list might begin with a hook built around a bold data claim or event announcement. One or two lines of supporting context follow, then a directional call to action with an arrow or link. The agent gets the expected sequence before it starts drafting. The Brand Kit content type editor with fields for structure, formatting, CTA pattern, and examples Formatting uses written rules rather than on or off switches. Emojis, Exclamation points, Line breaks, and Hashtags each hold your instruction in plain words. A Line breaks rule might read `Short blocks; 1-2 sentences per line`, which carries more useful context than an enabled setting. You can also paste real pieces of that content type into Examples and give each one a short label. ## What's next Set who the work addresses and how it sounds. Pull a content type into a single task. # Design Source: https://apidocs.writesonic.com/agents/brand-kit-design Design is the Brand Kit section that stores your visual language for the Design agent. A logo file and a primary hex still leave the hardest decisions unresolved. The agent also needs to know why your brand looks the way it does and when a visual choice should stay quiet. ## Design turns visual taste into working rules The product describes this Brand Kit section as: > Your brand's visual design language, colors, typography, and components. Design is a single markdown document rather than a form. Preview shows it as a readable design system, while Edit exposes the markdown behind it. The document opens with an Overview of how the brand looks and why, then records its Key Characteristics. This is your **written brand system**. It gives the agent a coherent set of rules instead of leaving each visual decision open to interpretation. Brand Kit Design section showing a written visual system in Preview view ## Live tokens keep visual details exact Design carries live design tokens and asset paths alongside the explanations. A primary color can be recorded as a token, while the logo can be recorded as a file path. That distinction matters. The agent can use the actual hex and the actual mark instead of approximating either from a description. Typography and spacing follow the same pattern. The document can preserve the type stack and the allowed section padding range, giving the agent usable values for its visual decisions. ## Intent tells the agent when to hold back Values alone don't explain how a system should feel in use. In one real Design document, the brand's orange is rationed and used as a signal rather than a theme color. The rest of the page stays quiet so the content reads clearly. That rule does more work than the color value alone because it tells the agent where orange belongs, how often it should appear, and why generated assets shouldn't become loud. ## The Design agent works from one grounded system The Design agent is grounded in this document once, then makes visual decisions from it. Like the rest of [the agent team](/agents/the-agent-team), it uses shared context to keep its work aligned with your company. The document becomes the reference point for color, typography, spacing, assets, and visual restraint. ## Design sets direction without rendering your site Design describes the system in words, tokens, and asset paths. It isn't a component library, and it doesn't render your site. Its job is narrower. It gives the Design agent the materials and rules needed to make brand-specific visual choices. ## What's next See how specialist agents work from shared context. Set up the context every agent works from. # Build a playbook Source: https://apidocs.writesonic.com/agents/build-a-playbook Describe the workflow and it gets built as a step graph. Then open the editor, fix what's wrong, test it, and publish. Building an automation usually means placing every step and every connection by hand. Here you describe the procedure and get a working draft, then correct it. ## Describe the process instead of wiring every step The box on the Playbooks screen reads "Describe the workflow you want to automate." Type the procedure or dictate it, then select **Generate**. The describe-a-workflow box on the Playbooks screen, with a Generate button Brief it the way you'd brief a new hire. Name the inputs, put the steps in order, and say what the finished output should be. Include the checks and decisions that belong to your procedure. A vague description produces a vague playbook, the same way a vague task produces generic work. > Use a page URL as the input. Audit the page for SEO and GEO, then return prioritized recommendations, a title tag, and a meta description. If your team already has the SOP written down, paste it in. Keep its inputs, sequence, decision points and output requirements intact. That's the shortest path to a playbook that matches how you actually work. ## The editor shows the workflow as a graph What comes back is a **Draft**, and it opens in the editor. The playbook editor showing a node graph, the Skill library panel, and Test run and Publish buttons The canvas runs from **Start** through a **Manual input** node, which is where the playbook's inputs are defined, down through the numbered steps to **End**. Steps that don't depend on each other sit under a **Parallel tasks** bar and run together. A **Conditional** node splits the path, and its two branches are labelled **If true** and **If false**. A conditional node reading Research URLs Provided, with an If true branch leading to a Scrape Web Page step that runs on an LLM So you can read the whole procedure off the canvas without opening a single step. The left panel has two tabs. **Chat log** keeps the request you typed, the reasoning behind the workflow it built, and a **Workflow details** card. **Skill library** lists every skill available to the playbook, grouped by the integration it comes from. ## Setup required means it won't run yet A generated playbook often has steps that still need configuring. Those carry a **Setup required** badge, and the count in the top bar tells you how many are outstanding. A playbook can look complete on the canvas and still not be runnable. Clear the warnings before you test. ## Edit by describing the change, or by opening the step Two ways to change a workflow, and they work on the same graph. Describe what you want different in the box at the bottom, the same way you described the workflow in the first place. Or select a node and edit it directly. Use the first for structural changes and the second when one step is nearly right. ## Test run before you publish **Test run** executes the playbook on one input while it's still a Draft. Read what comes back and compare it against the procedure you meant to write. Once the output holds up, **Publish**. The playbook becomes available to run for real, on its own or across a [grid](/agents/grids). Testing first is the whole point of the Draft state. A generated structure that looks right on the canvas can still produce the wrong deliverable, and one test costs a minute. ## What's next Run it across many rows. Start from a template instead. # Choosing an agent Source: https://apidocs.writesonic.com/agents/choosing-an-agent One artifact goes to a specialist. A list, or anything needing research first, goes to the CMO. Every task needs an assignee, and the shape of the work decides which agent it goes to. ## The shape of the task decides the route **One artifact goes to the specialist that owns it.** A list of artifacts, or a job that needs research first, goes to the CMO. A decision diagram: one artifact goes to a specialist, a list or research-first job goes to the CMO agent ## Similar tasks can belong to different agents | Task | Send it to | Why | | - | - | - | | Add an FAQ section to this pricing page | CMO | Needs research first | | Update the FAQ using the People Also Ask questions for this keyword | Content | Question set is given | | Run a technical audit and list broken pages | SEO/GEO | One diagnostic job | | Fix everything flagged on this page | CMO | Several kinds of work | | Create the featured image for this post | Design | One artifact | | Find where competitors are cited and we aren't | Research | Evidence gathering only | ## The CMO is the safe choice when you're unsure Going straight to a specialist is faster when the job really is one artifact. The CMO is the default assignee on a new task, so leaving it unchanged is safe. The CMO doesn't do the work itself. It plans the job and delegates each part. That takes a little time, which is the cost of over-delegating. Under-delegating means a specialist starts without the research it needed. Teams already work this way. The SEO person writes the brief, then the content person picks it up. ## A wrong assignment costs little Nothing is lost when you choose the wrong agent. You can [reassign the task](/agents/tasks) as soon as the mismatch is clear. If a specialist has already started, the CMO can pick up the work. It then plans and routes the remaining parts. ## What's next Learn how much context to give. See what each specialist does. # Common tasks Source: https://apidocs.writesonic.com/agents/common-tasks Templates for the tasks teams hand over most. Copy one, swap in your page or topic, and send it. Every template below comes in two parts, because a task does: a **title** that names the job, and a **description** that says how to do it. Paste them into the matching fields. Swap the URL, keyword or topic for yours, and leave the rest, since the wording is doing real work. ## Templates for the work teams send most ### Fix the gaps on one page Send it to **CMO**. You need a URL that already has flagged opportunities in [Pages](/agents/pages). You get research, an audit, and the rewritten sections applied to a CMS draft. ```text title="Task title" theme={"system"} Fix the flagged gaps on https://example.com/your-page ``` ```text title="Description" theme={"system"} Research the pages currently ranking and cited for this page's target queries. Audit the title, meta description, headings, schema and E-E-A-T signals against them. Then write the missing content and apply the changes. Keep the existing URL and internal links. ``` ### Refresh a page that's losing citations Send it to **CMO**. You need a URL and the prompt or query it used to win. You get a diff-level rewrite of the sections that stopped getting cited. ```text title="Task title" theme={"system"} Refresh https://example.com/your-page for AI search ``` ```text title="Description" theme={"system"} Compare this page against the answers currently cited for "your target prompt". Identify which sections lost citations and why. Rewrite those sections so the page answers the question directly and early. Leave the sections that are still working alone. ``` ### Find internal link opportunities into one page Send it to **SEO/GEO**. You need a target URL and its topic. You get a ranked list of candidate pages, each with proposed anchor text and the exact sentence the link belongs in. ```text title="Task title" theme={"system"} Internal link opportunities pointing to https://example.com/your-page ``` ```text title="Description" theme={"system"} Find pages on our site that are topically related to this page and could naturally link to it. For each candidate, propose a contextual anchor text and the specific sentence or section where the link fits. Prioritize pages with higher authority or traffic, and avoid forced or low-relevance placements. ``` A task artifact listing internal link candidates, each with a URL, priority signal and placement ### Add an FAQ section from People Also Ask Send it to **Content**. You need a URL and its target keyword. You get an FAQ block written to match the questions people actually ask. ```text title="Task title" theme={"system"} Add an FAQ section to https://example.com/your-page ``` ```text title="Description" theme={"system"} Pull the People Also Ask questions for "your target keyword" and pick the ones this page can answer credibly. Write a concise answer for each, in our voice, and append them as an FAQ section. Don't repeat answers already covered in the body. ``` ### Turn a video into a blog post Send it to **Content**. You need a public video URL. You get an SEO-optimized draft in your CMS. ```text title="Task title" theme={"system"} Turn https://youtube.com/watch?v=your-video into a blog post ``` ```text title="Description" theme={"system"} Transcribe the video, then structure it as an article rather than a transcript. Keep the specific examples and numbers from the video. Add a title, headings, an intro that states the takeaway, and internal links to related pages on our site. ``` ### Create the images for a post Send it to **Design**. You need the post URL or draft, plus a Brand Kit with your logo and colors. You get a featured image and social variants. ```text title="Task title" theme={"system"} Create the featured and social images for https://example.com/your-post ``` ```text title="Description" theme={"system"} Use our logo and brand colors from the Brand Kit. Produce one featured image at 1200x630 and one square variant for social. Keep the composition simple enough to stay readable as a thumbnail. ``` ### Find where competitors are cited and you aren't Send it to **Research**. You need nothing beyond your connected AI visibility data. You get the prompts, the answers, and who's getting cited in your place. ```text title="Task title" theme={"system"} Find prompts where competitors are cited and we aren't ``` ```text title="Description" theme={"system"} Go through our tracked prompts and list the ones where a competitor is cited but we aren't. For each, show the prompt, what the answer says, and which page of theirs got cited. Group them by topic so I can see where the gap is concentrated. ``` ### Rank every page by what it's worth fixing Send it to **CMO**. You need Search Console and Analytics connected. You get a shortlist with reasons, not a full-site dump. ```text title="Task title" theme={"system"} Rank our pages by business impact and give me the ten to fix this week ``` ```text title="Description" theme={"system"} Use traffic, conversions, current position and AI visibility together. For each of the ten, say what's wrong and what the fix is. Skip pages where the fix is not worth the effort, and tell me why you skipped them. ``` ## Repeat any of these across many pages Once a template works on one page, it shouldn't be retyped. Save it as a [playbook](/agents/playbooks), then run it as a [grid](/agents/grids) with one row per page. Review happens per row, so a bad row doesn't hold up the rest. ## More tasks, in short These follow the same shape. Write the title, then a description that says what to do and what to leave alone. | Task | Send it to | | - | - | | Review this page's schema markup, generate an improved version, and apply it | SEO/GEO | | Show me pages sitting on page two of Google and push them to page one | SEO/GEO | | Run a technical audit and list broken and non-indexable pages | SEO/GEO | | Check whether everything we published last month actually got indexed | SEO/GEO | | Find pages cannibalizing each other, and pages declining in rank, with the reason | SEO/GEO | | Show me which past changes actually moved citations, so I know what to scale | SEO/GEO | | Write a first-draft content brief for this page, one version per audience segment | Content | | Translate these product pages into Spanish from the attached CSV | Content | | Write the full post from this CSV of study data, with charts, images and internal links | Content | | Take this product photo and place it in a different setting | Design | | Scrape our competitors' blogs for new product releases | Research | | Flag AI answers about us that are factually wrong, checked against our knowledge base | Research | | Give me this week's AI visibility report, limited to these prompts | Research | | Show our share of voice with branded prompts excluded | Research | | Show every AI answer with negative sentiment about us, with the question, response and citation | Research | ## Send each task to its owner Send one artifact to its specialist. Send a list of artifacts, or work that needs research before anyone can start, to [the CMO agent](/agents/choosing-an-agent). ## Some requested workflows aren't available yet These aren't available today. * Turning a webinar recording into a blog post, social posts and short videos * Outreach that emails authors to ask them to add you to their article * Monitoring journalist requests and sending an approved reply * Self-updating dashboards you build by describing them in chat * Publishing changes to existing static pages, as opposed to creating new CMS drafts ## What's next What separates a task that works from one that doesn't. Choose how much you review. # Connect your data Source: https://apidocs.writesonic.com/agents/connect-your-data Google Search Console is required. Add an analytics source and your CMS from there. The first connection takes about ten minutes. Open Integrations and a catalogue of apps comes up. Most of them you don't need today. ## Google Search Console and Google Analytics are the only required connections Google Search Console is required. An analytics source, Google Analytics or Plausible, is strongly recommended. Nothing else in the catalogue is required. AI visibility data arrives from the Writesonic platform automatically. There is no AI visibility integration to connect. Once both Google connections are active, you can stop here and start working. The optional connections have specific jobs. A CMS can receive finished work, third-party SEO tools add page-level data, and Gmail is available for sending email from a run. ## Every connection follows the same five steps All connections start from the Integrations screen. In the sidebar, open **Context**, then **Integrations**. **Connections** shows what you have connected, while **Apps** shows what is available. Select **Add connection** to open the app catalogue. Search by name or filter by **All**, **Code**, **Communication**, **Data**, **Design**, or **Productivity**. Open the app you want to connect. Grant Google integrations access through OAuth with your Google account. For a third-party SEO tool, paste your API key. Connections are saved per workspace. Assign each one to the specific projects that should use it. The Connections tab shows its status and which projects have access. The Writesonic Agents integration catalogue with categories and available apps ## A CMS writes finished work back as a publishable draft A CMS is optional, but we recommend connecting one early. Agents can write finished work back to WordPress.com, self-hosted WordPress, Contentful, Drupal, Webflow, or Sanity. The work arrives as a draft. Nothing publishes automatically, so a person still reviews it before publication. See [Review and approve work](/agents/approvals) for that human step. ## More data makes the gap analysis more specific Google Analytics provides the required analytics connection, and Plausible Analytics can add another source. Third-party SEO data adds more signals for each page. With more signals per page, the gap analysis can name more specific opportunities. Third-party SEO tools connect with your own API key, so you'll need your own subscription. ## What's next Add the context every agent writes from. Go from nothing to a reviewed deliverable. # Glossary Source: https://apidocs.writesonic.com/agents/glossary Every term the Agents docs use, defined once. | Term | What it means | | - | - | | Activity log | A record of changes to a page and what happened afterward. It shows which work moved anything. | | Agent | A specialist that carries out work. The specialist agents are Research, SEO/GEO, Content, and Design. | | AI visibility | How often AI answers mention your brand. The data comes from the Writesonic platform. | | Artifact | The deliverable produced by a task. | | BIP score | Business Impact Potential, a 0 to 100 score used to rank which pages to fix first. | | Brand Kit | The context every agent reads for every task. It covers your business, objectives, audience, voice, authors, and content types. | | Citation share | How often AI answers cite one of your pages. | | Closed-loop marketing | A process that tracks, prioritizes, acts, verifies, measures, then feeds what you learned back in. | | CMO agent | The agent that takes a goal, splits it into subtasks, and routes them. It does no work itself. | | Content type | The rules for one format, such as blog posts or LinkedIn posts. | | Data layer | The Writesonic platform, where AI search visibility data lives. | | Execution layer | Writesonic Agents, where the work happens. | | Grid | One playbook run across many rows, with review tracked per row. | | Knowledge Base | Your own synced documents and pages that agents use for grounding. | | Page group | A set of pages you manage together. | | Playbook | A workflow written once and run on demand. | | Review mode | The setting for how much you check before work is applied. Choose Manually review, Skip reviews, or Review based on agent. | | Single run | A playbook run on one input rather than a grid. The playbook list calls the same action Quick run. | | Smart filters | The default filter on Pages that hides stable, redirected, and pruned pages. | | Subtask | A piece of a larger task. Subtasks run in order when one depends on another. | | Task | One unit of work assigned to an agent. | ## What's next See the building blocks. Check what to do when something looks wrong. # Grids Source: https://apidocs.writesonic.com/agents/grids A spreadsheet where every row runs the same playbook. Import your list, run it, and review row by row. A playbook that works on one page is only useful if it works on four hundred. A grid is how you get there. ## A grid is a spreadsheet with a playbook wired into it Open one and it looks like a spreadsheet, because that's what it is. Columns run left to right in three groups. The **input columns** hold what the playbook needs, one set per row. The **playbook column** is the run itself. The **output columns** fill in with what came back. On a grid built from an FAQ playbook, that reads: article URL, number of FAQs, country, language and whether to use the Brand Kit, then the playbook, then the FAQs and the schema it generated. A grid showing the input columns of an FAQ playbook: article URL, number of FAQs, country code, language code and Brand Kit Scroll right and the playbook column comes into view, with the output columns after it. The playbook column of a grid showing View output on two rows and Run on a third, followed by the FAQ markdown and schema output columns Create one from the playbook's own screen with **Create grid**. ## Fill it by hand or import the list Add rows one at a time with **+ Row**, or use **Import** when the list already exists somewhere else. Most real work starts as a CSV from another tool, so import is usually the faster way in. **Export** takes the finished grid back out, outputs included. A grid holds up to **1,000 rows and 28 columns**. Past that, split the work across more than one grid. ## Run one row before you run all of them **Run All** starts every row that hasn't run. Each row also has its own **Run**. Use the single-row run first, on real input, and read what comes back. A playbook that gets it right once is worth pointing at the other three hundred rows. One that doesn't is a cheap thing to find out early, while the fix costs one row instead of four hundred. ## Review happens per row Rows are reviewed one at a time rather than the grid being accepted in one go. The grids list counts **Rows pending review** and **Rows completed** separately, so a grid can be part done. That matters at volume. Approve a first batch, check the quality held, then work through the rest. A row that came back wrong doesn't hold up the ones that came back right. The Grids table showing rows pending review, rows completed and the playbook each grid uses ## What's next Write the procedure a grid runs. See how review works elsewhere in Agents. # How Writesonic Agents works Source: https://apidocs.writesonic.com/agents/how-it-works Integrations, the Brand Kit, the agents, tasks, pages and playbooks. This page shows how they fit together. You've run a task. Now the rest of the sidebar needs a map. Agents is in beta, and access is limited to selected enterprise and agency accounts. Ask your account manager, or [book a demo](https://writesonic.com/?demo=open). ## Writesonic tracks AI search, and Agents does the work The Writesonic platform is your **AI search data layer**. It tracks how your brand appears in AI answers, which prompts include you, and who gets cited instead of you. Agents is the **execution layer**, and it works from more than that. It adds Search Console, Analytics and your CMS on top, so the work gets decided from every signal you have rather than from AI search alone. Both run on the same Writesonic login and account. The platform sidebar opens `agents.writesonic.com`. ## Integrations and the Brand Kit give every agent its context Integrations bring in Search Console, Analytics, CMS, optional CRM and conversion signals, plus AI visibility from the platform with no setup. The Brand Kit defines who you are, who you sell to, and how you sound. Every agent uses this combined context, and thin context produces generic work. The building blocks of Writesonic Agents and how they connect ## Specialists do the work, and the CMO delegates it Research, SEO/GEO, Content, and Design are specialists. Send one artifact directly to the agent responsible for it. The CMO agent does no work itself. Send it a list or research-led job instead. It splits the goal into subtasks for the right specialists. ## A task is one unit of work, and you decide when it's done A task is one assignment to an agent. The agent plans it, does the work, and returns a deliverable. Larger tasks split into subtasks across the [task lifecycle](/agents/tasks). You choose how much to review. CMS work lands as a draft because nothing publishes automatically, and you mark the task Done. ## Pages join the signals, and playbooks make the work repeatable [Pages](/agents/pages) gives every URL on your site one 360-degree record, joining its SEO, content, and AI-search signals so each named gap belongs to that exact page. A [playbook](/agents/playbooks) records a workflow once, then runs it again. Use it on one page or across hundreds. ## What's next See the full lifecycle and every status. Learn how the three review modes work. # Import your existing skills Source: https://apidocs.writesonic.com/agents/import-skills Bring the Agent Skills and MCP servers your team already runs into your workspace without rebuilding them. If your team has already written a skill, you don't write it again here. A skill is the same unit of work a [playbook](/agents/playbooks) is built from, so the folder you already have becomes a step in the workflows you build in Writesonic. ## A skill packages instructions and the material they need A skill is a folder containing a `SKILL.md` file, and that file has two parts: YAML frontmatter and markdown instructions. The frontmatter description is what an agent reads to decide when the skill applies. The markdown body is the procedure it follows once it does. Reference material, scripts and examples sit in the folder alongside it, and none of it loads until the skill is actually used. Agent Skills is an open standard, so the folder isn't tied to one tool. That is why work your team has already written moves across intact. ## An imported skill keeps its origin visible Imported skills appear in the playbook editor's **Skill library**, grouped by where they came from, next to the skills your connected integrations already provide. Add one to a playbook and it becomes a step in the graph, named for the skill it runs and badged with the system it belongs to. You can read the whole procedure off the canvas and still see which parts are yours. A skill can also be attached to an agent rather than a playbook, which makes it available while the agent works a task. ## Connect an MCP server instead of rewriting it The Model Context Protocol is an open standard for connecting AI applications to external systems: data sources, tools and workflows. A server exposes its capabilities once, and any client that speaks the protocol can use them. If you already run one for an internal system, connect that server instead of rebuilding its tools here. ## We handle the import today Send your account manager either the skill folder, `SKILL.md` and supporting files included, or the connection details for your MCP server. We add it to your workspace. Self-serve import is on the way. Until it lands, every import goes through your account manager. ## What's next See how skills chain into a repeatable workflow. Turn a described procedure into a step graph. # Integrations Source: https://apidocs.writesonic.com/agents/integrations Every app you can connect, whether it's required, and what each one feeds. Agents works from whatever you connect. The more of your stack it can read, the more of the work it can finish without coming back to ask you something. ## Connect what you have, starting with search and analytics A few categories carry most of the value. **Search** is Google Search Console, and it's the one integration Agents requires. It tells an agent which queries a page already wins, which it nearly wins, and where it slipped. Without it there's no SEO half to the page record. **Analytics** is Google Analytics or Plausible, whichever you run. Neither is required, but connect one. It's what turns a ranking into a business number, so the agents can rank work by what it's worth rather than by traffic alone. Adobe Analytics is on the way. **CMS** is where finished work lands. Without it, an agent hands you a document and you paste it yourself. With it, the draft appears in the system your team already publishes from. **AI visibility** needs nothing from you. It comes across from the Writesonic platform automatically. If access is slow to arrange, connect **Google Search Console** and add the rest as it clears. That's the floor, not the target. Everything you add widens what the agents can decide for themselves. Follow [Connect your data](/agents/connect-your-data) for the setup steps. ## The full catalogue Open the Apps tab, select Add connection, and filter by All, Code, Communication, Data, Design, or Productivity. | Category | Integration | What it feeds | How it connects | | - | - | - | - | | Search | **Google Search Console** (required) | Queries, impressions, clicks and positions per page | OAuth | | Analytics | **Google Analytics** | Sessions, engagement and conversions per page | OAuth | | Analytics | Plausible Analytics | The same traffic picture, if you use Plausible instead | API key | | CMS | WordPress.com | Finished work written back as a draft | OAuth | | CMS | WordPress self-hosted | Finished work written back as a draft | API key | | CMS | Webflow | Finished work written back as a draft | OAuth | | CMS | Contentful | Finished work written back as a draft | API key | | CMS | Sanity | Finished work written back as a draft | API key | | CMS | Drupal | Finished work written back as a draft | API key | | SEO data | Ahrefs | Backlinks, keyword and domain metrics | API key | | SEO data | Moz | Domain authority and link metrics | API key | | SEO data | DataForSEO | Keyword and SERP data | API key | | Email | Gmail | Drafting email during a run. Sending stays with you | OAuth | | AI visibility | Writesonic platform | Prompts, citations and share of voice | Automatic | The SEO data integrations are for teams that already pay for those tools and want the agents reading the same numbers they do. ## More integrations are coming, and you can ask for the one you need The catalogue keeps growing. If the app your team depends on isn't listed yet, select **Request an app?** at the bottom of the catalogue, or reach out to sales or your account manager with the app name and what you'd want it to feed. The integrations catalogue, with category filters and a Request an app button ## Connections stay with the workspace and access stays project-specific Connections belong to the workspace. You assign each connection only to the projects that should use it. The Connections tab shows its status and which projects have access. On a team, this makes access visible and keeps unrelated projects separate. The Connections tab listing connected apps with their status, app and project access ## Third-party SEO data uses your own subscription You bring the API key. Each third-party SEO integration requires an active subscription with that provider. Add the connection with the API key from your account. The subscription isn't included with Writesonic. ## What's next Follow the setup steps. See how work reaches your CMS. # Knowledge Base Source: https://apidocs.writesonic.com/agents/knowledge-base Keep the source material agents use accurate, organized, and current. A model may remember an older answer or fill a gap with something plausible. The Knowledge Base gives every agent material your team controls, so its work starts with facts you can verify. See [where context lives](/agents/where-context-lives) for how agents use this shared context. ## The Knowledge Base tells agents what to write from The Brand Kit says how to write. The Knowledge Base is **what to write from**. Add product documentation, pricing and packaging details, positioning documents, past research, and customer proof. Sources appear in a list on the left. Select one to open it and inspect the material available to agents. This is also the place for knowledge that hasn't been published. If an important product distinction lives only in someone's head, you can write it directly into a document. ## Each route fits a different kind of material An empty Knowledge Base offers the four routes directly, and **Add knowledge** carries the same list once you have sources in it, plus **New folder** for grouping them. The empty Knowledge Base offering Keep a website in sync, Add URLs, Upload files and Start a blank doc | Route | Use it for | Stays current | | - | - | - | | **Keep a website in sync** | A domain whose pages agents should read | Auto-refreshes when pages change | | **Add URLs** | Individual pages carrying a specific fact | Auto-refreshes when pages change | | **Upload files** | PDFs, Word docs, spreadsheets, or a zip | Fixed at upload | | **Start a blank doc** | Notes, briefs and guidelines that exist nowhere else | You edit it | Both web routes refresh themselves, so a page you correct on your site is corrected here too. Uploads and blank docs are snapshots, and stay whatever you last saved. Choose the narrowest useful source. One URL for a pricing page beats syncing the whole domain to reach it. ## Synced websites stay connected to their pages A website sync isn't a one-off import. Open the source to see a **Tracked pages** table with one row for each page. Every row reports **Synced** or **Sync failed**. A failed row identifies the exact page that didn't come through, instead of letting the crawl fail silently. The source also shows a **Last synced** timestamp, and **Sync now** requests an immediate refresh. When a tracked page changes on your site, its Knowledge Base version changes through the ongoing sync. That keeps agents closer to the material customers and your team can see now. ## One source can ground one specific task Shared knowledge is useful, but some work needs a tighter boundary. You can tag a Knowledge Base source into a single task so the agent grounds that work in one specific document. Use [tagging context](/agents/tagging-context) when a pricing analysis should use the current packaging document, or when a customer story should stay faithful to its approved proof. ## Brand instructions belong in the Brand Kit Don't put brand voice or author profiles in the Knowledge Base. Those instructions belong in the [Brand Kit](/agents/set-up-brand-kit), where they tell agents how your company and its authors should sound. Keep facts here and writing guidance there. ## What's next Set the voice, positioning, and author profiles agents should follow. Attach a specific Knowledge Base source to one task. # What is Writesonic Agents Source: https://apidocs.writesonic.com/agents/overview Agents is the half of Writesonic that does the work. Specialist agents read your SEO, content and AI search data, find what to fix, and fix it with your approval. Agents is a second workspace on the Writesonic account you already have. It doesn't replace the platform you use now, and it doesn't need setting up from scratch. Connect Search Console and Analytics, complete your Brand Kit, and you're running. **Agents is in beta.** Access is currently limited to selected enterprise and agency accounts. To request it, talk to your account manager or [book a demo](https://writesonic.com/?demo=open) with our sales team. ## The platform shows where you stand, and Agents does something about it The Writesonic platform tracks how your brand appears in AI search. Agents is the other half, where the work to change that actually gets done. Both products share your Writesonic login and account, but Agents has its own workspace at [agents.writesonic.com](https://agents.writesonic.com). Open it from the platform sidebar. Your AI visibility data flows across automatically, so you don't reconnect the platform. ## Every signal belongs in one record for each page We pull Google Search Console, Google Analytics, your CMS and Writesonic AI visibility data into one place. You can add CRM and conversion data when you use them. Together, these sources create a **360-degree view of every page**. With every signal on the same page record, Agents can run a real gap analysis and name the exact gaps and opportunities. The full view also keeps one fix from creating another problem. An SEO change shouldn't damage AI search, and an AI-search change shouldn't cost you SEO. That trade-off appears when signals stay split across tools. Scattered data sources converging into a single page record with one gap highlighted ## The agents work autonomously while you keep control The roster covers Research, SEO/GEO, Content and Design. A CMO agent receives the goal and delegates the work to the right specialists. It doesn't do the work itself. Once assigned, the agents carry the work through end to end without being babysat. You choose the review mode and approve the result. Finished work lands in your CMS as a draft, and nothing publishes on its own. The agent team: a CMO agent delegating to Research, SEO/GEO, Design and Content specialists ## Most teams stop after acting and leave the marketing loop open Last month, you published 10 posts or landing pages. Did all 10 get indexed? If they were ranking on Google in week one, are they still ranking in week four? Most teams can't answer either question. **Closed-loop marketing** is the version where you can. It starts with tracking the keywords and prompts that matter, then prioritizing them by business impact and whatever you're chasing this quarter. Acting is the part everyone already does. Verifying is the part that gets skipped, and it's a yes or no gate. Did the page get indexed, and can ChatGPT crawl and read it? If Google never indexed it, nothing after that matters. Measuring comes 14 to 28 days later and asks about performance. Did the page start ranking, or start getting cited? AI search makes this sharper. A page can get cited the week you publish it and lose those citations a month later. Then you iterate, and what you learned sets the next round of priorities. That's the loop closing. It's also what moves organic marketing from reactive to proactive. The closed marketing loop: track, prioritize, act, verify, measure, iterate ## Agents can finish one page or repeat a proven workflow across your site * Hand a whole page to an agent and get the audit, research and rewrite back * Turn a workflow you repeat every week into a playbook and run it across hundreds of pages * See every page on your site in one view, with what to fix ranked by impact * Track what you changed and what happened after Start with one page, then turn the work that repeats into a playbook. ## What's next Search Console and Analytics, in about ten minutes. The building blocks behind the product. # Page detail Source: https://apidocs.writesonic.com/agents/page-detail Inspect one page across five evidence tabs, then turn its named opportunities into a reviewed agent task. Open **Pages > Page details** to investigate a single page. The header shows its title with a link to the live URL, the selected market such as US, and a date range compared with the previous period. The right-hand Details panel keeps Type, Target keyword, Word count, Published, Last updated, First seen, Index status, and Search intent visible as you move between tabs. BIP is a prioritisation aid that is still being built out. ## Overview names the work worth doing Overview opens with a plain-language status such as "Barely surfacing in search", a Dormant badge, and the compared window. It then shows clicks and impressions for the last 28 days. A real page with about 0 clicks and 100,167 impressions is captioned "Very little traffic to work with". Below that diagnosis, **named opportunities** turn the gaps into concrete work: 1. Add answers to all existing FAQs 2. Add selection criteria and GEO invisibility rationale 3. Missing 2 keyword variations 4. Meta description lacks competitive edge 5. Page missing structured data A card beside the list explains what the button will do: > Act on all 5 opportunities. We'll create one task for your agent to work through every opportunity on this page. Review before creating. Select **Address opportunities** after reviewing the list. The CMO agent receives one task and splits it into subtasks. Nothing publishes on its own, and any CMS work lands as a draft. Overview tab showing a page status, five named opportunities, and the Address opportunities button ## SEO separates search performance from the results page The **Organic Search** section attributes its data to Google Search Console. Clicks, Impressions, Average position, and CTR are toggleable metrics plotted on the same chart, so you can change the view without losing the shared date range. **Marketing Traffic** sits below it and identifies Plausible or GA4 as its source. SERP Intelligence explains the search environment around the page. It records search intent, gives a written read of what is ranking, and shows which SERP features were captured out of four: featured snippet, People Also Ask, related searches, and knowledge graph. Your position appears beside the organic competitors ranking above you. SEO tab with Organic Search metrics, Marketing Traffic, and SERP Intelligence ## AI Search connects visits and citations to their source The **AI Search** tab separates bot visits from human visits and breaks the bot traffic out by platform. This shows which platforms are reaching the page without folding their activity into human traffic. Citations provide the other half of the view. You can slice them by prompt, platform, and topic to see where the page is being used in AI answers and where it remains absent. ## Content shows the inputs behind its score The **Content Signals** band gives you six page-level readings before the score: | Signal | Example reading | | - | - | | Freshness | 5 months ago | | Word Count | 4.2K | | H1/Title Match | Keyword in title | | Internal Links In | 3 | | Internal Links Out | 42 | | External links | 14 | Below the band, Content Score grades the page out of 100 and assigns a label such as Excellent. Nine weighted signals contribute to it: Schema 15%, E-E-A-T 15%, Structure 12%, Internal Links 12%, Information Gain 10%, Keyword Alignment 10%, Readability 10%, Non-Commodity 8%, and Freshness 8%. Coming soon. Per-signal breakdown is not available yet. The Content tab showing the six Content Signals tiles: freshness, word count, H1 and title match, internal links in and out, and external links ## Activity keeps the page's history in one place The **Activity** tab shows this page's own history, with the wider record covered in the [Activity log](/agents/activity-log). ## What's next See what happens after you press Address opportunities. Check the record used to prove the change worked. # Pages Source: https://apidocs.writesonic.com/agents/pages See search, traffic, and AI visibility signals for each URL, then narrow the table to the pages that need work. The useful question is which URL deserves attention first. ## Every page keeps its signals in the same scope Pages creates one record per page. Each row joins Google Search Console, your analytics source, and AI visibility data, so you don't have to reconcile separate reports before choosing what to work on. The market selector and date range apply to every signal, with a previous-period comparison. A **Tracking** indicator in the header shows how many pages are in the set. Four headline numbers show the current value and previous-period change for Visitors, Google Clicks, AI Visibility, and Citation Share. Four Pages headline metrics with their previous-period changes ## Smart filters remove pages that need no attention **Smart filters** are on by default. They turn the full table into an **attention view** by hiding stable, redirected, and pruned pages while keeping the current market and date range intact. The banner says exactly what happened: > 169 pages hidden, stable, redirected and pruned, so you can focus on what needs work. **Show all pages** brings the complete table back. The smart filters toggle lets you return to the attention view without rebuilding any conditions. Pages table with smart filters, the hidden-pages banner, Add pages, New group, and the Status column ## Automatic status identifies the condition on each page The **Status** column is the fastest way to choose what to work on because the product detects the condition for you. You don't have to hunt through traffic, ranking, and indexing signals first. A page carries one status: **Not indexed**, **Cannibalizing**, **Underperforming**, **New**, **Rising**, **Declining**, **Dormant**, **Stale**, or **Thin**. **Not indexed** means Google hasn't indexed the page. **Cannibalizing** means two of your own pages are competing for the same query. **Dormant** and **Stale** identify pages that have stopped moving, while the remaining values separate new momentum, lost momentum, and pages that need closer review. ## Custom filters isolate a precise opportunity Select **Add filter** to build a condition using Primary keyword intent, Traffic, Clicks, Impressions, Position, Citations, Citation Share, or AI bot visits. Each metric includes its value and its trend, such as **Position** and **Position Trend**. Two filters are especially useful: 1. Set **Position** from **11 through 20** to find pages sitting just off page one. 2. Set **Citations Trend** to **falling** to find pages losing ground in AI answers. You can combine these conditions with smart filters and page groups to keep the table aligned with the work at hand. ## Page groups match the way campaigns are planned Page groups are your own labels for sets of URLs. The useful unit is usually a topic cluster or campaign, such as competitor-alternative pages you're prioritising this month or every page tied to a Q3 product launch. Tag a page from the **Page groups** column on its row. One page can belong to more than one group, which lets the same URL sit inside both a topic cluster and a launch campaign. Create a group from the **Page group** filter by typing a name that doesn't exist yet, or select **New group**. **Manage groups** lets you rename or remove groups. Once created, every group becomes a table filter. ## Add pages brings missing URLs into the table Select **Add pages** for URLs the table doesn't already cover. Paste one URL per line or upload a CSV, then optionally place the new pages into a page group as you add them. ## Every row carries enough context into the fix The table also includes Page, Impressions, Clicks, Traffic, Position, Citation Share, Type, Primary keyword intent, and Page groups. Every row ends with **Fix**, which hands the page to an agent with its signals attached. Open the [page detail](/agents/page-detail) when you need the full view for one row. ## What's next Open the signals and opportunities attached to one page. Review the work completed by your agents. # Playbook library Source: https://apidocs.writesonic.com/agents/playbook-library The playbooks that ship with Agents, what each one does, and which are still in beta. A set of playbooks ships ready to run. Running one on real input is the fastest way to understand what a playbook is, and it saves you describing a workflow that already exists. ## Open the Templates tab to see them Playbooks splits into three tabs. **All playbooks** is everything available to you, **Your playbooks** is what your workspace has built, and **Templates** is what ships with the product. The tab shows the count for your workspace. The list shows ten at a time, so use the pagination at the bottom to reach the rest. The Templates tab of the playbook library, showing shipped playbooks with Beta badges ## What each one does Most of them carry a **Beta** badge. Beta playbooks run normally. The badge means the steps are still being tuned, so read the output before you trust it at volume. ### Write and publish | Playbook | What it does | | | - | - | - | | Article Generation v10 | The full pipeline: competitor analysis, keyword curation, title, outline, research, writing, review and editing | Beta | | YouTube to Blog | Turns a video into an SEO-optimized post, with keyword research, meta tags and a featured image | | | Translate Content | Translates one piece of content into a target language, with optional style matching and preservation rules | Beta | | Humanize Content | Rewrites AI-generated content to read naturally, preserving formatting and links | Beta | | Get Hero Stock Image for Article | Reads an article and generates a hero image from its content | Beta | ### Improve pages you already have | Playbook | What it does | | | - | - | - | | Bulk Content Optimizer | Recommendations for many pages at once, exported as a CSV | Beta | | Meta Tags Optimizer | Rewrites meta title and description for a URL, using page-type-aware SEO and GEO rules | Beta | | Schema Generator | Generates JSON-LD structured data for a page, with page-type-specific guidelines | Beta | | Internal Link Builder | Inserts internal links into a Markdown article by finding relevant pages on your domain | Beta | | FAQ Suggester v2 | Generates FAQs from an article URL, and waits for your review before creating schema markup | | | FAQ Suggester | The earlier version. Pulls People Also Ask, researches Reddit and Quora, and returns FAQs with schema | | ### Diagnose | Playbook | What it does | | | - | - | - | | Keyword Cannibalization Checker | Finds which of your pages compete for the same keyword, analyzes the conflict, and says whether publishing more on that keyword is safe | Beta | | Analyze SERP for Target Keyword | Reads the search results for a keyword, tracks your domain in them, and returns recommendations | Beta | ### Win citations off your own site | Playbook | What it does | | | - | - | - | | Citation to Outreach Target Finder | Finds pages cited in AI answers that mention competitors but not you, resolves the author's contact details, scores each lead, and drafts the outreach email | Beta | | Reddit Citations Outreach | Finds the Reddit threads AI assistants cite for your project, analyzes each one, and drafts a comment | Beta | ### Research | Playbook | What it does | | | - | - | - | | Ecommerce Product Review Summariser | Summarizes product reviews for a brand across e-commerce sites and Reddit | | ## Running one Each row has a **Quick run** action, which takes one input and returns one result. Open the playbook itself and you get the same thing as **Single run**, alongside **Create grid** for running it across many rows at once. The playbook's own screen also keeps its run history, so you can see how previous runs ended before you commit to a large one. Start with Quick run on real input. A template you've watched work once is a template you can safely put in a [grid](/agents/grids). A completed playbook run showing its recorded inputs and the Research, Output and Details tabs A run records the inputs it was given and keeps them with the result, so you can see exactly what produced a given output. **Research**, **Output** and **Details** split what came back: Output is the deliverable, and the other two show the working behind it. ## Every template can become your own A template is a starting structure, not a locked process. Open it in the editor, keep the steps that match how you work, and change the ones that don't. ## What's next Describe your own process and turn it into a playbook. Run one playbook across many rows. # Playbooks Source: https://apidocs.writesonic.com/agents/playbooks A workflow written down once, then run on demand. Playbooks are what a repeated task should become. A playbook is a workflow written down once and run on demand, on one page or on four hundred. It is what a task should become once you've sent the same request a third time. ## A playbook is a procedure, not a prompt Agents run on language models. Hand one the same goal twice and you get two good answers, not the same answer. That is the right trade for most work, and it is why a [task](/agents/tasks) reads like a brief to a colleague rather than a script. Some work doesn't want that. An SOP your team follows the same way every time, a format that has to match, a check that has to happen in a fixed order. A playbook is where that lives. It's a chain of steps that runs in the order you wrote them, every time. The structure repeats. What each step produces is still the model's work, so read the output before you trust it at volume. ## A playbook is built from skills Each step in a playbook is a skill, and skills chain together into a workflow. Alongside them sit tool calls into whatever you've connected, so a single playbook can read Google Search Console, pull your AI visibility data, fetch a page, and write a draft back to your CMS in one run. Steps can run in parallel where they don't depend on each other. Skills your team has already written elsewhere are the same unit of work, so they can be [imported](/agents/import-skills) rather than rewritten. ## Describe the workflow and Agents builds it The Playbooks screen starts with one box labeled "Describe the workflow you want to automate." Its placeholder reads "Describe the process you wish ran on autopilot." Write the workflow in plain language, then select Generate. Agents builds the playbook from your description. The describe-a-workflow box on the Playbooks screen, with a Generate button The screen separates All playbooks, Your playbooks, and Templates, and each tab carries its own count. Each row shows the playbook's description, Category, Status, Last run, and an Open editor action. ## Run it once or across hundreds of rows Open a playbook and you get two buttons. **Single run** takes one input and returns one result, and it's the same action the playbook list offers as Quick run. **Create grid** runs it across many rows at once, which is covered in [grids](/agents/grids). The playbook keeps its own run history, so you can see every past run and how each one ended. A playbook detail screen showing Single run and Create grid buttons above a list of past runs with Success, Review and Failed statuses ## Start from a shipped template Check the [playbook library](/agents/playbook-library) before describing a workflow from scratch. One of the shipped templates may already cover the procedure you need. ## Call a playbook from inside a task This is the part most people miss. A playbook isn't only something you run on its own. You can point a task at one. Write the task the way you always would, and [tag](/agents/tagging-context) the playbook in the description with `@`. A task takes one playbook. ``` Write this month's comparison article @Article Generation v10 Target keyword is "ai seo tools", and send it to WordPress as a draft. ``` The agent still plans the surrounding work, still decides what needs researching, still comes back for approval. But the part you care about being consistent runs your steps, in your order. Ask for five articles and all five go through the same procedure. That's how the two halves fit: the agent handles the judgement, the playbook handles the parts that shouldn't vary. ## Your third repeat should become a playbook Use a simple rule. If you've asked for the same work three times, write it down as a playbook. The first version starts as a Draft, and that's expected. Open the editor and keep refining it until the procedure matches how you want the work done. Repeated work should stop requiring repeated instructions. ## What's next See the playbooks that ship already built. Run one playbook across many rows. # Publishing Source: https://apidocs.writesonic.com/agents/publishing Finished work lands in your CMS as a draft. Publishing stays a human action. The CMS connection is the only integration with write access. Every other integration is read-only. Nothing an agent does is applied without your approval, and finished work arrives as a draft. You open it in your own CMS, check it, and publish from there. ## Publishing always stays with you Nothing is published automatically, ever. When you ask an agent to send work to your CMS, it arrives as a draft. You can also ask the agent to update the meta description at the same time. ## Your CMS must be on the supported list Agents currently supports six CMS connections. * WordPress.com * WordPress self-hosted * Contentful * Drupal * Webflow * Sanity Follow [Integrations](/agents/integrations) to connect your CMS. ## Approval and publishing are separate actions When you [approve a task](/agents/approvals), you approve the work inside Agents. You don't publish the CMS draft. Open the draft in your CMS, review it there, and publish it when you're ready. The second action is yours. ## Published-page updates need a one-page test Test any change on one published page before running the same update across many. Check the page body and meta description on that first page, then scale. ## What's next Review agent work before it reaches this step. Connect your CMS to Agents. # Run your first task Source: https://apidocs.writesonic.com/agents/run-your-first-task Create one task, watch an agent work it, and review what comes back. About fifteen minutes from here to a finished draft. A first task is worth choosing carefully. Ask for something broad and you won't be able to tell whether the agent did well. ## A small, checkable task makes the first result useful Choose a first task with a **clear finish line**. We recommend asking for internal link opportunities that point to one existing page. The job is small and finishes quickly. You can judge each suggestion against your site as soon as it arrives. Use this goal for your first run. > Find internal link opportunities across our site that point to \[page URL]. Don't begin with "improve our SEO." That task has no agreed output, so it teaches you nothing about whether the agent did useful work. ## The agent needs a goal, not a procedure Give the agent the result you want. It plans its own steps. Select **New Task** from the sidebar. The modal opens with title and description fields. The empty Create task modal in Writesonic Agents Give the task a clear title, then describe the result you want. Include the page you want the internal links to point to. Don't write a procedure for the agent to follow. The Create task modal with a goal written in the title field Leave the assigned agent on **CMO** for this first run. CMO splits the goal into subtasks and hands them to specialists. For later tasks with one artifact, assign the specialist directly. The agent picker showing Research, SEO/GEO, Design, Content and CMO alongside team members Leave the status at **Todo** and priority at **No priority**. The same row includes **Labels**. In the footer, leave the review mode set to **Review based on agent**. You'll also see **Actions** and **Cancel** there. Select **Create task**. Creating the task with CMO assigned starts the work, so there is no separate start button. ## The task shows you what the agent is doing The task moves from Todo to In Progress. Its description locks while the agent works, which preserves the goal it is acting on. A banner shows what the task is waiting on. Subtasks appear as CMO hands work to specialist agents. The activity feed records progress, including status moves such as Todo to In Progress. A Writesonic Agents task in progress showing its banner, subtasks and activity feed Nothing is wrong if your first task stays In Progress for a few minutes. ## Your review happens on the artifact Finished work appears as an artifact on the task, and the task moves to In Review. Read the artifact against the original goal. If it needs a change, comment on the deliverable instead of rewriting the task. The agent keeps the context it already gathered for the revision. You decide when the work is done. Move the task to Done yourself once you accept it. CMS work lands as a draft for human review, so accepting the task doesn't publish it. See [Approvals](/agents/approvals) for review settings. See [Tasks](/agents/tasks) for task states and controls. ## What's next See what other teams hand over. Choose how much you review. # Security and data Source: https://apidocs.writesonic.com/agents/security-and-data What Agents can access, what it can change, where your data goes, and what it is never used for. An autonomous system with credentials to your analytics and CMS needs clear boundaries. Agents limits what each connection can do and where it can be used. ## Every integration is read-only except the CMS Agents can't change data through its read-only connections. The CMS connection is the only integration with write access. It writes completed work to your CMS as a draft. Nothing publishes automatically, so a person reviews each draft before it goes live. ## You grant and revoke access through your own accounts Google integrations connect over OAuth with limited scopes. You grant access from your own Google account and can revoke it there. API keys for third-party tools remain yours and can be rotated. ## Writesonic is SOC 2 Type 2 and HIPAA compliant Writesonic is SOC 2 Type 2 and HIPAA compliant. ## Customer data stays out of model training We don't use customer data to train models. ## Work runs across Anthropic and OpenAI Agents routes model work across Anthropic and OpenAI. OpenAI models run on Azure. If one provider degrades, cross-provider fallback keeps work running. ## Connections are scoped to specific projects Connections belong to a workspace, then each connection is assigned to specific projects. A connection isn't available to every project by default. Agents can use it only where it has been assigned. ## What's next See what connects and how. See the human checkpoints. # Brand Kit Source: https://apidocs.writesonic.com/agents/set-up-brand-kit Brand Kit gives every agent the same standing business, audience, voice, content, and design context on every task. Your Brand Kit is the **standing context** every agent reads before working on a task. You define it once, then update it when your business, audience, or standards change. The Brand Kit sections under Context in the Writesonic sidebar ## Every agent starts from the same brand context A task brief should explain the work you need now. It shouldn't have to repeat your company background, audience, voice, author details, format rules, or design direction. The Brand Kit keeps those instructions in one shared place. Business, Objectives, and Design are single documents. Audience, Voice, Authors, and Content types can each hold multiple named entries, so the relevant options can coexist without being blended into one generic profile. At the bottom of every section, a green bar confirms how that context is used: > Live in your brand kit. The AI references this section when writing for you. That context remains available across tasks and agents. ## We build the first version from what you already have You won't be left with an empty form to fill in section by section. We generate the starting point from one of two sources. 1. **Your live website.** Give us your URL and we infer the Brand Kit and the design kit from the site. This captures the brand you've already published, in the language and visual direction your customers see today. 2. **Your existing brand guidelines.** Send us the documents your team already uses, PDF or DOC. We turn that material into the matching sections. Your website reflects what is live. Your guideline documents often carry standards and distinctions that never made it onto the site. Pick whichever better represents the brand you want agents to follow. ## Nothing counts until you approve it Everything we generate arrives as a **draft**. The Brand Kit opens on a review screen that tells you how many drafts are waiting and how many you've approved, and the sidebar carries a percent-complete bar until you're through them. The Brand Kit review screen showing 17 drafts ready to review, 0 approved, and a Review button on each section **Start reviewing** walks them one at a time. Read the draft, then **Approve and Next** to accept it, or **Edit with AI** to say what's wrong and have it redrafted. A counter tracks where you are in the run. The Brand Kit review flow showing a generated Business section with Edit with AI and Approve and Next in the footer Work through the whole set before you assign real work. An unapproved section still reads as your brand to an agent, and a generated guess that nobody checked is the one thing that shows up in the output. ## Each Brand Kit section has its own page Use these pages when you need to review or refine a specific part of the shared context. | Section | What it sets | | - | - | | [Business and objectives](/agents/brand-kit-business) | Your facts, products and positioning, and the goals the work is measured against | | [Audiences and voices](/agents/brand-kit-audiences-voices) | Who a piece is written for, and which of your voices it's written in | | [Authors](/agents/brand-kit-authors) | The byline, its credentials, and what that author is allowed to say | | [Content types](/agents/brand-kit-content-types) | The length, structure and formatting rules for each thing you publish | | [Design](/agents/brand-kit-design) | The written visual system the Design agent builds from | ## Task tags can focus or override the standing context The Brand Kit supplies the default. A particular task may need one audience, a specific author, or guidance that differs from the usual standard. In those cases, you can [tag context into the task](/agents/tagging-context) to focus the agent on the relevant entry or override the default for that piece of work. The underlying Brand Kit remains unchanged for future tasks. ## What's next Define the brand and people who can receive attribution. Give agents the source material they can use in their work. # Tag context into a task Source: https://apidocs.writesonic.com/agents/tagging-context Point a task at a specific playbook, author, audience or source instead of describing it in prose and hoping the agent picks the right one. A task written entirely in prose leaves the agent to work out which playbook you meant and which voice to write in. Tagging removes the guess. You name the exact object, and it goes into the brief as a reference the agent resolves rather than a phrase it interprets. ## Two ways to tag, and they open the same picker Select **Actions** below the description, or type `@` anywhere in the description itself. Both open the same list, filtered by a row of tabs. The Actions picker showing All, Knowledge base, Playbooks, Integrations, Brand kit and Users tabs, with Brand kit selected and Audience, Voice and Author groups listed | Tab | What it holds | | - | - | | Knowledge base | Every source you've added: URLs and uploaded files | | Playbooks | Every playbook in the workspace | | Integrations | Your connected accounts, listed per provider and per connection | | Brand kit | Your Audience, Voice, Author, Design and Content type entries | | Users | People in your workspace | | All | Everything above in one list, grouped by type | ## One playbook per task, as many of everything else as you need Tag a [playbook](/agents/playbooks) and the task runs those exact steps rather than whatever approach the agent would have chosen. That is how you get a repeatable result out of a system that is otherwise probabilistic: describe the outcome in your own words, then name the playbook that has to produce it. A task takes one playbook. Tag a second and it replaces the first. Everything else is multi-select. Two audiences, an author and a content type can all sit in the same brief. ## Brand kit tags decide who it sounds like and who it's for The [Brand Kit](/agents/set-up-brand-kit) entries are the ones worth reaching for most often, because they answer the questions a brief usually leaves vague. **Author** sets whose voice it's written in. **Audience** sets who it's written for. **Voice** sets the register. **Content type** sets the shape of the deliverable, so a LinkedIn post and a landing page don't come back looking the same. Mix them. An article written as one author for one audience is a different piece from the same article written as another. ## Tags sit inline, so write the sentence around them A tag lands in the description as a chip where your cursor is. Everything else stays plain English. A Create task modal with a title and a description containing four tags followed by plain-text instructions Tag the things that have an exact answer and write the rest normally. The word count, the target keyword and where the draft should land are all better as a sentence than as a tag. Closing the modal offers **Save to draft**, so a half-composed brief keeps its tags until you come back. ## What's next What to put in the prose around the tags. Set up the authors, audiences and voices you'll tag. # Tasks Source: https://apidocs.writesonic.com/agents/tasks A task is one unit of work you hand to an agent. This page covers the full lifecycle, subtasks, blocking, and why done is a human action. A task is one assignment. Its status tells you whether an agent is working on it or whether it's waiting on you. ## A task gives one agent one goal A task is one unit of work you assign to an agent. Give it a goal, not a procedure. The agent plans the work, completes it, and returns a deliverable. Agents run on language models, so the same goal won't produce an identical result twice. When you need the same steps in the same order every time, write the procedure as a [playbook](/agents/playbooks) and point a task at it. ## Each status tells you who the task is waiting for Tasks are listed grouped by status, so one glance tells you whether the agent is working or whether you are the thing holding it up. The Writesonic Agents task list grouped by status, with counts for All tasks, In Review, Active and My Tasks | Status | What it means | Who sets it | | - | - | - | | Backlog | Parked. Nothing runs while a task sits here. | You | | Todo | Assigned and queued. For an agent, this is the trigger. | You | | In Progress | The agent is working. | The agent | | Pending Approval | The agent paused mid-task and needs you before it continues. | The agent | | In Review | The deliverable is ready and waiting on you. | The agent | | Done | You accepted the work. | You | | Cancelled | The work was stopped. | You | There is no Blocked status. The two that need you are **Pending Approval** and **In Review**. ## Todo is the trigger, and the assignee decides who drives Assign a task to an agent while it's in **Todo** and the agent picks it up on its own. It moves itself to In Progress and starts. There's no start button, and nothing else is required from you. Create the task in **Backlog** instead and nothing happens until you move it to Todo. That's the difference between the two states, and it's the one worth remembering: Backlog parks work, Todo releases it. When the agent has a deliverable, it moves the task to **In Review** itself. Everything between Todo and In Review is the agent's. Done is yours. Assign the task to a person rather than an agent and none of that applies. A human moves their own task through the states by hand, the same as any task tracker. A Writesonic Agents task detail view showing the review banner, the brief, attached resources, subtasks and the properties rail Anything you attach to the brief sits under **Resources**, and anything the agent produces sits under **Artifacts**. The description locks while agents are working, so mid-flight direction goes in as a comment. ## Large tasks break into ordered subtasks The agent decides when one goal is really several. It creates the subtasks itself and the activity feed records each one as it appears. A subtasks panel showing three subtasks with IDs, titles, High priority, assignee avatars and dates Each subtask is a task in its own right, so you can open one and read its own feed. When one depends on another, they run in order. A subtask waiting on you shows as Pending Approval, and the parent waits with it, which is why a task can look stalled when it's actually waiting on a subtask. ## Done only happens after you accept the work Agents don't close their own work. That is deliberate. A finished deliverable stays In Review until you accept it as Done. CMS work still lands as a draft, so accepting the task doesn't publish it. ## An assigned task runs unless you stop it There's no start button. Assigning a task is what starts it. Cancel the task when you want the work to stop. ## What's next Choose how much you review. See what other teams hand over. # The agent team Source: https://apidocs.writesonic.com/agents/the-agent-team Meet the specialist agents for Research, SEO/GEO, Content, and Design, coordinated by a CMO agent. A broad marketing goal often hides several dependent jobs. Research has to exist before a claim can be written, and an audit has to identify the problem before anyone can fix it. ## Each agent is built around one discipline These are **discipline-built specialists**, not general-purpose assistants pointed at a marketing task. Each carries current knowledge of its field, has direct access to the data that field runs on, and works from playbooks based on what is working now. They can handle work outside their lane, but their own discipline is where they have the deepest context and judgment. | Agent | What it does | | - | - | | Research | Gathers external sources and turns them into structured, cited findings that other agents can use | | SEO/GEO | Diagnoses search and AI visibility using Google Search Console, Google Analytics, and your AI visibility data | | Content | Writes and edits in your brand voice and style using the Brand Kit | | Design | Makes visual decisions and produces assets using your brand guidelines and design system | The SEO/GEO agent also carries current guidance from Google core updates and AI assistants. Its playbooks reflect what is moving rankings and citations now, so it can connect a change in your data to the work most likely to address it. The Design agent is grounded in your visual system once. That gives it the constraints needed to make decisions instead of treating every asset as a blank brief. ## The CMO controls sequence without doing production work The CMO agent sits above the specialists, but it doesn't write, research, audit, or design. It takes a broad or ambiguous goal, breaks it into subtasks, and routes each one to the right specialist. It also enforces the order of work. If a content task depends on research and an SEO/GEO audit, content stays blocked until both inputs are complete. That sequencing matters when one request crosses several disciplines. The specialists do the work, while the CMO keeps their dependencies clear. The Writesonic Agents org chart with the CMO agent above Research, SEO/GEO, Design, and Content, plus a separate Off-page agents group marked Coming soon ## Shared context keeps specialist work coherent Every agent reads the same Brand Kit and Knowledge Base. You set that shared material once in [where context lives](/agents/where-context-lives), then each specialist applies it through the judgment of its own discipline. When you want to route work yourself, see [choosing an agent](/agents/choosing-an-agent). That page covers which specialist to assign. ## Off-page agents remain visible but unavailable Reddit, Outreach, and Digital PR appear in the product under Off-page agents. They're marked Coming soon and can't be assigned yet. ## What's next Choose the specialist whose discipline matches the work. See real tasks grouped by job. # Troubleshooting Source: https://apidocs.writesonic.com/agents/troubleshooting The things that actually go wrong, and what to do about each one. Match what you see to the section below, then follow the checks in order. ## Pages is empty or nearly empty right after setup This is expected. Search Console and Analytics backfill over the first few days. AI visibility builds as prompts run. Tasks work immediately, so [start there](/agents/what-to-expect). ## A task has sat In Progress for a while and nothing seems to be happening In Progress means the agent is working. Open the task's activity feed to see its steps, and allow several minutes for a first task. [Learn how task states work](/agents/tasks). ## Nothing has happened and the task is waiting on you There is no Blocked status. Tasks needing your input appear as Pending Approval or In Review. Those are the two states to watch in your [task list](/agents/tasks). ## The deliverable came back generic Thin context is usually the cause. Check the [Brand Kit](/agents/set-up-brand-kit), especially the audience and voice. Then check that the content type matches the format. Comment on the deliverable instead of rewriting the task, as explained in [writing good tasks](/agents/writing-good-tasks). ## The agent did the task but ignored the house rules for that format Format rules belong in content types, not the task description. See [where context lives](/agents/where-context-lives). ## A Knowledge Base page shows Sync failed Agents couldn't fetch the source. Select **Sync now** for that source, then check that the page is reachable and isn't blocked. See [Knowledge Base](/agents/knowledge-base). ## Work is not appearing in the CMS Confirm that a CMS connection exists and is assigned to this project. Work arrives as a draft, never as a published page. Look in your CMS drafts before reconnecting anything. See [publishing](/agents/publishing). ## A change was made and the numbers have not moved Whether a change worked is a 14 to 28 day question. First verify that the change shipped and the page was indexed. Then measure the result in the [activity log](/agents/activity-log). ## You cannot tell which of the two audit tools to use The AI crawler audit checks whether AI systems can reach and read your pages. The SEO audit checks technical and on-page health. ## A playbook produced a weak first result A playbook is only as specific as the description used to build it. Open the editor, tighten the steps, and run it on one row before running a grid. See [build a playbook](/agents/build-a-playbook). ## What's next What's normal early on. Every term, defined once. # What to expect Source: https://apidocs.writesonic.com/agents/what-to-expect What works on day one, what needs a few days of data, and why Pages looks empty at first. Tasks work from the moment setup finishes. The reporting screens don't, because they join data sources that need a few days of history before they show anything. This page says which screens are which. ## You can start work on day one Tasks are ready immediately. You don't need to wait for the dashboards to fill. An agent gathers what it needs while it works. We recommend starting with one task on day one. ## Pages needs a few days of data Pages follows a different timeline. It joins Google Search Console, Google Analytics, and AI visibility signals for each page. Those sources backfill over the first few days. If your Writesonic platform project is new, AI visibility data builds as prompts run on their schedule. A thin or empty Pages view right after setup is expected and isn't a fault. ## The first task can take a few minutes Your first task may sit In Progress for a few minutes. That status means the agent is working, not stuck. Open the activity feed to see what it's doing. ## Knowing whether it worked takes longer than knowing it shipped CMS work lands as a draft, so you can quickly confirm when the agent has finished. Nothing publishes on its own. Whether the change moved rankings or citations is a 14 to 28 day question because indexing and citation changes take time to appear. The [Tasks](/agents/tasks) page explains the full lifecycle and every status. ## A sensible first week follows a simple order 1. **Day one:** Connect Google Search Console and Google Analytics, complete your Brand Kit, then run one task. 2. **Day two or three:** Check Pages as its per-page records fill in. 3. **End of week one:** Turn whatever you repeated into a playbook. ## What's next See what other teams hand over. Learn the lifecycle and every status. # Where context lives Source: https://apidocs.writesonic.com/agents/where-context-lives Brand Kit, content types, Knowledge Base or the task description. A decision table for where a piece of context belongs. Context lives in several places, and each one has a different lifespan. An instruction typed into a task description applies to that task and stops there. ## Every place context can live has a different lifetime Brand Kit, content types, Knowledge Base and the task description, and what each is for Context has a lifetime. The Brand Kit carries company-wide truth into every task, for every agent. Content types carry format rules into work such as blog posts or LinkedIn posts. The Knowledge Base holds source documents, while the task description carries details for this job alone. Company-wide truth includes who you are, your audience, your voice, and your authors. The right place depends on **how long the context should keep applying**. ## Each place matches a different lifetime | Put it in | When it applies | Example | | - | - | - | | Brand Kit | Every task, across every agent | Company identity, audience, voice, and authors | | Content types | Whenever that format is produced | Blog posts use H2s for main sections | | Knowledge Base | When source documents are needed | A product brief or customer research | | Task description | This job only | Update this page from the attached file without changing its title | ## The Knowledge Base holds documents, not rules The Knowledge Base holds your own documents so agents can ground their work in them. Use it for source material and facts. Voice, formatting and standing instructions belong in the Brand Kit instead. ## Standing rules belong in the Brand Kit `Never mention a competitor by name` is a standing company rule, so put it in the Brand Kit. Every agent reads the Brand Kit on every task. If you keep pasting that instruction into task descriptions, its lifetime is wrong. The rule disappears when the task ends, and someone has to remember it next time. A company-wide rule you repeat per task belongs in the Brand Kit. ## What's next Work through the six sections. Learn what to put in a task description. # Writing good tasks Source: https://apidocs.writesonic.com/agents/writing-good-tasks Give a goal, not a procedure. The agent already knows your brand, so spend the description on what's specific to this job. A task description has one job: say what the finished work should be, and what it must respect. Brand background, audience profiles and voice rules don't belong in it, because the agent already reads them. ## Describe the outcome and let the agent plan the steps The agent plans its own steps, so describe the finished result and the limits it must respect. A required SOP is part of the job's input, so attach it instead of recreating its steps. | Instead of | Write | | - | - | | Audit our pricing page. | Audit `/pricing` for SEO issues affecting organic sign-ups. Use the attached keyword CSV and prioritize this quarter's fixes. | ## Your Brand Kit already carries the standing context The agent reads your [Brand Kit](/agents/set-up-brand-kit) on every task. It already knows who you are, your audience, your voice, and your authors. It also reads the rules you've set for each content type. Don't copy any of that into the task. If a rule should apply to every future task, change it in the Brand Kit. ## Put this job's specifics in the description The task description is for **job-specific context**. Name the exact page or keyword set, the deadline, and any constraint that changes the answer. Include the audience for this one piece when it differs from your usual audience. Attach source material the agent must use, such as a data CSV or an SOP. Anything with an exact answer is better [tagged than described](/agents/tagging-context). A playbook, an author, an audience or a knowledge base source goes in as a reference rather than a phrase the agent has to interpret. ## Comments preserve the work and its context When a deliverable misses the mark, leave feedback in its comments rather than rejecting it. Say what to redo, what to drop, and what to prioritise. The agent revises while keeping the context it already gathered. Rewriting the task from scratch throws that away. ## What's next Copyable examples for common marketing work. See how much you review. # Your first week Source: https://apidocs.writesonic.com/agents/your-first-week A sequenced plan: what to do on day one, what to check on day three, and what to turn into a playbook by Friday. Access on its own changes nothing. **The agents need context, and you need to have reviewed real work, before any of this becomes a habit.** ## Day one has two setup steps and one real task A first week timeline: connect and run one task, check Pages, then build a playbook Open Agents from the Writesonic sidebar with your existing account. Start by connecting Google Search Console and Google Analytics through [Connect your data](/agents/connect-your-data). Search Console is the one that's required. Add an analytics source too, so the agents can weigh work by business impact rather than traffic alone. Then complete your [Brand Kit](/agents/set-up-brand-kit). Integrations and Brand Kit are the whole setup. Once both are ready, open Pages and expect it to look thin or empty. Move to Tasks and run one real request you already planned to complete this week. ## Days two and three are for review and repetition Review the first deliverable on day two. Nothing publishes automatically, so the work reaches your CMS as a draft for a person to review. Add factual corrections and direction in the comments. Then run two or three more tasks, using [Writing good tasks](/agents/writing-good-tasks) to make each request clearer. Check Pages again on day three as its data fills in. ## Repetition becomes a playbook by Friday Whatever you asked for more than once is a playbook. Playbooks come last because they depend on having a task worth repeating. Use the task you already repeated as the basis for your first one. One proven loop is enough for Friday. ## Week one shows what shipped, not what worked By Friday, you'll know whether the agents produced useful work and whether a person reviewed it. You'll also know which CMS drafts were approved and shipped. That is an operating result, not a performance result. Whether the change moved rankings or citations is a 14 to 28 day question. ## What's next Choose what to run on day one. See what's thin at first, and why. # Authentication Source: https://apidocs.writesonic.com/api-reference/agents/authentication Programmatic access to Writesonic Agents: projects, tasks, playbooks, grids, knowledge base, and pages, over a simple API-key-authenticated REST API. The Agents API is the REST interface to [Writesonic Agents](/agents/overview). It exposes the same capabilities as the [Agents MCP server](/agents-mcp/mcp-server): read your projects, create and manage tasks, inspect playbooks and grids, search your knowledge base, and pull pages reports, all as plain HTTP endpoints you can call from any language. **Agents is in beta.** Access is currently limited to selected enterprise and agency accounts. To request it, talk to your account manager or [book a demo](https://writesonic.com/?demo=open) with our sales team. ## Base URL ``` https://api.agents.writesonic.com ``` All endpoints are mounted under `/api/v1/business`. Every request is a JSON `POST` (a few reads are `GET`), and every response is JSON. ## Authentication Every request requires your Writesonic API key in the `X-API-Key` header. ```bash theme={"system"} curl --request GET \ --url https://api.agents.writesonic.com/api/v1/business/whoami \ --header 'X-API-Key: ' ``` ### How to find your API key Go to [app.writesonic.com](https://app.writesonic.com) and sign in. Hover over your profile picture in the top-right corner and select **API Dashboard**. Switch the activation toggle **on** to enable API access. Click **Reveal API Key** and copy it. Never commit your API key to a public repository or ship it in client-side code. Use environment variables or a secrets manager. ## Scoping a request Your API key belongs to a **workspace** by default. Most endpoints act on a single **project** within it, which you name with a request header. | Header | Value | Required | | - | - | - | | `X-API-Key` | Your Writesonic API key | Always | | `X-Project-Id` | The project a request targets | For project-scoped endpoints | | `X-Workspace-Id` | Overrides the workspace your key defaults to | Optional | | `Content-Type` | `application/json` | For `POST` requests with a body | `GET /whoami` is the one call that needs no `X-Project-Id`. Call it first, it returns your identity, your teams, and the projects in the active workspace. Use a project's `id` from that response as the `X-Project-Id` header on every other call. ## Your first request ```bash theme={"system"} curl --request GET \ --url https://api.agents.writesonic.com/api/v1/business/whoami \ --header 'X-API-Key: ' ``` Copy the `id` of the project you want to work with from the `projects` array. ```bash theme={"system"} curl --request POST \ --url https://api.agents.writesonic.com/api/v1/business/tasks/query \ --header 'X-API-Key: ' \ --header 'X-Project-Id: ' \ --header 'Content-Type: application/json' \ --data '{"view": "list"}' ``` ## Error responses | Status | Meaning | | - | - | | `401` | Missing or invalid API key | | `403` | Key is valid but lacks access to the project or workspace | | `422` | Validation error in the request body or headers | | `429` | Rate limit exceeded | ## MCP or REST? The Agents API and the [Agents MCP server](/agents-mcp/mcp-server) are two front doors to the same tools. * Reach for **REST** when you're writing code, a backend job, a script, an integration. * Reach for **MCP** when you want an AI assistant (Claude, ChatGPT) to call these tools for you in natural language. Each REST endpoint below does the same job as one MCP tool. The [tools reference](/agents-mcp/tools-reference) lists the REST path for every tool. Send a tool's arguments as the top-level fields of the JSON body. MCP clients wrap them in an `args` object; the REST API does not. # Authentication Source: https://apidocs.writesonic.com/api-reference/authentication How to authenticate with the Writesonic GEO API using your API key. All API requests require an `X-API-KEY` header with your Writesonic API key. ```bash theme={"system"} curl --request POST \ --url https://api.writesonic.com/v2/geo/business/prompts \ --header 'Content-Type: application/json' \ --header 'X-API-KEY: ' \ --data '{ "project_id": "your-project-id" }' ``` ## How to Find Your API Key Go to [app.writesonic.com](https://app.writesonic.com) and sign in with your account. Hover over your profile picture in the top-right corner and select **API Dashboard** from the menu. Find the activation toggle and switch it **on** to enable API access. Click the **Reveal API Key** button. Your key will be displayed — click to copy it. Never commit your API key to public repositories (GitHub, GitLab, Bitbucket) or store it in client-side code. Use environment variables or a secrets manager. ## Base URL All GEO API endpoints use the following base URL: ``` https://api.writesonic.com ``` ## Authentication Header | Header | Value | Required | | - | - | - | | `X-API-KEY` | Your Writesonic API key | Yes | | `Content-Type` | `application/json` | Yes | ## Error Responses | Status Code | Meaning | | - | - | | `401` | Missing or invalid API key | | `403` | API key valid but insufficient permissions | | `422` | Validation error in request body | | `429` | Rate limit exceeded | # Comment on a task Source: https://apidocs.writesonic.com/api-reference/business/comment-on-a-task https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/tasks/comments Add a comment to a task's discussion. **Example:** "Add a comment to the task 'Fix login bug' saying 'started debugging'" **Usage:** pass the task id, set `action` to `create`, and provide the comment `body`. **Response:** the new comment with its id, author, body, timestamp, and any attachments. # Create a task Source: https://apidocs.writesonic.com/api-reference/business/create-a-task https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/tasks Add a brand-new task to the project. This only ever adds: it never overwrites existing data, and the new task shows up in the product like any other. **Example:** "Create a task titled 'Write Q3 launch brief'" **Usage:** give the new task a title (the only required field). You can also set its description, status, priority, due date, assignee, parent task (to make it a subtask), labels, and any files to attach on creation. **Response:** the created task, including its generated id and identifier along with the status, priority, assignee, and other fields it was created with. # Get a workflow Source: https://apidocs.writesonic.com/api-reference/business/get-a-workflow https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/workflows/get Get a single workflow together with a chosen slice of its related data: its details, its versions, one version in full, its run history, or one run in full. **Example:** "Show me the details of the FAQ Suggester workflow" **Usage:** give the workflow id and pick the slice with `view`: `detail` for the workflow itself, `versions` for its version history, `version_detail` for one version (needs the version id, and you can leave out the builder chat history), `runs` for its run history, or `run_detail` for one run (needs the run id). For runs you can filter by status, by where the run came from (a standalone playbook run, a grid cell, or a task), by a name search, or by when they were created, and the version and run lists come back in pages of up to 100 (50 by default). **Response:** the workflow and whichever slice you asked for: its details, a list of versions, one version's step config and chat, a list of runs, or one run's status and progress. # Get attachment download URL Source: https://apidocs.writesonic.com/api-reference/business/get-attachment-download-url https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/attachments/download-url Get a short-lived link for downloading a file attached to a task or a comment. **Example:** "Give me a download link for this attachment" **Usage:** say where the file lives with `target` — a task (needs the task id) or a comment — and pass the attachment id. The link is presigned and expires after a short while, so use it promptly. **Response:** the download link plus the file's name, content type, and when the link expires. It does not return the file contents themselves. # Get brand kit Source: https://apidocs.writesonic.com/api-reference/business/get-brand-kit https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/brand-kit Get the project's brand kit: list the names of its sections, or compose the brand content into a ready-to-use prompt. **Example:** "What sections does my brand kit have?" **Usage:** pick what you want with `view`: `catalog` lists the section names only, `compose` returns one combined brand prompt, `compose_by_section` returns the same content split per section, and `compose_image_prompt` turns the brand's design section into an image prompt (give it a subject, aspect ratio, and whether to let the service expand a thin subject). For the compose views you can tailor the result by section keys, content type, author, audience, or voice. **Response:** for catalog, the section names. For the compose views, the composed brand prompt, either as one block, split per section, or as an image prompt. # Get caller identity and projects Source: https://apidocs.writesonic.com/api-reference/business/get-caller-identity-and-projects https://mcp.agents.writesonic.com/openapi.json get /api/v1/business/whoami Tells you who is calling: their identity, the HQ teams they belong to, and the projects in the workspace they are currently in. **Example:** "Who am I? Show my account identity" **Usage:** call this first, before anything else. It takes no input and it hands you the project ids you need to scope every other call to a specific project. **Response:** your profile (name, email, role, teams), the active workspace id, and the list of projects in that workspace with each project's id, name, and website. # Get content-intelligence dashboard Source: https://apidocs.writesonic.com/api-reference/business/get-content-intelligence-dashboard https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/content-intelligence/dashboard Returns project-level content-intelligence data for the dashboard: page and live-tracking summaries, the available filters and countries, the ranked list of tracked pages, page groups, and the columns shown in the page list. **Example:** "List the Pages I'm tracking" **Usage:** pick what you want with `view`: summary and live_summary for the headline numbers, countries and filters for the choices you can filter and sort by, pages for the ranked page list, groups for named page groups, and column_scope for the page-list columns. Scope the numbers with a market and a date window, and narrow the page list by search text, status, keyword intent, or group. The page list comes back in pages of up to 100 (50 by default). Use view=pages with a URL or title in search to find the page id other reports need, and view=filters to learn the real sort keys and ready-made presets before sorting. **Response:** the data for the chosen view: summary metrics, the list of countries or filters, the ranked pages with their metrics, the page groups, or the page-list columns. # Get page content-intelligence report Source: https://apidocs.writesonic.com/api-reference/business/get-page-content-intelligence-report https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/content-intelligence/page-report Returns a detailed content-intelligence report for a single tracked page, covering SEO performance, AI citations, conversion funnels, traffic, SERP position, keywords, page lifecycle, or activity. **Example:** "Show me the SEO performance report for this page" **Usage:** pick the report you want with `report_type` and pass the id of the page to report on. The keyword, SERP, and target-keyword reports need a market to be chosen. Scope the numbers with a date window, and for the AI-citations and keyword reports you can narrow by search text. The longer reports come back in pages of up to 100 (50 by default). Find the page id first by listing pages on the dashboard with the page URL or title. **Response:** the requested report for that page: its metrics, trends, and the supporting rows for the chosen report type. # Get task detail Source: https://apidocs.writesonic.com/api-reference/business/get-task-detail https://mcp.agents.writesonic.com/openapi.json get /api/v1/business/tasks/{task_id} Get everything about one task, always including its attachments and labels, and optionally its activity timeline, its links to other tasks, and any pending approvals. **Example:** "Show me the full detail of the task 'Fix login bug'" **Usage:** pass the task id. Add anything extra you want to `include`: `timeline` for the activity feed, `relations` for links to other tasks, and `approvals` for pending sign-offs. When you include the timeline it comes back a page at a time; pass the cursor from the previous response to get the next page, and use `timeline_kind` to narrow it to just comments, activity, approvals, or workflow events. **Response:** the task with its status, priority, assignee, dates, counts, attachments, and labels, plus whichever of timeline, relations, and approvals you asked for. # List integrations Source: https://apidocs.writesonic.com/api-reference/business/list-integrations https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/integrations/query Lists the third-party apps and integration connections available to the workspace: browse the catalogue of supported apps, see connections grouped by app with active and inactive counts, or list individual connections. **Example:** "What integrations are available to connect?" **Usage:** pick what you want with `view`: apps for the full catalogue of supported apps, apps_overview for connections grouped by app with active and inactive counts, connections for the individual connections, and connection_detail for one connection (needs its id). Narrow the lists with free-text search, and connections also by app, status, or whether they have project access; pass a project id to scope either list to one project. The lists come back in pages of up to 100 (50 by default). Credentials are never returned. **Response:** the data for the chosen view: the app catalogue, the per-app overview with counts, the list of connections, or one connection's details. # List or read grids Source: https://apidocs.writesonic.com/api-reference/business/list-or-read-grids https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/grids/query List the grids in a project, look at one grid's setup or its processing status, or see the column types you can add to a grid. **Example:** "What grids do I have going in this project?" **Usage:** choose what you want with `view` — the grid inventory (`list`), one grid's full setup (`detail`, needs the grid id), its processing status (`status`, needs the grid id), or the catalog of column types you can add (`column_options`). The inventory comes back in pages of up to 100 (50 by default) and can be narrowed by name, workflow, or who created it, and ranked by newest, most recently updated, or by how many rows sit in a given state (for example to surface the grids with the most failed rows first). **Response:** for the inventory, a page of grids, each with its name, when it was created, its row and column counts, and how many rows sit in each processing state. Detail adds the grid's columns and its saved sort and filter; status returns the counts plus who is editing it right now. Column options lists each addable type with its name and description. # List or read knowledge sources Source: https://apidocs.writesonic.com/api-reference/business/list-or-read-knowledge-sources https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/knowledge/sources List the project's knowledge sources or the folders that organize them, or read the full content of one source. This does not cover the brand kit, which is a separate resource. **Example:** "What knowledge sources have I uploaded?" **Usage:** pick what you want with `view`: `list` for the sources, `folders` for the folders (id and name, handy for turning a folder name into its id), or `content` for one source's parsed text (needs the source id). When listing you can narrow by folder, by origin (web url, website, file, or document), by sync status, by workflow status, by tag, or by a text search over the title or filename, and page through the results with a cursor and a limit. **Response:** for list, the matching sources with their status and details. For folders, each folder's id and name. For content, the parsed text of the source. # List project resources Source: https://apidocs.writesonic.com/api-reference/business/list-project-resources https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/project-resources/query Looks up the reference things that belong to a project, such as its people, labels, settings, skills, and agents. **Example:** "List the users in my project" **Usage:** pick what you want with `resource`: users, labels, settings, skills, agents, or agent_settings. By default you get the full list. To see the details of one item instead, add its `resource_id` (supported for users, skills, and agents only). For users, pass the id whoami gave you as `resource_id` to read your own record in this project, like your role here. Longer lists come back in pages. **Response:** the matching items for the resource you chose, or the full details of a single item when you pass a resource_id. # List workflow components Source: https://apidocs.writesonic.com/api-reference/business/list-workflow-components https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/workflows/components List the building blocks used to assemble workflows: the catalog of available components, a specific set of components fetched by id, or the capabilities offered by the workflows hub. **Example:** "List the workflow building blocks I can add to a workflow" **Usage:** pick what you want with `view`: `hub_capabilities` for a compact list of every building block (optionally narrowed to one skill or one capability id), `components` for the same blocks with their full input and output schemas (with an optional text search; responses are large, so keep the page small), or `batch` to fetch the full schemas of specific blocks by their capability ids. The lists come back in pages of up to 100 (50 by default); ask for the next page by its number. **Response:** the matching building blocks, each with its id, name, and description; components and batch results also carry each block's input and output schemas. # List workflows Source: https://apidocs.writesonic.com/api-reference/business/list-workflows https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/workflows/query List the workflows in a project as a filterable inventory, or get the counts of workflows grouped by status. **Example:** "pull up all my playbooks" **Usage:** pick what you want with `view` — `list` for the inventory or `counts` for the status totals. For the list you can narrow by type (the curated system playbooks or the ones users built), by the latest version's status, or by a text search over names, and you can sort by the field you choose. The list comes back in pages of up to 100 (50 by default); ask for the next page by its number. **Response:** for the list, each workflow with its name, type, latest version status, and timings. For counts, the number of workflows in each status. # Query agent runs Source: https://apidocs.writesonic.com/api-reference/business/query-agent-runs https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/agent-runs/query See the history of agent runs for a task or an agent, or follow the step-by-step progress of a single run. **Example:** "Show the agent run history for the task 'Fix login bug'" **Usage:** choose what you want with `scope` — the runs of a task (needs the task id), the runs of an agent (needs the agent id), or the live progress of one run (needs the task id and the run id). The run lists come back in pages of up to 100 (50 by default); pass the cursor from the previous page to get the next one. **Response:** a list of runs, each showing its status, what triggered it, when it started and finished, and how many tokens it used. A progress request returns the run's steps in order. # Query tasks Source: https://apidocs.writesonic.com/api-reference/business/query-tasks https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/tasks/query Search and list the project's tasks, or get grouped totals across them. **Example:** "Show me the in-progress tasks in this project" **Usage:** set `view` to `list` for the matching tasks or `counts` for grouped totals. Narrow results with `query.filter` on fields like status, priority, assignee, labels, due date, and title, and order a list with `query.sort`. Lists come back in pages of up to 100 (50 by default); pass the cursor from the previous page to get the next one. For `counts`, set `group_by` (status, priority, assignee_id, or creator_id) - it is required for that view. **Response:** for a list, a page of tasks with their core fields, labels, and subtask counts plus a cursor for the next page. For counts, the total and a per-group breakdown keyed by the field you grouped on. # Read grid data Source: https://apidocs.writesonic.com/api-reference/business/read-grid-data https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/grids/data Read what is inside a grid: its columns, its rows, a single cell, the run behind a computed cell, or the rows matching a search. **Example:** "Show me the columns of the 'FAQ Suggester v2 Grid' grid" **Usage:** pick what to read with `view` and always pass the grid id. `columns` lists the grid's columns; `rows` returns the data a page at a time (up to 200, 50 by default) and can be limited to certain columns or specific rows; `cell` and `cell_run` open one cell (both need the row id and column id, and `cell_run` also needs the run id); `row_search` finds rows matching your text (needs the search text). **Response:** columns come back with their names and types; rows come as a page of cell values tagged with the grid version; a cell returns its value, status, and the run that produced it; a cell run returns its inputs, status, and version; a search returns the row-and-column matches. # Search knowledge sources Source: https://apidocs.writesonic.com/api-reference/business/search-knowledge-sources https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/knowledge/search Search across the project's knowledge sources and get back the most relevant passages, optionally with a generated answer written from them. **Example:** "Search my knowledge base for anything about refund policy" **Usage:** give the search text and say how many passages you want back (5 by default). Ask for a generated answer or turn it off to get the raw passages only. You can narrow the search to specific sources, folders, or tags, or to sources in certain workflow statuses; leave those out to search the whole project. Only sources that have finished syncing are searchable, so a whole-project search already skips ones still queued, syncing, or failed. **Response:** the matching passages with their source, and, when asked for, a generated answer written from them. # Update a task Source: https://apidocs.writesonic.com/api-reference/business/update-a-task https://mcp.agents.writesonic.com/openapi.json post /api/v1/business/tasks/update Change an existing task: edit its fields, move it to a different status, or assign it to someone. Every change here is reversible. **Example:** "Mark the task 'Fix login bug' as done" **Usage:** pass the task id and pick what to do with `action`. `update_fields` edits the task and needs `fields` with just the values that change; `transition_status` needs the new `status`; `assign` needs the `assignee` (a person, an agent, or unassigned). **Response:** the updated task with its new field values. # Get AI Models Source: https://apidocs.writesonic.com/api-reference/generic/get-ai-models https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/models Get the list of tracked AI models/platforms (metadata only, no performance metrics). **Example:** "Which AI platforms are being monitored?" Returns name and icon for each model. **Metrics:** None — use `/reports/performance` with `model` dimension for metrics. **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`, `name`. **Sort fields:** `name`. **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). # Get All Citations Source: https://apidocs.writesonic.com/api-reference/generic/get-all-citations https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/citations List 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_`. **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). # Get All Projects Source: https://apidocs.writesonic.com/api-reference/generic/get-all-projects https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/projects Get all projects that have geo presence tracking enabled. ALWAYS call this first — every other tool needs a `project_id`, and this is the only place to get one. **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 (read carefully):** - 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). - Resolve it ONCE and REUSE the same `id` — do not re-list projects or change it unless the user switches projects. - You already have the id from this response: NEVER stop to ask the user for the project id, and never treat a project's `name` or `url` as the id. - If exactly one project is returned, use its `id` directly without asking. **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. # Get All Prompts Source: https://apidocs.writesonic.com/api-reference/generic/get-all-prompts https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/prompts List 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). # Get All Topics Source: https://apidocs.writesonic.com/api-reference/generic/get-all-topics https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/topics List 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). # Get Domain Reports Source: https://apidocs.writesonic.com/api-reference/generic/get-domain-reports https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/domains Browse 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). # Get Keywords Source: https://apidocs.writesonic.com/api-reference/generic/get-keywords https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/keywords Browse 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). # Get Markets Source: https://apidocs.writesonic.com/api-reference/generic/get-markets https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/markets Browse 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). # Get Tags Source: https://apidocs.writesonic.com/api-reference/generic/get-tags https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/tags List 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). # Get Websites Source: https://apidocs.writesonic.com/api-reference/generic/get-websites https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/business/websites Compare 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). # Get Ads Report Source: https://apidocs.writesonic.com/api-reference/reports/get-ads-report https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/reports/ads Sponsored-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_` 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 weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive. # Get Citation Report Source: https://apidocs.writesonic.com/api-reference/reports/get-citation-report https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/reports/citations Citation 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_` 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). # Get Performance Report Source: https://apidocs.writesonic.com/api-reference/reports/get-performance-report https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/reports/performance Brand 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_` 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. # Get Sentiment Report Source: https://apidocs.writesonic.com/api-reference/reports/get-sentiment-report https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/reports/sentiments Keyword 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` **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_` 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). # Get Shopping Report Source: https://apidocs.writesonic.com/api-reference/reports/get-shopping-report https://api.writesonic.com/v1/oauth/openapi.json?client_secret=FgwCVph3cjZy0KPsvsuU post /v2/geo/reports/shopping Shopping-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_` 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 weighted by how many of its links point at that merchant). `AD_SHOPPING` placements count in both this report and the other one, so shopping and ad totals are not additive. # Action Center: Actionables Source: https://apidocs.writesonic.com/docs/action-center-actionables The Action Center is your strategic command hub for maximizing brand visibility across AI-powered search engines including ChatGPT, Claude, Google AI Overviews, Perplexity, and Gemini. Let’s get you started with your first optimization in under 5 minutes. ### Step 1: Access Your Dashboard Navigate to the Action Center from your Writesonic GEO main menu. You’ll see three key metrics: * **Unresolved Items**: Total optimization opportunities available * **In-Progress Items**: Actions you’ve started working on * **Resolved Items**: Completed optimizations ### Step 2: Understanding Priority Scores Each action displays two critical indicators: * **Effort Level** (1-3 bars): Time and resources required * **Impact Level** (Low/Medium/High): Potential visibility improvement Start with High Impact, Low Effort items for quick wins. ### Step 3: Take Your First Action 1. Click “Address now” on any high-priority item 2. Follow the guided workflow specific to that action type 3. Mark as complete when done **Success Milestone**: Complete one optimization action and see it reflected in under **Impacts and results**. *** ## Understanding the Action Center ### What Problems Does It Solve? Traditional SEO focuses on Google rankings, but AI models are increasingly how users discover information. When someone asks ChatGPT about “best design tools,” your brand needs to appear in that response. The Action Center identifies exactly why you’re not appearing and provides step-by-step solutions. ### How AI Visibility Differs from Traditional SEO | Traditional SEO | AI Visibility (GEO) | | - | - | | Focuses on keywords | Focuses on factual accuracy and citations | | Targets one search engine | Targets 10+ AI platforms simultaneously | | Relies on backlinks | Relies on authoritative mentions | | Monthly algorithm updates | Real-time learning models | ### Your Visibility Dashboard Explained The Action Center analyzes your brand’s presence across AI platforms and organizes improvement opportunities into three strategic categories: 1. **Technical Issues** - Barriers preventing AI from accessing your content 2. **External Mentions** - Opportunities to earn citations from authoritative sources 3. **Content Visibility** - Content gaps and optimization opportunities *** ## Category 1: Get External Mentions(**Off-Page**) External mentions are the foundation of AI visibility. When authoritative sites mention your brand, AI models consider you more credible and citation-worthy. ### Get Mentioned on High-Authority Third-Party Sites **What You’ll See:** A list of URLs where competitors are mentioned but your brand isn’t. Each entry shows: * The citing page URL * Domain Rating (authority score) * Number of missed opportunities * Competitors mentioned * Platform icons showing which AI models use this source **Taking Action:** 1. **Review the Opportunity** * Click on any URL to see the full context * Understand how competitors are being mentioned * Assess if this aligns with your brand positioning 2. **Draft Your Outreach** * Click “Draft email” to access the platform's email template that you can customize with your unique value proposition. * Focus on the value you can provide to their audience 3. **Execute Outreach** * Send directly from the platform or copy to your email client * Platform tracks which URLs you’ve contacted * Set follow-up reminders as needed 4. **Track Results** * Mark outreach as “Done” when completed * View progress in the “Impacts and Results” tab * Platform automatically detects when citations go live * See real-time visibility improvements in your metrics **Pro Tips:** * Prioritize domains with ratings above 70 for maximum impact * Personalize every outreach message - generic templates have 3x lower success rates * Focus on providing genuine value, not just requesting mentions * Follow up after 7-10 days if no response ### Detailed Outreach Process **Phase 1: Opportunity Research (15 minutes per opportunity)** 1. **Initial Analysis** ``` Open the cited page and document: - Article title and publication date - Author name and contact information - Last update timestamp - Total number of brands/tools mentioned - Your brand's relevance to the content ``` 2. **Competitor Positioning Analysis** * Note how each competitor is described * Identify unique selling points highlighted * Find gaps your brand could fill * Document any outdated information about competitors 3. **Contact Research** * Find author’s email (check author bio, about page, or LinkedIn) * Identify the appropriate editor if author isn’t available * Note their writing style and tone * Check their recent articles for context **Phase 2: Crafting Your Outreach (10 minutes)** Create a personalized email using this enhanced template: **Phase 3: Systematic Follow-Up** **Day 0 (Initial send):** * Send email Tuesday-Thursday, 9-11 AM recipient time zone * Mark as “sent” in Action Center * Add to your CRM or tracking spreadsheet **Day 7 (First follow-up):** ``` Subject: Re: [Original subject] Hi [Name], Just floating this back to the top of your inbox. I know how busy things get! [One new piece of value - data point, news, or asset] Would you like me to send over those resources I mentioned? Best, [Your name] ``` **Day 14 (Final follow-up):** ``` Subject: Re: [Original subject] - Final check Hi [Name], I'll close the loop on this - if the timing isn't right or if [Brand] isn't a fit for your article, no worries at all. If you're ever updating content on [related topics], I'd be happy to contribute insights from our [specific expertise]. Thanks for your time and for creating such valuable content for the [industry] community. Best, [Your name] ``` ### Earn Mentions on UGC & Community Sites **What You’ll See:** Community platforms where your expertise could earn natural mentions: * Reddit threads in your industry * Quora questions you can answer authoritatively * Stack Overflow technical discussions * Industry-specific forums and communities **Taking Action:** 1. **Identify Relevant Discussions** * Review suggested threads and discussions * Look for questions where you have genuine expertise * Check recency - prioritize active discussions 2. **Engage Authentically** * Create accounts with complete, professional profiles * Provide valuable answers without being promotional * Include your brand naturally only when directly relevant * Build reputation before mentioning your product 3. **Build Long-term Presence** * Consistency matters more than volume * Aim for 2-3 high-quality contributions weekly * Become a recognized expert in specific communities * Help others genuinely - citations follow naturally **What to Avoid:** * Promotional language or obvious marketing * Copy-pasting the same response across platforms * Creating multiple fake accounts * Arguing or being defensive about your brand ### Platform-Specific Strategies **Reddit Optimization** 1. **Subreddit Selection Process** ``` Evaluate subreddits by: - Member count (enough number of members i.e. >1500) - Daily active discussions - Relevance to your expertise - Moderation strictness - Historical AI citation frequency ``` 2. **Contribution Strategy** * **Week 1-2:** Observer phase - read without posting * **Week 3-4:** Helper phase - answer questions without any brand mention * **Week 5+:** Authority phase - occasional relevant brand mentions 3. **High-Value Comment Structure** ``` Opening: Personal experience or empathy with the question Main value: Detailed solution with steps: 1. [First step with explanation] 2. [Second step with reasoning] 3. [Third step with expected outcome] Evidence: "In my experience with [relevant context]..." Additional resources: Mix of helpful links (only 20% yours) Engagement: "Happy to clarify anything - dealt with this for years" ``` **Quora Optimization** 1. **Question Selection Criteria** * View count: 1,000+ * Answer count: Less than 5 quality answers * Recency: Asked within last 60 days * Followers: 10+ people following question 2. **Answer Structure for Maximum Citations** ``` Bold Opening Statement (1 sentence answer) Context Paragraph (why this matters) Detailed Explanation: • Main point with evidence • Secondary point with example • Counter-argument addressed Real-World Application: [Specific scenario or case study] Tools/Resources Section: - [Your solution if genuinely relevant] - [Alternative solutions] - [Additional learning resources] Credentials: [Brief qualifier of your expertise] ``` **Stack Overflow and Technical Forums** 1. **Contribution Requirements** * Provide working code solutions * Include error handling * Explain the “why” not just “how” * Follow community formatting standards 2. **Reputation Building Timeline** * Month 1: Focus on answering, gain 100+ reputation * Month 2: Start asking quality questions too * Month 3: Occasional tool/solution mentions where relevant *** ## Category 2: Boost Content Visibility(**On-Page**) Content optimized for AI citations follows different rules than traditional SEO. The Action Center identifies what’s working and guides you to create citation-worthy content. ### Create Content Inspired by Websites Winning in AI Citations **What You’ll See:** A curated list of content opportunities based on actual AI citation data: * Topic ideas with citation frequency scores * Content types that perform best (guides, comparisons, tutorials) * Competitor content gaps you can fill * Estimated impact on AI visibility **Taking Action:** 1. **Choose Your Topic** * Filter by your expertise areas * Prioritize topics with 100+ citation instances * Check if you have unique insights to add * Verify you haven’t already covered this topic 2. **Create with Article Editor 6** * Click “Write” to launch the Article Writer 3. **Optimize for AI Extraction** **Content Formats That Win Citations:** | Format | Best For | Citation Rate | | - | - | - | | Ultimate Guides | Comprehensive coverage | High | | Comparison Articles | Product/service evaluations | Very High | | Statistical Roundups | Data-driven insights | High | | How-to Tutorials | Step-by-step processes | Medium | | Industry Reports | Original research | Very High | ### Refresh Existing Content for AI Visibility **Status: Coming Soon** This feature will analyze your existing content library and provide specific optimization recommendations: * Content restructuring for better AI comprehension * Fact extraction improvements * Citation-friendly formatting updates * Freshness signals and timestamp optimization * Internal linking enhancements *** ## Category 3: Fix Technical Issues Technical barriers can completely prevent AI models from accessing your content. These fixes often provide the fastest visibility improvements. ### Fix Broken or Non-Indexable Pages **Understanding the Challenge:** AI bots don’t execute JavaScript or use browsers like humans do. They need server-side responses to access your content. Many sites accidentally block these bots without realizing it. **Required Setup:** 1. **Enable Server-Side Tracking** * Choose your platform integration: * **Cloudflare**: One-click setup through dashboard * **WordPress**: Install the GEO tracking plugin * **Vercel**: Add to your deployment configuration * **Custom**: Use our API for other platforms 2. **Why This Matters** * Google Analytics can’t see AI bot traffic * AI bots don’t render JavaScript * Server-side tracking captures all bot interactions * Identifies exactly which pages have issues **What You’ll Discover:** * Pages returning 404 errors to AI bots * Internal server errors (500-series) * Redirect chains confusing crawlers * Authentication walls blocking access * Rate limiting preventing indexing **Taking Action:** 1. **Review Error Report** * Sort by error frequency * Identify patterns in problematic URLs * Check error codes and timestamps 2. **Prioritize Fixes** * Start with your most important content * Fix systematic issues before individual pages * Address 404s from external links first 3. **Implement Solutions** * Restore missing pages or create redirects * Fix server configuration issues * Ensure proper URL structures * Remove authentication requirements for public content ### Fix Robots.txt Blocking AI Crawlers **The Hidden Problem:** Over 60% of websites unknowingly block AI crawlers through restrictive robots.txt files, eliminating any chance of AI citations. **What You’ll See:** * Current robots.txt configuration analysis * List of blocked AI bots (GPTBot, Claude-Web, etc.) * Estimated visibility loss from blocking * Specific line-by-line recommendations **Understanding AI Bot User Agents:** | Bot Name | User Agent | Platform | | - | - | - | | GPTBot | GPTBot/1.0 | ChatGPT | | Claude-Web | Claude-Web/1.0 | Claude | | PerplexityBot | PerplexityBot/1.0 | Perplexity | | Google-Extended | Google-Extended | Google AI | **Taking Action:** 1. **Review Current Configuration** ``` # Common problematic configuration User-agent: * Disallow: / ``` 2. **Implement Recommended Changes** ``` # AI-friendly configuration User-agent: GPTBot Allow: / User-agent: Claude-Web Allow: / User-agent: PerplexityBot Allow: / ``` 3. **Balance Security and Visibility** * Allow AI bots to access public content * Maintain blocks on sensitive directories * Use crawl-delay for rate limiting if needed * Test changes before deployment 4. **Verify Implementation** * Use robots.txt testing tools * Monitor bot traffic after changes * Check for increased crawl activity * Track citation improvements *** ## Best Practices for Maximum Impact ### Prioritization Framework **The ICE Method for Action Selection:** * **Impact**: How much will this improve visibility? * **Confidence**: How certain are we of success? * **Effort**: How much work is required? Focus on actions scoring high on Impact and Confidence but low on Effort. ### Execution Timeline **Week 1-2: Technical Foundation** * Fix all robots.txt issues * Resolve critical broken pages * Setup server-side tracking **Week 3-4: Quick Wins** * Complete high-authority outreach (5-10 sites) * Publish 2-3 GEO-optimized articles * Begin community engagement **Month 2: Scale and Optimize** * Expand outreach to 20+ opportunities * Create comprehensive content cluster * Establish regular community presence **Month 3+: Sustain and Grow** * Monitor and maintain technical health * Continue content production rhythm * Build lasting community relationships *** [Citation Opportunities](/docs/citation-opportunity) [Content Optimization](/docs/content-optimization) # AI Search Basics: What It Is & How It Works Source: https://apidocs.writesonic.com/docs/ai-search-visibility ## What is AI Search? If you're here, you've probably noticed something: AI is changing how people find information online. Let's understand what's actually happening under the hood. ### How People Search Has Changed **Traditional Google Search:** * User types keywords: "CRM software" (2-3 words) * Google shows 10 blue links * User clicks one * You track the visit **AI Search:** * User asks: "What's the best CRM for a 10-person remote marketing team that integrates with Slack?" * AI reads multiple sources * Creates one synthesized answer * Maybe mentions you, maybe doesn't * You might never know People don't type keywords anymore. They have conversations. They provide context. They expect personalized answers. ## How AI Search Actually Works (RAG) AI search uses Retrieval Augmented Generation (RAG) to provide answers. Here's what happens step by step: **1. Question Analysis** * AI understands what you're really asking * Identifies key entities, intent, and context * Expands the question to capture related concepts **2. Document Retrieval** * Searches pre-built web indexes (not the live web!) * Uses vector search to find semantically similar content * Retrieves relevant passages from multiple sources **3. Content Evaluation** * Judges quality, relevance, and authority of sources * Filters out low-quality or outdated information * Prioritizes trusted domains and recent content **4. Answer Generation** * Synthesizes information from selected sources * Creates coherent response in natural language * Decides whether to include citations (usually doesn't) **5. Learning** * Improves from user feedback and interactions (remember the thumbs up/down buttons next to ChatGPT answers?) * Adjusts ranking and selection algorithms * Updates understanding of what makes good answers Think of it like a DJ mixing tracks - AI pulls content from different sites and mixes it into one answer. But most of the time, it forgets to credit the original artists. ### Where AI Gets Its Information **Critical insight:** AI doesn't crawl the live web. Each platform uses different pre-built indexes: | Platform | Index Source | | - | - | | ChatGPT | Bing + proprietary | | Perplexity | Google's index | | Claude | Own crawled data | | Google AI Overviews | Google's index | | Gemini | Google's index | This means your brand new content won't appear immediately - it needs to be indexed first by the underlying search engine. ### Google's Query Fan-Out Method Google AI Overviews and the upcoming AI Mode do something unique - they expand one query into many. When someone searches "best CRM software," Google AI generates 20+ related searches behind the scenes: * CRM pricing comparison * CRM features for small teams * CRM integration capabilities * CRM user reviews * CRM setup complexity * CRM customer support quality Your content ranking #50 for the main term might rank #2 for "CRM API capabilities" and get included. This is why comprehensive content wins - you need to match the entire query universe, not just one keyword. ### When AI Decides to Search Based on leaked Claude documentation, AI has 4 search modes: 1. **Never Search** - Uses pre-trained knowledge (you can't influence this) 2. **Offer Search** - Varies by model (unpredictable) 3. **Single Search** - Most common, handles 80% of queries (your main opportunity) 4. **Research Mode** - Complex queries needing 2-20 searches (growing opportunity) Focus your efforts on Single Search and Research Mode - these are where you can actually make an impact. ## What's Different About AI Search ### Key Differences from Traditional SEO | Aspect | Traditional SEO | AI Search (GEO) | | - | - | - | | **User Input** | Keywords (2-3 words) | Prompts (15-25 words) | | **Goal** | Rank in top 10 | Get mentioned at all | | **Competition** | 10 spots on page 1 | Unlimited mentions possible | | **Traffic** | Direct clicks | Brand awareness → searches | | **Updates** | Monthly algorithm changes | Daily volatility | | **Trust Signals** | Backlinks | Third-party mentions | **Now that you understand how AI search works differently**, let's learn the new vocabulary you'll need to navigate this world - from prompts to citations and everything in between. *** What’s Next * [AI Search Vocabulary & Metrics \[Very Important\]](/docs/ai-search-vocabulary-concepts-very-important) # AI Search Vocabulary & Metrics [Very Important] Source: https://apidocs.writesonic.com/docs/ai-search-vocabulary-concepts-very-important Let's understand what we're actually looking at when we track AI search. Here's a typical ChatGPT interface with the key components labeled: **Orange box (Prompt):** The question a user types - "what are the best project management tools". **Red box (Answer):** The AI-generated answer listing tools like Asana and Trello. **Yellow highlight (Mention):** Where brands get mentioned within the answer. **Green box (Citations):** The sources AI references, sometimes with clickable links. These are of 2 kinds - ones shown on the "Citations" side panel as well those shown in-line in the answer itself. ### Core Terms: From SEO to AI Search Traditional SEO has keywords, rankings, and SERPs. AI search has its own vocabulary. Let's translate what these terms mean and why they matter for your strategy. | SEO Term | AI Search Term | What It Actually Means | | - | - | - | | **Keyword** | **Prompt** | The conversational questions users type into AI platforms. Instead of "CRM software," think "what CRM should I use for my 10-person startup?" | | **SERP** | **Answer** | The synthesized answer AI creates from multiple sources. Not a list of links, but a complete answer. | | **Ranking Position** | **Mention Position** | Where you appear within the AI's answer - 1st paragraph, 2nd, or buried at the end. | | **Organic Traffic** | **AI Visibility** | How often your brand appears across all AI answers. Measured as a percentage, not visits. | | **Backlinks** | **Citations** | When AI references your content as a source. May include a link, or just mention your brand. | | **Click-Through Rate** | **Citation Click Rate** | How often users click on your citations when provided. Usually much lower than traditional CTR. | | **Domain Authority** | **Citation Authority** | How trustworthy AI considers your domain based on who else cites you. | ### Additional AI Search Terms **Answers Mentioned** The total count of AI answers where your brand appears. Different from visibility percentage - this is the raw number. **Answer Variations** When the same prompt gives different answers across platforms or time. Normal volatility can be 30%+ daily. **Query Fan-Out** (Google AI only) When one search becomes 20+ sub-queries behind the scenes. **Mention Sentiment** Whether AI describes your brand positively, negatively, or neutrally in its answer. **Source Type** Classification of citing domains: * Your brand (your own website's pages) * Competitor (direct competitor sites) * Third party (independent sources) **Citation Gap** Website sources that mention your competitors but not you - your biggest opportunity. ## Key AI Search Metrics Explained Now let's understand the numbers that actually matter in AI search. ### Visibility Score **What it measures:** The percentage of tracked answers where your brand appears. **How it's calculated:** * Answers where you're mentioned ÷ Total answers tracked × 100 * Example: Mentioned in 57 out of 100 answers = 57% visibility **What good looks like:** * 🟢 **Excellent**: Above 70% * 🟡 **Good**: 40-70% * 🔴 **Needs work**: Below 30% **Why it matters:** If you're not mentioned, you don't exist in AI search. This is your most fundamental metric. ### Answers Mentioned **What it measures:** The absolute number of AI answers that include your brand. **Example from dashboard:** 354 responses mentioned Canva **How it relates to visibility:** * 354 responses mentioned ÷ 604 total responses = \~57% visibility This raw count helps you understand volume, while visibility percentage shows coverage. ### Mention Position (Rank Distribution) **What it measures:** Where you appear in AI answers when mentioned. | Position | What It Means | | - | - | | **1st rank** | You're the primary recommendation | | **2nd rank** | You're an alternative | | **3rd rank** | You're also considered | | **4th+ rank** | You're in the list | | **Not mentioned** | You're invisible | ### Sentiment Score **What it measures:** How positively AI talks about your brand. **How it's calculated:** * Positive mentions ÷ Total mentions × 100 * Example: 82 positive out of 100 total = 82% sentiment **What good looks like:** * 🟢 **Excellent**: Above 85 * 🟡 **Good**: 70-85 * 🔴 **Concerning**: Below 60 **Why it matters:** Being mentioned negatively is worse than not being mentioned at all. ### Market Share (Share of Voice) **What it measures:** Your brand mentions compared to all competitor mentions. **How it's calculated:** * Your visibility ÷ Sum of all tracked brand visibility * In the image above for Canva: 34.2% market share in AI responses ### Citation Metrics **Total Citation Pages** * All unique URLs cited when your brand/topic is discussed * Shows the breadth of website sources (domains) AI considers authoritative **My Pages Cited** * The number of your website/blog pages that AI references **Total Domains Cited** * Unique domains AI references for your topics **Sites Mentioning Me** * Third-party websites that talk about your brand * Higher number = stronger authority signal to AI **Your Domain Rating** * This is a traditional SEO metric from Ahrefs * Shows quality score of your domain (0-100) **Citation Authority Score** * Quality rating of domains citing you (0-100) * Based on trust, relevance, and freshness of citing domains ### Platform-Specific Metrics **Platform Visibility Breakdown** Different AI platforms will show different visibility: * ChatGPT: 60% * Perplexity: 45% * Claude: 52% * Google AI: 58% This variance is normal - each platform has different: * Index sources * Ranking algorithms * Content preferences * Update frequencies ## Metrics That Don't Matter (Yet) Some traditional SEO metrics don't translate to AI search: * **Keyword density** - AI understands context, not repetition * **Meta descriptions** - AI writes its own summaries * **Page speed scores** - Important for crawling, not for citations * **Number of pages** - Quality over quantity in AI search **Now that you speak AI's language**, let's dive into what separates keywords from prompts - and why this distinction changes everything about your content strategy. *** What’s Next * [Prompts vs Keywords \[Very Important\]](/docs/prompts-vs-keywords-very-important) # Overview Source: https://apidocs.writesonic.com/docs/ai-traffic-analytics ## What is AI Traffic Analytics? AI Traffic Analytics reveals the previously invisible traffic from AI systems like ChatGPT, Claude, and Google Gemini that visit your website. While traditional analytics platforms like Google Analytics miss these visits completely, our system captures every AI crawler interaction with your content through server-side tracking. ## Key Metrics Definitions **Bot Visits**: Total number of HTTP requests from identified AI platform bots to your website pages. **Human Visits**: Verified human users who arrived at your site by clicking links in AI-generated responses. **Click Rate**: Percentage calculated as (Human Visits / Bot Visits) × 100, indicating the quality and relevance of AI exposure. **Bot Error Rate**: Percentage of bot requests resulting in error status codes, calculated as (Failed Requests / Total Requests) × 100. **AI Chatbot**: Real-time content fetching bots that retrieve information to compose immediate responses to user queries. **Search Indexing**: Systematic crawling to build searchable databases for future query retrieval. **AI Training**: Data collection crawls used to train and improve AI models. *** ## Quick guide ## Part 1: Understanding the Fundamentals ### What AI Bot Analytics Tracks AI Bot Analytics monitors three critical stages of AI-driven traffic: 1. **Discovery Stage**: When AI bots crawl and index your content 2. **Citation Stage**: When AI platforms reference your content in responses 3. **Conversion Stage**: When users click through from AI citations to your site ### The Metrics That Matter Before diving into the platform, understand these core metrics: * **Bot Visits**: Raw crawl volume from AI platforms * **Human Visits**: Actual users arriving from AI citations * **Click Rate**: The efficiency of converting bot attention to human traffic * **Bot Error Rate**: Technical barriers preventing AI access *** ## Part 2: Initial Setup and Audit ### Step 1: Conduct Your First AI Visibility Audit **Navigate to**: AI Bot Analytics > Overview **What to check first**: 1. **Bot Error Rate** - This is your priority 2. **Total Bot Visits** - Establishes your baseline 3. **Platform Distribution** - Which AI platforms know you exist **Action Items**: * Note any platforms with zero bot visits (opportunity gaps) * Identify your top 3 performing pages by click rate ### Step 2: Technical Health Check **Navigate to**: AI Bot Analytics > Pages > Non Accessible Pages **Priority Order for Fixes**: 1. **404 Errors** - Broken links losing you visibility 2. **403 Errors** - Authentication/permission issues 3. **500 Errors** - Server problems affecting all crawlers *** ## Dashboard Components ### 1. Overview Dashboard The Overview provides a comprehensive snapshot of your AI-driven traffic performance across all key metrics. ### **Core Metrics Section** Three primary KPIs: * **Bot Visits**: Total number of times AI bots accessed your website pages. This includes chatbots fetching content for real-time answers, indexing bots building their knowledge base, and training bots collecting data. * **Human Visits**: Actual users who clicked through to your site from AI-generated responses. This represents the real business value of AI citations. * **Bot Error Rate**: Percentage of bot requests that resulted in errors (4xx/5xx status codes). A high error rate indicates technical issues preventing AI platforms from accessing your content. ### **Time-Series Graph** Interactive visualization showing bot visits and human visits over time. Use the platform filter to analyze specific AI sources (Google, Bing, OpenAI, Perplexity, Apple, etc.) or view aggregate data across all platforms. ### **Traffic Sources Table** Platform-level breakdown showing: * **Platform**: AI platform name and logo * **AI Bot Visits**: Number of bot crawls from each platform * **Human Visits**: Click-throughs generated from each platform’s citations * **Click Rate**: Conversion rate from bot visits to human visits (quality indicator) ### **Top Pages Getting Traffic** Page-level performance metrics displaying: * **Page URL**: Specific pages being accessed * **Bot Visits**: Total bot traffic per page * **Human Visits**: Resulting human traffic per page * **Click Rate**: Page-specific conversion metrics ### **Platform to Pages Journey** Visual funnel showing the flow from AI platforms → bot types → specific page URLs, helping you understand which platforms are interested in which content. ### **Browser & Device Analytics** Validation metrics for human traffic showing: * **Browser distribution**: Chrome, Safari, Edge, Firefox, Opera breakdown * **Device types**: Desktop, Mobile, Tablet distribution These metrics confirm genuine human traffic and help optimize user experience. *** ### 2. Sources Dashboard The Sources section provides detailed analysis of each AI platform’s interaction with your site. ### **Aggregate Metrics** Top-level KPIs segmented by bot purpose: * **AI Chatbot**: Visits from conversational AI fetching content for real-time responses * **Search Indexing**: Crawls for building searchable knowledge bases * **AI Training**: Data collection for model training purposes * **Human Visits**: Total click-throughs across all sources * **Click Rate**: Overall conversion efficiency ### **AI Bot Visits Table** Comprehensive platform breakdown including: * **Bot**: Specific bot identifier (Googlebot, bingbot, ChatGPT-User, PerplexityBot, etc.) * **Platform**: Parent AI service * **Bot Type**: Classification (AI Chatbot, Search Indexing, AI Training) * **Bot Visits**: Volume of crawl activity * **Pages**: Number of unique pages accessed * **Last Visited**: Most recent bot activity timestamp **Use Cases**: * Identify which AI platforms show the most interest in your content * Spot unusual activity patterns or traffic spikes * Prioritize optimization efforts for high-value platforms * Monitor platform-specific crawl frequency *** ### 3. Pages Dashboard The Pages section reveals how AI platforms interact with your specific content. ### **Time-Series Visualization** Track traffic trends for your top-performing pages with color-coded lines for each URL, making it easy to spot content that’s gaining or losing AI attention. ### **Traffic Across Pages Table** Detailed page-level metrics showing: * **Page URL**: Complete page path * **AI Chatbot**: Visits from conversational AI bots * **Search Indexing**: Crawls for indexing purposes * **AI Training**: Data collection visits * **Human Visits**: Resulting click-through traffic **Strategic Value**: * Identify high-opportunity pages (high bot traffic, low human clicks) * Find successful content patterns to replicate * Prioritize technical fixes for valuable pages ### **Non Accessible Pages** Critical technical health section displaying: * **Page**: URLs that bots attempted but failed to access * **Platform**: Which AI service encountered the error * **HTTP Status Code**: Specific error type (404, 403, 500, etc.) * **Error Description**: Plain-language explanation * **Occurrences**: Frequency of access failures * **Last Observed**: Most recent error timestamp **Action Items**: * Fix robots.txt blocking issues * Resolve authentication problems * Address server errors and timeouts * Update redirect chains *** ### 4. Audit Logs The Audit Logs provide granular, row-level data for every bot interaction with your site. ### **Log Entry Details** Each entry contains: * **Date Visited**: Exact timestamp of bot access * **Method**: HTTP request type (GET, POST, etc.) * **Status**: HTTP response code * **IP**: Bot’s IP address * **Path**: Exact URL accessed * **Country**: Geographic origin * **Platform**: AI service name * **Bot Type**: Classification category * **Bot**: Specific bot identifier *** ## Why It Matters Up to now, website owners have had a major blind spot in their analytics: * When someone asks ChatGPT (and other similar AI chat platforms) a question and it reads your content for answers, traditional analytics show nothing * These "invisible visits" represent a growing portion of your content's actual reach and impact * Understanding which content AI systems prefer helps you optimize for this emerging channel * As AI-powered search grows, visibility to these systems becomes as important as Google rankings ## Key Features * **Complete AI Crawler Visibility**: Track visits from ChatGPT, Claude, Perplexity, Google Gemini, Deepseek, Meta's Llama, and Microsoft Copilot * **Zero Performance Impact**: Server-side tracking requires no code on your pages * **Content Performance Analysis**: See which pages AI systems visit most frequently * **Platform Breakdown**: Understand which AI systems engage most with your content * **Trend Monitoring**: Track changes in AI crawler patterns over time *** ### 5. Region Dashboard **Purpose**: Track where in the world real users click through from AI platform citations to visit your site, enabling geographic expansion strategies based on actual human engagement data. *** ### **What You’re Looking At** The Region dashboard displays **Human visits only** *** ### **Dashboard Components** ### **1. Top Region Cards** The five countries driving the most human traffic from AI citations, displayed as cards with: * 🏳️ Country flag and name * 📊 Visit count (large number) * 📈 Trend indicator (growth/decline from previous period) **How to use**: Quick health check - are your target markets in the top 5? ### **2. Control Bar** * **Time Period Selector**: “Last 7 Days” with dropdown for “Previous 7 Days” comparison * **Platform Filter**: Isolate traffic from specific AI platforms * **Page Filter**: Analyze regional performance for specific content * **Region Filter**: Focus on particular countries or regions **How to use**: Drill down to answer specific questions like “Which countries engage most with our product pages via ChatGPT?” ### **3. Visualization Toggle (Chart/Map)** **Chart View - Time Trends** * **What it shows**: Line graph of human visits over time by country * **Best for**: Spotting trends, peaks, and regional patterns * **Key features**: * Each country gets a unique color matching its flag * Hover for exact daily numbers * Identify which regions are growing vs. declining **Map View - Geographic Distribution** * **What it shows**: Global heat map of traffic concentration * **Best for**: Identifying geographic clusters and gaps * **Key features**: * Darker blue = more traffic * Zoom controls (+/-) for regional focus * 0-100% concentration scale **How to use**: Start with Map for overview, switch to Chart for trend analysis ### **4. Regional Performance Table** **Columns explained**: * **Region**: Country with flag icon * **Human Visits**: Absolute number + percentage of global total * **Pages Visited**: Average pages per session + change from previous period * **Growth Indicators**: Green ↑ for growth, red ↓ for decline **Reading the data**: * **High visits + High pages** = Strong market engagement * **Growing visits + Low pages** = Emerging opportunity, needs optimization * **Declining visits** = Investigate causes (competition, technical issues, content relevance) *** ## Getting Started To begin tracking AI traffic to your website: 1. [Set up AI Traffic Analytics](/docs/ai-traffic-analytics-setup-and-implementation-guide) 2. [Understand your dashboard](/docs/ai-traffic-analytics-understanding-your-dashboard) 3. [Optimize for AI visibility](/docs/ai-traffic-analytics-optimizing-for-ai-visibility) ## How It's Different from Traditional Analytics | **Traditional Analytics (Google Analytics)** | **AI Traffic Analytics** | | - | - | | Relies on JavaScript that AI crawlers don't execute | Works at the server level, capturing all AI visits | | Misses AI visits completely | Captures and categorizes all AI crawler activity | | Only tracks human visitors | Reveals both AI and human traffic patterns | | No differentiation between AI platforms | Detailed breakdown by specific AI system | | Limited to standard web metrics | Specialized metrics for AI visibility | *** ## FAQs **Q: What’s the difference between bot visits and human visits?** **A:** Bot visits are automated crawls by AI platforms to fetch and optionally index your content. Human visits are real users who clicked through to your site after seeing your content cited in an AI-generated answer. The relationship between these metrics indicates how effectively your content converts AI exposure into actual traffic. **Q: How is click rate calculated and what’s a good benchmark?** **A:** Click rate is (Human Visits / Bot Visits) × 100. Industry benchmarks vary, but rates above 5% indicate strong performance. **Q: Why are some of my pages showing in “Non Accessible Pages”?** **A:** Pages appear here when bots encounter errors trying to access them. Common causes include robots.txt blocking, authentication requirements, server timeouts, broken links, or rate limiting. Each entry shows the specific error code. **Q: What does a high bot error rate indicate?** **A:** A bot error rate above 5% suggests technical issues preventing AI platforms from properly accessing your content. This directly impacts your AI visibility and potential traffic. Review your audit logs to identify patterns and prioritize fixes. **Q: Can I see which specific AI answers cited my content?** **A:** The current version tracks citation-driven traffic at the platform and page level. While we can’t show the exact AI responses, the combination of bot visits, human visits, and click rates provides actionable insights about citation performance. **Q: What’s the difference between AI Chatbot, Search Indexing, and AI Training bots?** **A:** * **AI Chatbot bots** fetch content in real-time to answer user queries immediately * **Search Indexing bots** build databases for future query retrieval * **AI Training bots** collect data to improve model capabilities and used for training future models **Q: How should I prioritize optimization efforts?** **A:** Focus on three areas: 1. **High-error pages**: Fix technical issues blocking bot access 2. **High bot/low human pages**: Improve titles, snippets, and structured data 3. Server side rendering: Do server side rendering instead of client side **Q: How can I improve my click rate from AI citations?** **A:** * Optimize page titles and meta descriptions for clarity and relevance * Implement comprehensive structured data markup * Ensure fast page load speeds * Create content that directly answers common queries * Fix all technical errors preventing proper indexing * Do server side rendering instead of client side **Q: How do I use Audit Logs for debugging?** **A:** Filter audit logs by status code to find all errors, then search for specific paths to understand failure patterns. Check timestamps to correlate with any changes you made. Use IP and country data to identify regional issues or unexpected bot behavior. *** [GEO: Getting Started](/docs/geo-getting-started) [Setup and Implementation Guide](/docs/ai-traffic-analytics-setup-and-implementation-guide) # Optimizing for AI Visibility Source: https://apidocs.writesonic.com/docs/ai-traffic-analytics-optimizing-for-ai-visibility ## Understanding Generative Engine Optimization (GEO) Just as SEO helps your content rank well in Google, Generative Engine Optimization (GEO) helps ensure your content is found, cited, and recommended by AI systems. AI Traffic Analytics provides the data you need to implement effective GEO strategies. ## Key Optimization Principles ### 1. Clear Structure and Formatting AI systems tend to favor content that is: * Well-organized with logical headings (H1, H2, H3) * Contains clear definitions and explanations * Includes concise, direct answers to common questions * Features bullet points and numbered lists for key information **Action step**: Review your top-performing AI pages to identify structural patterns that work well. ### 2. Comprehensive Coverage AI systems often look for content that: * Covers topics thoroughly from multiple angles * Answers related questions within the same page * Provides context and background information * Includes relevant examples and applications **Action step**: Use your AI Traffic Analytics data to identify content gaps where AI systems might be leaving your site to find supplementary information. ### 3. Factual Accuracy and Citations AI platforms prioritize content that: * Presents accurate, verifiable information * Cites credible sources * Includes data points, statistics, and research * Maintains current, up-to-date information **Action step**: Regularly update your most-visited AI pages with fresh statistics and information. ### 4. Clear Entity Relationships AI systems understand content better when: * Key entities (people, organizations, concepts) are clearly defined * Relationships between entities are explicitly stated * Technical terms are explained * Content follows a logical flow of ideas **Action step**: Review your content for clarity of relationships and explicit definitions of key terms. ## Practical Optimization Workflow 1. **Identify Priority Pages**: Use AI Traffic Analytics to find: * Pages with high AI crawler traffic * Pages where AI traffic patterns differ from human visitors * Content that receives visits from multiple AI platforms 2. **Analyze Content Structure**: * Review heading structure and organization * Look for clear question-answer formats * Evaluate completeness of topic coverage * Check for suitable formatting (lists, tables, etc.) 3. **Enhance and Update**: * Add FAQ sections addressing common questions * Ensure comprehensive coverage of the topic * Update statistics and time-sensitive information * Improve clarity and readability * Add explicit definitions for key terms 4. **Monitor Results**: * Track changes in AI crawler patterns after updates * Note which AI platforms respond to which optimization techniques * Compare with changes in traditional search traffic ## Beyond Content: Technical Considerations * **Schema Markup**: While primarily designed for search engines, structured data can help AI systems understand your content * **Page Speed**: Faster pages tend to be crawled more frequently by all systems * **Crawlability**: Ensure your robots.txt doesn't block legitimate AI crawlers ## Measuring Optimization Success Track these metrics in your AI Traffic Analytics dashboard to measure the impact of your optimization efforts: * Increased AI crawler visits * More diverse AI platform coverage * Longer page sessions from AI systems * Higher crawl frequency * Expanded page coverage across your site *** [Understanding Your Dashboard](/docs/ai-traffic-analytics-understanding-your-dashboard) [Troubleshooting and FAQs](/docs/ai-traffic-analytics-troubleshooting-and-faqs) # Setup and Implementation Guide Source: https://apidocs.writesonic.com/docs/ai-traffic-analytics-setup-and-implementation-guide AI Traffic Analytics is a server-side analytics solution that captures and analyzes raw traffic directly from your infrastructure logs—not the browser. This guide walks you through the process of implementing AI Traffic Analytics on your website. ## Quick Start To get started, choose one of the supported integrations and forward logs or events to AI Traffic Analytics. ### Supported Integrations Writesonic AI Traffic Analytics can be integrated with any platform no matter where it is hosted. We offer native connectors for select platforms, while all other environments can be connected using our flexible custom integration pipeline. ## Need Help? Please check out the [Toubleshooting and FAQs](https://docs.writesonic.com/docs/ai-traffic-analytics-troubleshooting-and-faqs#/) page. For assistance, contact [\[email protected\]](/cdn-cgi/l/email-protection#c0b3b5b0b0afb2b480b7b2a9b4a5b3afaea9a3eea3afad) *** What’s Next * [Troubleshooting and FAQs](/docs/ai-traffic-analytics-troubleshooting-and-faqs) * [Understanding Your Dashboard](/docs/ai-traffic-analytics-understanding-your-dashboard) # Troubleshooting and FAQs Source: https://apidocs.writesonic.com/docs/ai-traffic-analytics-troubleshooting-and-faqs ## Common Issues ### No Data Showing After Setup **Possible causes:** * The Cloudflare Worker may not be properly deployed * Your site hasn't received AI crawler visits yet * There might be a reporting delay (up to 24 hours) **Solutions:** 1. Verify the Worker is correctly deployed in your Cloudflare dashboard 2. Check that your site is accessible to external crawlers 3. Wait 24-48 hours for data to appear 4. Run the verification test from the setup page ### Missing Data for Specific AI Platforms **Possible causes:** * The AI platform might not be crawling your site * Our system might not yet recognize a new crawler signature **Solutions:** 1. Ensure your content is relevant to that AI platform's typical queries 2. Contact support if you believe a specific AI platform should be visiting but isn't detected ### Unexpected Drops in AI Traffic **Possible causes:** * AI systems update their crawling patterns * Your content might have become outdated * Technical issues might be blocking crawlers **Solutions:** 1. Check for any technical changes to your site 2. Update content to ensure it remains relevant 3. Verify robots.txt settings aren't blocking crawlers 4. Look for correlations with known AI model updates ## Frequently Asked Questions ### What AI platforms do you currently track? We currently track and identify: * OpenAI (ChatGPT) * Google (Gemini) * Perplexity * Deepseek * Meta (Llama) * Microsoft (Copilot) * Additional systems are added as they emerge ### How is this different from bot tracking in server logs? While basic server logs might show bot visits, AI Traffic Analytics: * Specifically identifies AI crawler signatures * Provides purpose-built metrics and visualization * Offers analysis tools designed for AI optimization * Continues to update crawler identification as systems evolve * Shows trends and patterns specific to AI interactions ### Does this slow down my website? No. Our tracking system uses server-side integration that has zero impact on page load times or performance. Unlike JavaScript-based analytics, there's no code added to your pages. ### Is this compliant with privacy regulations? Yes. AI Traffic Analytics tracks AI crawler behavior, not individual users. It doesn't collect personal data and is fully compliant with GDPR, CCPA, and other privacy regulations. ### How often is the data updated? Data is processed and updated in near real-time. ### Can I block AI crawlers after seeing this data? While our system provides visibility, blocking decisions are separate. If you wish to limit AI crawlers, you should update your robots.txt file or implement other access controls. However, we generally recommend allowing AI systems to access your content for increased visibility. ### What's coming next for this feature? Our roadmap includes: * Citation tracking (seeing when your content is referenced in AI responses) * Expanded integration options beyond Cloudflare * Correlation between AI visits and subsequent human traffic * Content optimization recommendations * Custom alerts and reporting ### Does this work for all websites? The primary integration works for any website using Cloudflare. We're rapidly expanding to support other platforms with upcoming integrations for WordPress, Vercel, AWS, and direct server implementations. *** [Optimizing for AI Visibility](/docs/ai-traffic-analytics-optimizing-for-ai-visibility) [AI Search Basics: What It Is & How It Works](/docs/ai-search-visibility) # Understanding Your Dashboard Source: https://apidocs.writesonic.com/docs/ai-traffic-analytics-understanding-your-dashboard Your AI Traffic Analytics dashboard provides a comprehensive view of how AI crawlers interact with your website. Here's how to interpret the data and gain actionable insights. ## Key Metrics Explained ### Total AI Visits This metric shows the total number of requests from AI crawlers to your website within the selected time period. Each time an AI system like ChatGPT or Claude accesses one of your pages, it's counted here. **How to use it**: Monitor the trend over time to understand if AI systems are increasing their engagement with your content. ### Visits by AI Platform This breakdown shows which specific AI systems are visiting your site most frequently. **How to use it**: Different AI platforms may prioritize different types of content. Understanding which ones engage most with your site helps you optimize accordingly. ### Top Pages for AI This section reveals which pages on your website receive the most attention from AI crawlers. **How to use it**: These pages are your most visible content in the AI ecosystem. They may differ significantly from your top pages in Google Analytics, revealing new opportunities for optimization. ### Visit Trends The trend graph shows how AI crawler activity has changed over time, with data available in daily, weekly, and monthly views. **How to use it**: Look for patterns or spikes that might correlate with content updates, industry news, or AI model releases. ## Custom Date Ranges To analyze specific time periods: 1. Click the date selector in the top right corner 2. Choose a preset range (Today, Yesterday, Last 7 Days, Last 30 Days) 3. Or select "Custom Range" to define specific start and end dates 4. Click "Apply" to update all dashboard metrics ## Comparing with Traditional Analytics For a complete picture of your site's performance, it's valuable to compare AI Traffic Analytics with your standard analytics: 1. Note which pages are popular with human visitors vs. AI crawlers 2. Look for content that performs well with AI but poorly with humans (and vice versa) 3. Identify patterns in content format, structure, or topics that appeal to different audiences *** [Integrating with Cloudfront](/docs/integrating-with-cloudfront) [Optimizing for AI Visibility](/docs/ai-traffic-analytics-optimizing-for-ai-visibility) # All Citations Source: https://apidocs.writesonic.com/docs/all-citations The page lists every webpage that generative‑AI systems (ChatGPT, Google SGE, Bing Chat, etc.) cite when answering questions in your niche. It tells you: ## Core Components The All Citations section displays a comprehensive table of individual pages from across the domain where AI models are currently citing or could potentially cite your content. Each entry represents a unique citation opportunity with detailed metrics and insights. **What this shows:** * **Which pages** (yours, competitors’, third‑party) are referenced * **How often** each page appears in AI answers * **Which topics, brands and AI platforms** are involved Use it to measure your content’s AI visibility, spot competitor wins, and uncover new content opportunities. **Why it matters:** * **Strategic Priority Setting**: Quickly identify your most valuable and frequently cited content to focus optimization efforts where they'll have maximum impact * **Content Gap Analysis**: Discover which pages are underperforming in AI citations despite having valuable content, revealing optimization opportunities * **Competitive Intelligence**: Understand which competitors appear alongside your citations, enabling you to refine your positioning and differentiation strategies * **Cross-Platform Visibility**: Track your presence across multiple AI platforms from a single view, ensuring comprehensive coverage in the AI search landscape * **Topic Authority Building**: Identify subject areas where you're gaining traction and double down on content that establishes domain expertise **How to read the metrics:** * **Higher answer counts** indicate pages with strong authority and relevance in AI responses * **Multiple platform presence** suggests broad recognition across AI ecosystems * **Brand co-mentions** reveal competitive landscape and partnership opportunities *** ## 1. Key controls (top bar) | Control | Why it matters | | - | - | | **Date picker** | View today’s data or any past date. | | **Changes** toggle | Compare current data to a prior period to spot trends. | | **Filters** (Platform • Topic • Citing domain • Brand mentions) | Slice the table by AI source, query theme, site, or brand references. | | **Search** | Jump to a specific page or keyword. | | **Export** | Download the table (CSV) for offline analysis. | *** ## 2. Table columns (left → right) | Column | Insight | | - | - | | **Cited page** | Title & URL of the referenced article—click to open. | | **Source type** | *Your brand*, *Competitor*, or *Third‑party*. | | **No. of answers** | How many AI answers use this page (higher = greater AI exposure). | | **Brands mentioned** | Logos of brands named in the page (+X for more). | | **Platform** | Icons showing which AI engine(s) cited it. | | **Topic** | Query category that triggered the citation (hover to see extras). | *** ## 3. Fast workflows 1. **Audit your reach** Filter → Source type = **Your brand** to see which of your pages appear in AI answers. Strengthen or update low‑performing pages. 2. **Track competitors** Filter → your competitor domains to find their most‑cited pages. Study structure, depth, and backlinks. 3. **Find content gaps** Filter → **Topic** where none of your pages appear but competitors/third‑parties dominate—create or revamp content there. 4. **Leverage brand mentions** Use **Brand mentions** filter to gauge how often your tool—or rivals—are name‑dropped inside influential content. 5. **Compare platforms** Switch **Platform** filter to see if Google SGE vs. ChatGPT favors different sources; tweak SEO or content accordingly. 6. **Monitor change over time** Set **Changes** to *Last 7 days* (or any range) to confirm impact after a new content launch or update. *** ## 4. Tips * **High “No. of answers” + Third‑party** → consider outreach, guest posts, or partnerships to gain visibility. * **Your page cited across multiple topics** → replicate that content format for other keywords. * **Export regularly** to build an internal benchmark of AI citation share vs. competitors. *** [Overview](/docs/citations-overview-page) [Citations: Domains Mentioning me(User's Brand)](/docs/citations-domains-mentioning-you-brand) # All Prompts and Answers Source: https://apidocs.writesonic.com/docs/all-prompts The page is your single, unified view of every prompt GEO is tracking — and every AI-generated answer those prompts produce. It combines two complementary tabs — and — so you can move seamlessly from "what are we tracking?" to "what did the AI actually say?" Use this page to spot visibility gaps, monitor competitor mentions, analyze AI-generated responses, and prioritize your next optimization moves — all without leaving the screen. *** ## Page-Level Controls Before diving into either tab, familiarize yourself with the controls at the top of the page. These apply globally and shape the data you see in both tabs. * **Date Selector** — Choose the date for which you want to view prompt and answer data. This lets you analyze a specific point-in-time snapshot. * **Comparison (vs.)** — Select a second date to compare against. When enabled, change indicators (↑ / ↓) appear next to metrics like Search Volume, AI Visibility, and Rank, showing how values have shifted between the two dates. * **All Markets** — Filter data by a specific target market (country + language) or view across all configured markets. * **Topics** — Narrow the view to prompts belonging to a specific topic cluster. * **Platform** — Filter by a specific AI platform (e.g., ChatGPT, Perplexity, Claude, Google AI Overview) or view data across all platforms. * **Prompts** — Quick text search to find a specific prompt by keyword. * **Presets** — Save and apply commonly used filter combinations for faster access. * **Non-branded / Branded Prompts Toggle** — Switch between viewing prompts that don't contain your brand name (non-branded) and those that do (branded). This helps you separately analyze discovery-intent queries vs. brand-specific queries. * **AI Suggested Filter** — Click the lightning bolt icon to surface AI-powered filter suggestions based on your data patterns. * **Advanced Filters** — Build multi-condition queries using AND/OR logic across dimensions like Visibility, Rank, Brands Mentioned, and more. This is especially useful for complex analyses like *"show prompts where CompetitorX is mentioned but my brand is not"* or *"prompts with AI Visibility below 50% and Search Volume above 1,000."* *** ## Prompts Tab The **Prompts** tab gives you a comprehensive, sortable list of every prompt configured in your GEO project. Each row represents a single tracked prompt and shows key performance metrics at a glance. ### Table Columns * **Prompts** — The exact natural-language query being tracked across AI platforms. Clicking a prompt opens its detailed view. * **Topic** — The topic cluster this prompt belongs to (e.g., "design tool analysis," "email marketing software"). Topics are set during onboarding and help you group related prompts for campaign-level analysis. * **Search Volume** — The estimated monthly search volume for this prompt. When comparison is enabled, you'll see the change (↑ or ↓) relative to the comparison date. Higher search volume = higher potential visibility impact. * **AI Visibility** — The percentage of AI-generated answers (across tracked platforms) that mention your brand for this prompt. This is your core GEO performance metric per prompt. When comparison is enabled, the delta shows whether visibility is improving or declining. * **Rank** — Your brand's average position in AI-generated answers for this prompt. A rank of **1** means your brand is the first mentioned. When comparison is enabled, rank changes are shown — a downward number (e.g., ↑ 5) means you've moved up (improved). * **Market** — The geographic market and language (e.g., "United States – English (US)", "India – Hindi") for this prompt entry. If you track multiple markets, the same prompt may appear multiple times with different market tags. ### How to Use the Prompts Tab * **Identify high-value gaps** — Sort by **Search Volume** (descending) and filter for low **AI Visibility**. These are high-traffic prompts where your brand isn't showing up — your biggest opportunities. * **Track competitive positioning** — Use Advanced Filters to find prompts where a specific competitor is mentioned but you're not. * **Monitor rank movement** — Enable date comparison and sort by **Rank** change to see where you're gaining or losing ground. * **Segment by topic** — Use the Topic filter to assess performance within a specific product category or content cluster. * **Market-level analysis** — Filter by a specific market to understand regional differences in AI visibility. ### Pagination & Export The table supports pagination (configurable to 25, 50, or 100 items per page) and can be exported for offline analysis or reporting. *** ## Answers Tab Switch to the **Answers** tab to see the actual AI-generated responses for each prompt. While the Prompts tab tells you *what* you're tracking and *how you rank*, the Answers tab shows you *what the AI actually said* — and who it mentioned. ### Table Columns * **Answers** — A preview of the AI-generated response text. This is the actual content the AI platform returned when the prompt was asked. Click to expand and read the full answer. * **Prompts** — The prompt that generated this answer. This links back to the corresponding prompt entry. * **Mentions You** — Indicates whether your brand was explicitly mentioned in this AI-generated answer. A green check mark (✓) means you were mentioned; a red cross (✗) means you were not. * **Platform** — The AI platform that generated this answer (e.g., ChatGPT, Perplexity, Claude, Google AI Overview). * **Rank** — Your brand's position within this specific answer. If your brand is not mentioned, this field is blank or shows no rank. When comparison is enabled, the change indicator shows movement. * **AI Visibility** — The visibility score for your brand in this specific answer, shown as a percentage with change indicators when comparison is active. * **Brands Mentioned** — Displays icons/logos of all brands mentioned in this AI-generated answer, including your brand and competitors. This gives you an instant visual of who the AI is recommending alongside (or instead of) you. * **Topic** — The topic cluster associated with this answer's prompt. * **Query Fanouts** — Shows the related query categories or fanout types that this prompt/answer maps to (e.g., "Social media content creation," "Online Graphic design"). Query fanouts reveal how AI platforms interpret and expand the original prompt. * **Market** — The geographic market and language for this answer. * **Answered On** — The date when this AI-generated answer was captured by GEO. ### How to Use the Answers Tab * **Gap hunting** — Filter **Mentions You = No** to instantly see all answers where your brand is absent. These are your most actionable optimization targets. * **Competitive intel** — Check the **Brands Mentioned** column to see which competitors appear most frequently and in which contexts. * **Content audit** — Read the actual AI answers to understand *how* AI platforms describe your category and what language they use. Mirror this language in your content. * **Platform-specific analysis** — Filter by a specific **Platform** to see how each AI engine responds differently to the same prompts. * **Track answer freshness** — Use the **Answered On** date to understand how recently AI platforms refreshed their responses for your prompts. * **Understand query expansion** — Use **Query Fanouts** to discover how AI platforms are interpreting and expanding your tracked prompts into related sub-queries. *** ## Switching Between Prompts and Answers The **Prompts** and **Answers** tabs sit at the top of the page and can be toggled instantly. Your active filters carry over between tabs, so if you've filtered to a specific topic or platform, that filter persists when you switch. **Recommended workflow:** 1. Start on the **Prompts** tab to identify prompts with low visibility or declining rank. 2. Switch to the **Answers** tab to read the actual AI responses for those prompts. 3. Analyze which competitors are mentioned, what sources are cited, and what language the AI uses. 4. Use these insights to inform your content strategy, outreach priorities, or Action Center workflows. *** ## Key Metrics Explained | Metric | What It Tells You | What to Aim For | | - | - | - | | **Search Volume** | How many people search this prompt monthly | Prioritize high-volume prompts for maximum impact | | **AI Visibility** | % of AI answers mentioning your brand for this prompt | Higher is better — aim for consistent improvement | | **Rank** | Your brand's position in the AI answer | Closer to 1 is better — means you're mentioned first | | **Mentions You** | Whether the AI answer includes your brand | Green check (✓) on every high-value prompt | | **Brands Mentioned** | All brands the AI recommends in its answer | Monitor competitor presence and identify displacement opportunities | *** ## Tips & Best Practices * **Use date comparison regularly.** Comparing data across two dates is the fastest way to measure whether your GEO efforts are working. Look for upward trends in AI Visibility and improving (lower) Rank numbers. * **Prioritize high-volume, low-visibility prompts.** These represent the biggest opportunities — lots of people are asking, but AI isn't mentioning you yet. * **Read the actual AI answers.** Numbers tell you *where* you stand, but reading the answers tells you *why*. Understanding how AI frames its recommendations helps you craft content that earns mentions. * **Combine with the Action Center.** Once you've identified gaps on this page, head to the Action Center to find specific, prioritized steps to close those gaps. * **Leverage Advanced Filters for reporting.** For enterprise teams, Advanced Filters let you build precise, repeatable queries — ideal for stakeholder reports and weekly audits. * **Track query fanouts.** AI platforms often expand a single prompt into multiple related queries. Monitoring fanouts helps you understand the full scope of how your brand is (or isn't) surfacing. *** [Prompts Overview](/docs/prompts-overview) [Missing Prompts](/docs/missing-prompts) # Sentiment: Themes and Keywords Source: https://apidocs.writesonic.com/docs/all-themes The page gives you a fast, at-a-glance view of — and whether that conversation is positive or negative. It works by grouping AI-generated answers into recurring **themes** (topics that keep showing up) and drilling down into the specific **keywords** driving sentiment within each theme. Use it to spot what's resonating, what's hurting, and where you need to focus next. *** ## How to Read This Page The page has two main views, controlled by the toggle at the top: * **Themes** — Groups AI mentions into broad thematic categories (e.g., "Intuitive user interface," "Responsive design," "Seamless integration"). * **Keywords** — Shows the individual keywords that drive sentiment within those themes, along with the specific AI platforms where they appear. Switch between the two views using the **Themes / Keywords** toggle at the top of the page. *** ## Filters and Controls Before diving into the data, you can narrow down what you see using the filter bar at the top. These filters apply to both the Themes and Keywords views. * **Date Range** — Select a start and comparison date to track how themes and keywords have shifted over time. Trending indicators (↑/↓) throughout the table reflect changes between these two periods. * **Markets** — Filter by a specific market if you're tracking multiple regions or languages. * **Topics** — Narrow results to a specific topic from your configured GEO topics. * **Platform** — Filter by a specific AI platform (e.g., ChatGPT, Perplexity, Gemini) to see platform-specific sentiment patterns. * **Tags** — Apply custom tags to further refine the data based on your internal categorizations. *** ## Themes View The **Themes** view displays a complete breakdown of thematic categories with sentiment distribution and mention volumes. Think of themes as the big-picture topics AI engines associate with your brand. ### What You'll See in the Table Each row in the **All Themes** table represents a recurring theme, with the following columns: * **Themes** — The name of the thematic category (e.g., "Intuitive user interface," "Regular updates"). These are automatically identified from AI-generated answers to your tracked prompts. * **Keywords** — The number of individual keywords associated with this theme. Click the count to explore the specific terms driving this theme. The trending indicator (↑/↓) shows whether the keyword count has increased or decreased compared to the previous period. * **Sentiment** — A visual sentiment bar with a numerical score representing the percentage of positive mentions. Green indicates strong positive sentiment, yellow is mixed, and red signals predominantly negative sentiment. The trending indicator reflects whether sentiment is improving or declining. * **Mention Count** — The total number of times this theme appeared across AI-generated answers. The trending indicator shows whether the theme is being discussed more or less frequently. ### Why Themes Matter * **Spot brand strengths** — Themes with high sentiment scores and high mention counts represent what AI platforms consistently praise about your brand. * **Identify problem areas** — Themes with low sentiment but high mention counts are actively being discussed in a negative light — these need immediate attention. * **Track perception shifts** — Use the date comparison to see if your content updates, campaigns, or product changes are moving the needle on specific themes. ### How to Use It Look for themes that have a **high mention count but low sentiment score**. These are high-visibility areas where your brand is frequently discussed but not positively perceived — representing both a risk and an opportunity. Prioritize addressing these through content improvements, product updates, or targeted messaging. *** ## Keywords View The **Keywords** view gives you a granular look at the specific terms AI platforms use when discussing your brand. While Themes show you the big picture, Keywords show you the exact language driving sentiment. ### What You'll See in the Table Each row in the **All Keywords** table represents an individual keyword, with the following columns: * **Keyword** — The specific term extracted from AI-generated answers (e.g., "User-friendly interface," "Quick load times," "Comprehensive documentation"). Keywords are clickable for deeper exploration. * **Theme** — The parent thematic category this keyword belongs to. This helps you understand the broader context behind each keyword. * **Sentiment** — A visual sentiment bar with a numerical score, same as the Themes view. The trending indicator shows whether sentiment for this specific keyword is improving or declining. * **Mention Count** — How many times this keyword appeared in AI-generated answers. The trending indicator reflects volume changes over time. * **Platform** — Icons showing which AI platforms are using this keyword when discussing your brand (e.g., ChatGPT, Perplexity, Gemini, Google AI Mode, and others). This tells you where specific perceptions are forming. ### Why Keywords Matter * **Understand the exact language AI uses** — Keywords reveal precisely how AI engines describe your brand, which may differ from your own messaging. * **Discover platform-specific patterns** — A keyword might appear frequently on one platform but not another. This helps you tailor your content strategy per platform. * **Connect sentiment to specifics** — Instead of knowing a theme is "negative," you can see exactly which terms are driving that negativity. ### How to Use It Pay close attention to **negative-sentiment keywords with high mention counts**. These are the specific terms pulling your brand perception down. Cross-reference with the **Platform** column to identify if the issue is widespread or isolated to a specific AI engine — then prioritize your content and messaging strategy accordingly. *** ## Searching and Exporting Both views include: * **Search bar** — Quickly find a specific theme or keyword by typing in the search field at the top of the table. * **Export** — Click the download icon (top-right of the table) to export the data for reporting, stakeholder presentations, or deeper analysis. * **Pagination** — Navigate through results using the pagination controls at the bottom. You can adjust the number of items displayed per page (default: 25 per page). *** ## Tips for Getting the Most Out of This Page * **Start with Themes, then drill into Keywords.** Themes give you the strategic overview. Keywords give you the tactical detail. Use both together to build a complete picture. * **Compare date ranges regularly.** Sentiment shifts over time. Set a weekly or bi-weekly cadence to track whether your GEO efforts are improving brand perception. * **Filter by Platform when investigating issues.** If a theme has mixed sentiment, filtering by platform can reveal whether the problem is universal or specific to one AI engine. * **Use Keywords to inform your content strategy.** If AI platforms consistently associate your brand with a negative keyword, create or update content that directly addresses that concern. * **Cross-reference with the Competitors page.** Understanding how competitors perform on the same themes gives you context for whether a sentiment issue is brand-specific or industry-wide. *** [Sentiment: Overview](/docs/sentiment-overview) [Sentiment: Platforms](/docs/sentiment-platform) # Citation Opportunities Source: https://apidocs.writesonic.com/docs/citation-opportunity The page shows you where competitors are getting cited in AI-generated answers — but your brand isn't. Think of these as gaps in your AI visibility that you can close through outreach, content improvements, or PR efforts. This is one of the most actionable pages in Writesonic's GEO tool. Instead of guessing where to focus, you get a clear list of high-value sources that already influence AI answers — and specific ways to get your brand included. *** ## Filters and Controls At the top of the page, you'll find a set of filters to narrow down your view: * **Date range selector** — Compare citation opportunities across two time periods to spot trends and new gaps. * **Markets** — Filter by target region if you're tracking multiple markets. * **Topics** — Focus on specific topic categories relevant to your business. * **Platform** — Narrow results to a specific AI platform (e.g., ChatGPT, Perplexity, Google AI Overviews, Claude). * **Tags** — Use tags you've configured in your project to slice the data further. * **Prompt type** — Filter by the type of prompts driving the citation opportunities. These filters help you prioritize opportunities that matter most to your strategy — whether that's a specific region, platform, or topic area. *** ## Citation Gaps This is the summary section at the top of the page, giving you a quick snapshot of your total opportunity landscape. * **Opportunity pages** — The total number of third-party web pages that cite your competitors but don't mention your brand. A change indicator shows how many new pages have been identified since the last period. * **Opportunity domains** — The number of unique domains (websites) where these opportunity pages exist. This also highlights how many are high-authority domains. * **Top opportunity** — The single domain that appears most frequently in missed citation opportunities. It shows the domain's DR (Domain Rating) and the percentage of missed AI responses that cite this domain. **Why it matters:** These three metrics give you an at-a-glance understanding of how large the gap is between your brand's current citation presence and where competitors are winning. A high number of opportunity pages means there are many places where your brand could be appearing but isn't. *** ## Third-Party Pages Mentioning Competitors but Not You This is the main data table on the page — a detailed breakdown of external websites that reference your competitors but don't include your brand. You can toggle between two views: **Webpages** and **Domains**. ### Webpages View The Webpages tab shows individual pages where competitors are being cited. Each row includes: * **Cited page** — The specific URL and page title of the third-party content. Clicking it opens the page for review. * **Citation share** — The percentage of AI answers citing this particular page, with a trend indicator showing increase or decrease over time. * **Brands mentioned** — Icons representing which competitor brands are mentioned on this page. A "+N" badge indicates additional brands beyond those displayed. * **Citing answers** — The number of AI-generated answers that cite this page, along with a trend showing change over the selected period. * **Topic** — The topic category this page falls under, based on your configured topics. * **Content last updated** — When the page content was last refreshed, helping you assess how current the opportunity is. * **+ Track** — Click this to start tracking a specific page for ongoing monitoring. ### Domains View The Domains tab aggregates the data at the domain level, making it easier to identify high-priority websites for outreach. Each row includes: * **Cited domain** — The root domain (e.g., zapier.com, techradar.com) with a clickable link. Clicking into a domain reveals all the individual pages underneath. * **Citation share** — The domain's overall share of citations across AI answers, with trend data. * **Brands mentioned** — Which competitor brands are referenced across pages on this domain. * **Citing answers** — Total number of AI answers citing pages from this domain. * **Pages cited** — The number of individual pages on this domain that are cited in AI answers, along with trend data. * **Topic** — The topic categories covered by this domain's cited pages. **Why it matters:** The Webpages view is best for execution — it gives you specific pages to target for outreach. The Domains view is best for strategy — it helps you identify which websites to prioritize building relationships with. Both views include a **search bar** to find specific pages or domains, and pagination controls at the bottom to navigate through results. *** ## Prompts Citing Competitors but Not You Below the pages/domains table, you'll find a second critical section that flips the perspective. Instead of showing *where* competitors are cited, this section shows *which prompts* trigger AI answers that cite competitors but not your brand. You can toggle between **Prompts** and **Topics** views. ### Prompts View Each row represents a specific prompt (a real question users ask AI platforms) where competitors are getting cited but you aren't. The columns include: * **Prompt** — The actual question or query being tracked. These are the natural-language questions your potential customers are asking AI engines. * **Competitors cited** — Icons showing which competitor brands are cited in the AI response for this prompt, with a "+N" indicator for additional brands. * **Citing answers** — The number of AI-generated answers for this prompt that cite competitor content, along with a trend indicator. * **ChatGPT volume** — The estimated search volume for this prompt on ChatGPT, giving you a sense of how many people are asking this question. * **Platform** — Which AI platforms are generating answers for this prompt (shown as platform icons). * **Market** — The geographic market and language this prompt is tracked for. * **Intent** — The search intent behind the prompt, labeled as **N** (Navigational), **I** (Informational), **C** (Commercial), or **T** (Transactional). This helps you understand what the user is trying to accomplish. * **Topic** — The topic category this prompt falls under. ### Topics View This view aggregates the prompt data into broader content themes, making it easier to spot patterns. Each row includes: * **Topic** — The broader content category where competitors are consistently cited but you're not. * **Prompts to target** — The number of individual prompts within this topic that represent citation opportunities, with trend data. * **Citing answers** — The total number of AI answers across all prompts in this topic that cite competitors. * **Competitors cited** — Which competitor brands are cited across this topic area. **Why it matters:** The Prompts view helps you understand the exact questions where your brand is invisible. The Topics view helps you prioritize entire content themes for your GEO strategy — if a topic has a high number of prompts to target, it's likely a significant gap worth addressing. *** ## How to Use Citation Opportunities Here's a straightforward workflow to turn these insights into action: 1. **Start with the Citation Gaps summary** — Get a sense of the overall opportunity size. A large number of opportunity pages means there's significant room to grow your AI visibility. 2. **Switch to the Domains view** — Identify the highest-authority domains where competitors are being cited. These are your priority outreach targets because AI engines already trust content from these sites. 3. **Drill into specific pages** — Click into a domain to see the exact URLs. Review the content on those pages to understand why competitors are mentioned and where your brand could fit naturally. 4. **Check the Prompts section** — Look at which questions are driving competitor citations. If you notice prompts where you should clearly be mentioned, these are content gaps you can address on your own site or through third-party content. 5. **Use Topics view for strategic planning** — If a particular topic shows a large number of prompts to target, consider building a dedicated content strategy around that theme. 6. **Track key opportunities** — Use the **+ Track** button on high-priority pages to monitor them over time and measure whether your outreach efforts are working. *** ## Pro Tips * **Prioritize high citation share pages** — Pages with a high citation share percentage are frequently used by AI engines. Getting your brand mentioned on these pages has the highest potential impact. * **Focus on recently updated content** — Pages with recent "Content last updated" dates are actively maintained, which means the authors are more likely to respond to outreach and update their content. * **Use intent data to guide your approach** — Commercial and transactional intent prompts are closer to purchase decisions. Prioritize getting cited in these over purely informational prompts. * **Revisit regularly** — Citation opportunities change as AI engines update their responses and new content is published. Check this page at least weekly to catch new gaps early. * **Pair with the Action Center** — The Action Center uses citation opportunity data to generate ready-made outreach workflows, including personalized email drafts. Use both together for fastest results. *** *** [Citations: Your Content Performance](/docs/citations-content-performance) [Action Center: Actionables](/docs/action-center-actionables) # Citations: Your Content Performance Source: https://apidocs.writesonic.com/docs/citations-content-performance Track how your website pages perform when cited by AI — and see exactly where you stand against competitors. When AI engines like ChatGPT, Google AI Overviews, Perplexity, and others generate answers, they often pull from and cite specific webpages as sources. The **Your Content Performance** page gives you a complete picture of how your own content is performing in those citations — including which pages are being cited, how often, on which platforms, and how your citation share compares to competitors. Use this page to identify your top-performing content, spot competitive gaps, and take targeted action to grow your brand's presence in AI-generated answers. *** ## Global Filters Before diving into the data, you can refine your view using the **filter bar** at the top of the page. These filters apply across all sections on the page: * **Date range**: Select a custom or preset date range to analyze performance over a specific period. You can also compare against a previous period. * **Markets**: Filter by specific geographic markets you've configured. * **Topics**: Narrow results to specific topics relevant to your business. * **Platform**: Isolate data by AI platform (e.g., ChatGPT, Perplexity, Google AI Overviews, etc.). * **Brand mentions**: Filter to see only results where your brand is explicitly mentioned. * **Prompt type**: Filter by the type of prompt driving the citation. All metrics, charts, and tables on the page update instantly when you adjust these filters. *** ## Quick-Look Metrics At the top of the page, three headline metrics give you an instant snapshot of your citation performance: * **Your citation share** — The percentage of total AI citations (across all tracked answers) that reference your domain. This is shown alongside the total number of answers being tracked. A change indicator (e.g., ↑ or ↓) shows how this has shifted compared to the previous period. * **Answers citing your content** — The total number of AI-generated answers that included at least one citation to your website. The change indicator shows growth or decline from the last period, along with the percentage shift. * **Unique pages cited** — The number of distinct pages from your site that were cited as sources across AI answers. A rising number here means AI engines are pulling from a broader range of your content. These metrics are your starting point. If citation share is growing, your content strategy is working. If it's flat or declining, dig deeper into the sections below. *** ## Your Citation Share Over Time This trend chart visualizes how your citation volume compares to your top competitors over the selected date range. * **Y-axis**: Number of citations. * **X-axis**: Time (days or weeks, depending on the selected range). * Each competitor is represented by a **color-coded line**, making it easy to spot who's gaining or losing ground. **Key controls:** * Toggle between **Top 5 competitors** and a **Custom** selection to choose which competitors appear on the chart. * Switch between **Weekly** and other time granularities for different levels of detail. * Enable **Previous period** comparison to overlay past performance. * **Download** the chart data for reporting or further analysis. **How to use this:** Look for sustained upward trends in your line relative to competitors. If a competitor's citation count is climbing while yours is flat, drill into the **Your Cited Webpages** table below to understand what content they may be winning with — and where you can improve. *** ## Your Cited Webpages This is the core table on the page. It shows **every page from your website** that has been cited as a source in AI-generated answers, along with detailed performance data for each. **Columns include:** * **Cited page** — The URL and title of your page that was cited. Click to open. * **Citation share** — The percentage of total citations that this specific page accounts for, with a change indicator showing the trend. * **Citing answers** — The number of AI answers that cited this page, along with the change from the previous period. * **Platform** — Icons showing which AI platforms cited the page (e.g., ChatGPT, Perplexity, Google, etc.), plus a count if cited on additional platforms. * **Topic** — The topic categories associated with the prompts that triggered citations to this page. * **Content last updated** — The date when the content on this page was last refreshed. AI engines tend to favor up-to-date sources, so this is an important signal. **Actions available per page:** * **+ Track** — Add this page to your tracked pages for ongoing monitoring. * **Optimize** — Jump directly to content optimization recommendations for this page. **Additional features:** * Use the **Search** bar to find specific pages quickly. * **Sort** by any column to surface your top-performing or underperforming pages. * Toggle between **list and grid views** using the view icons. * **Download** the table data for offline analysis. * **Pagination** controls let you navigate through all your cited pages, with customizable results per page. **How to use this:** Sort by **Citing answers** to find your strongest pages. These are your citation champions — keep them fresh and authoritative. Sort by **Citation share (declining)** to spot pages losing ground, and use the **Optimize** action to get specific improvement recommendations. *** ## Prompts Citing Your Pages This section reveals the **actual prompts** (questions and queries) that drove AI platforms to cite your pages. It connects the dots between what people are asking AI and which of your pages are being used as sources. **Columns include:** * **Prompt** — The exact question or query that triggered a citation to your content. * **Pages cited** — The number of your pages cited in response to this prompt, with a change indicator. * **Citation share** — Your share of citations for this specific prompt, with trend data. * **Citing answers** — How many AI answers for this prompt cited your content, with change tracking. * **AI search volume** — The estimated search volume for this prompt across AI platforms, helping you gauge demand. * **Platform** — Which AI platforms generated answers citing your content for this prompt. * **Market** — The geographic market and language where this prompt was tracked, shown with a country flag. * **Intent** — The intent classification of the prompt (e.g., **N** for Navigational, **C** for Commercial, **T** for Transactional, **I** for Informational). * **Type** — Whether the prompt is **Branded** (includes your brand name) or **Non-branded** (generic/category queries). * **Topic** — The topic category this prompt falls under. **Additional features:** * **Search** to find specific prompts. * **Sort** by any column to prioritize by volume, citation share, or other metrics. * **Download** the data for reporting. * **Pagination** controls for navigating large prompt lists. **How to use this:** Pay close attention to **non-branded prompts** with high AI search volume where you have citation share. These represent organic discovery opportunities — people finding your content without searching for your brand directly. If you spot high-volume prompts where your citation share is low, prioritize content creation or optimization for those topics. *** ## Optimization Tips * **Keep your top-cited pages fresh.** AI engines favor up-to-date content. Regularly refresh pages that are already earning citations — update data, add new insights, and ensure accuracy. * **Close competitive gaps.** If competitors are dominating citation share for specific topics or prompts, analyze their cited content and create stronger, more authoritative pages to compete. * **Focus on non-branded prompts.** Earning citations on generic, category-level queries builds broader brand awareness and captures users who haven't heard of you yet. * **Track and optimize consistently.** Use the **+ Track** and **Optimize** actions on individual pages to build a systematic content improvement workflow. * **Monitor prompt intent.** Informational prompts help build awareness, while commercial and transactional prompts drive higher-value traffic. Balance your content strategy across intent types. *** [Citations: Domains Mentioning me(User's Brand)](/docs/citations-domains-mentioning-you-brand) [Citation Opportunities](/docs/citation-opportunity) # Citations: Domains Mentioning me(User's Brand) Source: https://apidocs.writesonic.com/docs/citations-domains-mentioning-you-brand ## Citations: Domains Mentioning Me ### What this page shows Every time a LLM platform (ChatGPT w/ browsing, Google AI Overviews, Google AI Mode, Bing Copilot, Perplexity, etc.) mentions your **brand name**, it attaches a redirection pointing to the web pages it used. This report surfaces *those* parent domains so you can see: * **Who influences AI answers about you** – which blogs, news sites, docs, or forums shape what large‑language models (LLMs) say. * **How that pool is changing** – new domains joining, old ones dropping off, and overall growth or churn. * **Where to act** – domains that deserve content updates, partnership/content outreach, or PR because they already rank as trusted sources. > **Inclusion rule** A domain appears only when **(1)** a page on that domain contains your brand name **and** **(2)** that page is explicitly cited in at least one tracked AI answer inside your selected date range. *** ### Metrics bar (top of page) | Metric | Why it matters | | - | - | | **Total Domains** | Unique sites cited for your brand in the period. A quick pulse on overall reach. | | **New Domains** | Sites that started citing you *for the first time* this period – momentum indicator. | | **Domains Lost** | Sites that cited you last period but not this one – potential visibility drop. | | **Growth %** | Net gain of citing sites vs previous period. | | **Churn %** | Portion of last period’s sites that disappeared. High churn flags attrition to investigate. | Use the **date‑range picker** to switch periods and the **"Compare to previous"** toggle to activate growth/churn columns. *** ## All referring domains The **All referring domains** panel (left column of the page) is the master list of every external **domain** that meets the inclusion rule for your selected date range. | Column | Description | | - | - | | **Domain** | Root site that hosted the mentioning page (e.g. *wikipedia.org*, *productivity‑blog.com*). Click to open the *All referring webpages* view scoped to this domain. | | **No. of asnwers** | Raw count of times your brand name appears across all qualifying pages on the domain. Helpful to spot large sites that mention you frequently but may not always get cited. | | **Page Mentions** | Number of times your brand name appears **on that single page**. Useful for spotting comprehensive guides vs fleeting mentions. | | **AI Platform** *(optional column)* | When you filter by a specific assistant, this column shows where the citation occurred (e.g., Google SGE, Bing). | ### Next steps: ### No. of answers 1. Click a page row to inspect the actual AI answers citing it (full answer log opens in the main panel). 2. Use View full report for a wider workspace with additional columns (first cited, last cited, co‑sources). 3. Download to export the per‑page data and prioritize updates with your marketiing team. *** ### Pages Click the value in the Pages column (total number of individual pages from that domain mentioning your brand). 1. Click a page row to inspect the actual AI answers citing it (full answer log opens in the main panel). 2. Use View full report for a wider workspace with additional columns (first cited, last cited, co‑sources). 3. Download to export the per‑page data and prioritize updates with your content team. *** **Tips** * **Sort by Sure** to reveal one‑stop authoritative domains. * **Sort by Last Seen** to confirm the freshest sources still active in AI answers. * **Filter** by AI platform to see which assistants prefer which domains. *** ## All referring webpages Clicking any domain (or choosing the **All referring webpages** tab) drills down one level deeper to show *individual URLs* that AI cited. | Column | Description | | - | - | | **Page URL / Title** | Direct link to the exact web page the AI footnote pointed to. Hover to preview; click to open in new tab. | | **No. of asnwers** | Raw count of times your brand name appears across all qualifying pages on the domain. Helpful to spot large sites that mention you frequently but may not always get cited. | | **AI Platform** *(optional column)* | When you filter by a specific assistant, this column shows where the citation occurred (e.g., Google SGE, Bing). | ### Next steps: ### No. of answers 1. Click a page row to inspect the actual AI answers citing it (full answer log opens in the main panel). 2. Use View full report for a wider workspace with additional columns (first cited, last cited, co‑sources). 3. Download to export the per‑page data and prioritize updates with your content team. **How to use it** * Identify **high‑Sure pages** – they single‑handedly inform AI answers. Keep them up‑to‑date or negotiate edits if third‑party. *** ### FAQ (quick reference) **Does every backlink show up here?** No. Only pages that AI assistants actually cite make the list. Plain backlinks without AI citations live in the *Backlinks* report. **How fast does the list update?** We refresh citation logs daily. New mentions can appear within 24 h of an AI answer surfacing publicly. **Why is my own domain missing?** If your site isn’t cited, check that pages use clear, factual language and structured data (FAQ, HowTo, schema.org) so AIs can trust and attribute them. *** Use this report weekly to make sure trusted, accurate voices represent your brand – and to proactively grow new ones. *** [All Citations](/docs/all-citations) [Citations: Your Content Performance](/docs/citations-content-performance) # Overview Source: https://apidocs.writesonic.com/docs/citations-overview-page The Citations Overview page is your command center for understanding how AI search engines reference and link back to your content. It brings together everything you need — citation volume, source authority, competitive gaps, and content performance — in a single, actionable view. When AI platforms like ChatGPT, Perplexity, Claude, Google AI Overviews, or Bing Copilot generate answers, they often cite specific webpages as sources. This page shows you exactly which pages are being cited, how your brand stacks up against competitors, and where the biggest opportunities lie. > **Note:** The Citations Overview page supports two views — **Branded prompts** and **Non-branded prompts** — which you can toggle using the prompt type filter at the top. The branded view focuses on prompts that directly mention your brand, while the non-branded view shows prompts where AI could cite you based on topic relevance alone. Use the date range picker, market, topic, platform, and prompt type filters at the top of the page to narrow your analysis. *** ## Quick Look Metrics At the top of the page, three key performance indicators give you an instant snapshot of your citation health: * **My citation share** — The percentage of total AI citations in your tracked space that point to your domain. This is your overall share-of-voice in AI-generated citations. A higher percentage means AI engines are choosing your content more frequently as a trusted source. Track this over time to measure whether your GEO efforts are translating into more citations. * **Your cited pages** — The total number of unique pages from your website that AI platforms are actively citing as sources. This tells you how much of your content library AI engines consider worth referencing. A growing number here means your content portfolio is expanding its authority footprint. The comparison indicator shows how this compares to the total pages cited across all brands in your space. * **External pages mentioning you** — The count of third-party pages (from external domains) that mention your brand and are being cited in AI answers. These are pages you don't own but that reference your brand — and AI is using them as sources. A higher count signals strong brand presence across the broader web ecosystem. *** ## Citation Share Trend This time-series chart tracks how your citation share has changed over your selected date range. * The **trend line** plots your citation share percentage over time — whether it's weekly or across a custom period. * Use the **Previous period** toggle to overlay the prior period's data for direct comparison. * Each data point on the chart represents the citation share for that specific time interval. **Why it matters:** This chart is your clearest indicator of momentum. A rising trend means your content is gaining trust with AI engines. A declining trend may signal that competitors are producing stronger content or that your existing pages need refreshing. Use it to correlate citation performance with specific content updates, campaigns, or outreach efforts. *** ## Leaderboard / Competitive Leaderboard This section shows a ranked list of brands (including yours) that AI cites most frequently in your industry. * Each row displays the **brand domain**, its **Domain Rating (DR)**, and its **citation share** percentage. * Your brand is highlighted with a **"You"** tag for easy identification. * The **change indicator** next to the citation share shows movement compared to the previous period. * When viewing **non-branded prompts**, this section is titled **Competitive Leaderboard** and shows only competitor domains (excluding your brand), giving you a clear view of who dominates when your brand isn't directly named. * Use the **pagination arrows** to browse through additional brands beyond the initial view. **Why it matters:** This is your competitive benchmarking at a glance. It tells you exactly where you rank among competitors for AI citation share and whether you're gaining or losing ground. If a competitor's citation share is climbing while yours is flat, it's a signal to investigate what content they're producing or which sources they're getting cited on. *** ## Citation Source Breakdown This horizontal bar chart categorizes your citations by the type of source citing you: * **Owned** — Citations from your own domain's pages. * **Competitor** — Citations from competitor domains. * **Third party websites** — Citations from independent, non-competitor domains (blogs, news sites, publications). * **Social & Forums** — Citations from community platforms like Reddit, Quora, or niche forums. Each category shows its percentage share of your total citations. **Why it matters:** A healthy citation profile has a balanced mix of source types. Heavy reliance on owned citations means you're essentially citing yourself — which is limited in impact. A strong share of third-party and social citations indicates that external, independent sources trust and reference your brand, which carries more weight with AI engines. If competitor citations are high, those pages may be mentioning you in comparison contexts — worth investigating further. *** ## Most Cited Domains / Most Cited Webpages This section provides a ranked view of the domains and webpages AI cites most when answering prompts in your tracked space. You can toggle between **Webpages** and **Domains** views. ### Webpages View A ranked table of specific pages most frequently cited in AI answers. Each row includes: * **Cited page** — The page URL and title being referenced by AI. * **Citation share** — The percentage of AI answers citing this specific page, with a change indicator. * **Source type** — Whether this page belongs to your brand, a competitor, or a third party. * **Citing answers** — The total number of AI-generated answers referencing this page, with a change indicator. * **Mentions you** — Whether or not this cited page mentions your brand (indicated by a check or cross icon). ### Domains View A ranked table aggregated at the domain level. Each row includes: * **Cited Domain** — The root domain being referenced. * **DR** — The Domain Rating of that domain. * **Citation share** — The percentage of total citations this domain captures, with a change indicator. * **Source type** — Whether this is your brand, a competitor, or a third-party domain. * **Citing answers** — How many AI answers cite pages from this domain. * **Pages cited** — The total number of individual pages from this domain that are being cited. Click **"Show all domains"** or **"Show all webpages"** to expand the full list. **Why it matters:** This table reveals who your real competition is in AI citations — and it may not always be your traditional business competitors. Third-party blogs, news outlets, or community sites can dominate AI citations in your space. Understanding which specific pages and domains hold the most citation share helps you prioritize outreach, content creation, and competitive analysis. *** ## Citation Opportunities This section highlights high-value sources that are citing your competitors but **not yet citing your brand**. These are your most actionable gaps. You can toggle between **Webpages** and **Domains** views. ### Webpages View Each row shows: * **Cited page** — The specific page URL and title. * **Citation share** — How much citation share this page commands, with a change indicator. * **Brands mentioned** — Which competitor brands are mentioned on this page (shown as brand icons). * **Source type** — Whether this is a competitor page or a third-party page. * **Citing answers** — The number of AI answers referencing this page. ### Domains View Each row shows: * **Cited Domain** — The root domain. * **Citation share** — The domain's overall citation share percentage, with a change indicator. * **Brands mentioned** — Competitor brands mentioned across pages on this domain. * **Source type** — Competitor or third-party classification. * **Citing answers** — Total AI answers citing this domain. * **Pages cited** — Total number of pages from this domain that are being cited. Click **"Show all webpages"** or **"Show all domains"** to view the complete list. **Why it matters:** These represent your **highest-impact opportunities**. Since these pages are already trusted by AI engines and actively being cited, getting your brand mentioned or linked on them significantly increases your chances of being included in AI answers. Prioritize outreach to pages with high citation share and high DR for maximum impact. *** ## Top Cited Content This section shows the pages driving the most AI citations — split into two tabs: **Your brand** and **Competitors**. ### Your Brand Tab A ranked list of your own pages that receive the most AI citations. Each row includes: * **Cited Page** — Your page URL and title. * **Citation share** — The percentage of AI citations pointing to this page, with a change indicator. * **Mentions you** — Whether your brand is explicitly mentioned in the citing AI answer (indicated by a check or cross icon). * **Brands mentioned** — Other brands mentioned alongside your content (shown as brand icons). * **Citing answers** — The number of AI-generated answers citing this page. ### Competitors Tab The same table structure but showing your competitors' top-performing pages — so you can analyze what types of content earn the most AI citations in your space. Click **"Show all webpages"** to view the complete list for either tab. **Why it matters:** Your top-cited pages are your **strongest content assets**. Keep them updated, expand their coverage, and study what makes them successful. On the competitors side, analyze their winning pages to understand content formats, depth, and topics that earn the most AI trust — then apply those learnings to your own content strategy. *** ## Your Citation Share vs. Competitors This comparative matrix is one of the most powerful analytical tools on the page. It shows how your citation share stacks up against competitors across two dimensions — **by topic** and **by platform**. ### Analyze by Topic * Rows represent **brands** (your domain and competitors). * Columns represent **topics** you're tracking (e.g., keyword research, link building, optimization, SEO copywriting). * Each cell shows the **citation share** percentage for that brand within that topic, along with a change indicator. * **Green cells** highlight top performers for that topic. **Red cells** indicate bottom performers. * Your brand row is highlighted with a **"You"** tag for easy identification. ### Analyze by Platform * Rows represent **brands**. * Columns represent **AI platforms** (e.g., ChatGPT, Claude, Perplexity, Bing). * Each cell shows the **citation share** for that brand on that specific platform, with a change indicator. * Color coding works the same way — green for leaders, red for lagging brands. Use the **Metric** dropdown to switch between **Citation share** and other available metrics. Pagination controls at the bottom let you navigate through all brands in your tracked competitive set. **Why it matters:** This matrix instantly reveals your strategic positioning. You can identify topics where you dominate and need to defend, topics where competitors lead and you should invest, and platforms where your content performs differently. For example, you might have strong citation share on Perplexity but weak performance on ChatGPT — signaling a need to optimize content specifically for ChatGPT's citation patterns. *** [Missing Prompts](/docs/missing-prompts) [All Citations](/docs/all-citations) # Content Optimization Source: https://apidocs.writesonic.com/docs/content-optimization # Overview **Content Optimization** is Writesonic's advanced GEO (Generative Engine Optimization) solution that helps your content achieve maximum visibility in AI-generated responses across platforms like ChatGPT, Claude, Gemini, and Perplexity. This feature analyzes your existing website content—articles, landing pages, and documentation—to identify specific optimization opportunities that enhance your brand's presence in AI search results. By addressing these optimization points, you can **increase your citation rates by 60-70%** and ensure your brand appears prominently when AI platforms reference content in your industry. *** ## How Content Optimization Works The Action Center scans your indexed content and evaluates it against **proven GEO best practices**. The system analyzes your pages and presents a comprehensive dashboard showing: * **Total issues identified** across your content * **Issue categorization** by optimization type * **Issue count** for each category * **One-click optimization** buttons for immediate action(`Coming soon`) * **Competitive analysis** showing how rival sites are performing * **Citation tracking** to monitor your AI visibility improvements Each piece of content is analyzed for specific optimization opportunities (called "finders") that directly impact how AI models discover, understand, and cite your content. The system provides actionable recommendations tailored to your content type, whether it's a how-to article, product page, or technical documentation. *** ## Understanding the Action Center Dashboard When you access Content Optimization in the Action Center, you'll see: ### **Issues Overview Panel** The main dashboard displays all identified optimization opportunities, organized by category. Each category shows: * **Issue type** (e.g., "Comparison Table is missing") * **Number of sub-issues** found across your pages * **Brief explanation** of why this optimization matters * **"Optimize" button** for immediate action(`Coming soon`) ### **Priority Indicators** Issues are color-coded and marked based on their impact: * 🔺 **Critical issues** (red): Schema markup, title mismatches * 🟡 **Important optimizations** (orange): Key points, FAQs, comparison tables * 🔵 **Enhancements** (blue): Author credentials, brand mentions ### **Competitive Intelligence** The dashboard also shows: * **Competing sites** that are ranking for similar topics * **Current citation status** - whether AI platforms are citing your content * **Performance comparison** against industry benchmarks *** ## Optimization Finders: Complete Guide Below are all the optimization points our system identifies to improve your content's AI visibility. Each finder includes detailed explanations and actionable insights. ### **Content Accuracy & Relevance** ### **Title-Content Mismatch** This finder detects when your page title promises content that isn't fully delivered within the article body. AI models heavily weight title-content alignment when determining source credibility. **What it checks:** * Whether promised features, steps, or information in the title actually exist in the content * If the scope described in the title matches what's covered (e.g., "Complete Guide" should be comprehensive) * Alignment between title keywords and actual content focus **Why it matters:** Mismatched titles create **trust issues** for AI models, leading to lower citation rates and potential exclusion from AI-generated responses. Users also experience higher bounce rates, which AI platforms track as a negative quality signal. **How the Action Center helps:** When this issue is detected, clicking "Optimize" will highlight specific mismatches and suggest title revisions that accurately reflect your content. **Example:** A title saying "10 Best Marketing Automation Tools" should actually review 10 tools, not 7, and should focus on automation specifically, not general marketing software. *** ### **Meta Description-Content Mismatch** This finder identifies when your meta description promises content, features, or benefits not actually present on the page, or when it fails to accurately summarize the content's value proposition. **What it checks:** * Alignment between meta description claims and actual page content * Whether key benefits mentioned in the description are substantiated in the content * If the description accurately reflects the content's depth and scope **Why it matters:** AI models use meta descriptions as **secondary validation** for content relevance. Mismatches signal potential clickbait or outdated content, reducing your authority score in AI algorithms. **In the Action Center:** The system will show you exactly how many pages have this issue (e.g., "5 issues") and provide specific recommendations for each affected page when you click "Optimize." **How to fix:** Ensure your meta description is a truthful, concise summary (150-160 characters) that accurately represents your content's unique value without overpromising. *** ### **Outdated Freshness Indicators** This finder flags temporal indicators (years, dates, version numbers) in titles, content, or schema that are older than 3 months from the current date. **What it checks:** * Year references in titles (e.g., "Best CRM Software 2024") * "Last updated" dates in schema markup * Version numbers for software/technical content * Temporal phrases like "this year," "recently," "latest" **Why it matters:** AI models **prioritize fresh content** and can detect outdated information. Content with old temporal indicators sees a **60-70% reduction** in AI citation probability. This is especially critical for news, technical documentation, and comparison content. **Action Center insight:** The tool will flag all instances with a timestamp showing how outdated each indicator is, allowing you to prioritize updates based on age. **Best practice:** Use evergreen titles when possible, or implement automatic date updating. For time-sensitive content, establish a quarterly review cycle to update temporal indicators. *** ### **Lead-Content Mismatch** *(Landing Pages Only)* This finder detects when the lead section (opening paragraph) makes claims or promises that the rest of the page doesn't fulfill, or when it's too vague to establish clear value. **What it checks:** * If the lead's scope matches the actual product/service offering * if the Freshness indicator in the lead section is updated or not * Alignment between lead section promises and available features **Why it matters:** The lead section receives **3x more weight** in AI content analysis. Mismatches here immediately flag content as potentially unreliable, dramatically reducing citation likelihood. **Example:** A lead claiming "complete digital transformation solution" for a basic CRM tool will trigger this finder. *** ### **Content Structure & Clarity** ### **Self contained Descriptions or not** This finder identifies descriptions that lack specific, self-contained information that AI models can extract and understand independently without additional context. **Why it matters:** AI models need **self-contained, specific information** to generate accurate responses. Vague content is typically skipped in favor of more precise sources, reducing your visibility by up to 40%. **How to fix:** Replace vague statements with specific details. Instead of "improves performance significantly," write "improves page load speed by 40% (from 3.2s to 1.9s)." *** ### **Key Points Needs Optimization** This comprehensive finder evaluates multiple aspects of how key information is presented in your content. In the Action Center, you might see **"6 issues"** under this category, each representing a different aspect needing improvement. ### **Too Long** * **What it checks:** Individual takeaways exceeding 80+ words or 5+ sentences * **Impact:** Reduces scannability and snippet extraction likelihood by 45% * **Fix:** Break long takeaways into concise, single-concept statements under 80 words ### **Wrong Placement** * **What it checks:** Key takeaways positioned at bottom or middle of content instead of near the top * **Impact:** **60-70% higher citation rates** when key information is front-loaded (within first 20% of content) * **Fix:** Move key takeaways to immediately after the introduction or as a highlighted box near the top ### **Missing Structure** * **What it checks:** Takeaways written in paragraph form instead of bullet points or numbered lists * **Impact:** AI models parse structured lists **60% more effectively** than paragraph text * **Action Center guidance:** The tool will show you exactly which sections need restructuring and provide formatting templates ### **Wrong Count** * **What it checks:** Fewer than 3 takeaways (too sparse) or more than 10 (information overload) * **Impact:** Optimal range of 3-7 takeaways shows **highest engagement and citation rates** * **Fix:** Consolidate or expand to hit the 3-7 takeaway sweet spot *** ### **FAQ Optimization** ### **Long FAQ Answers/Questions** This finder identifies FAQ entries that are too lengthy for optimal AI extraction and featured snippet eligibility. **What it checks:** * Answers exceeding 100 words * Questions longer than 15 words * Multiple questions combined into one * Answers containing multiple unrelated concepts **Why it matters:** AI models prefer **concise, focused FAQs** for quick answer extraction. Long FAQs have 50% lower chance of being selected for AI-generated responses or featured snippets. **Best practice:** Keep questions under 10 words and answers between 40-60 words. For complex topics, break into multiple focused Q\&A pairs. *** ### **Product FAQs is Missing** *(Product Pages Only)* When the Action Center shows **"Product FAQs is missing - 1 issue"**, it means your product page lacks specific FAQs that address buyer questions LLMs use for recommendations. **What it checks:** * Presence of product-specific specifications in FAQs * Compatibility and integration questions * Unique use cases or applications * Product-specific troubleshooting **Why it matters:** Generic FAQs provide **no differentiation value** and are often ignored by AI models in favor of competitors with specific information. Product FAQs directly influence AI product recommendations. **Example:** Instead of "Is this product good?" use "Is the XYZ compatible with Windows 11 and ARM processors?" *** ### **Schema FAQ Mismatch** This finder validates that all questions marked up in your FAQPage schema are actually visible on the page. **What it checks:** * Every schema FAQ entry has a corresponding visible element * No hidden or JavaScript-only FAQ content in schema * Schema questions match exact on-page text **Why it matters:** Mismatches can trigger **manual penalties** from search engines and cause AI models to flag your site as potentially deceptive, severely impacting all content from your domain. **Critical:** This is a high-severity issue that can affect your entire site's credibility with AI platforms. *** ### **Comparison Tables** ### **Comparison Table is Missing** When you see **"Comparison Table is missing - 1 issue"** in the Action Center, it means your page lacks structured comparison data that AI systems need for generating recommendations. **What this means:** The page lacks a comparison table. Structured comparison tables enable rich snippets in search results and provide AI systems with clear comparative data for recommendations. **What it checks:** * Presence of tabular comparison data * Table structure and accessibility * Key comparison columns (pricing, features, pros/cons) * Mobile responsiveness of tables **Why it matters:** AI models heavily rely on **structured comparison data** for product recommendations. Pages with proper comparison tables see **3x higher citation rates** in AI-generated comparisons. Tabular data enables direct extraction for AI-generated comparisons. **Optimal structure:** Include columns for: * Product/Service Name * Pricing * Key Features * Pros * Cons * Best For (use case) * User Rating * Integration Options **Action Center solution:** Clicking "Optimize" will provide templates and guidance for adding effective comparison tables to your content. *** ### **Authority & Trust Signals** ### **Missing/Irrelevant Expert Quotes** This finder checks whether your content includes contextually relevant expert quotes with proper credentials to boost E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) signals. **What it checks:** * Presence of at least one expert quote per 1,000 words * Quote relevance to the specific topic **Why it matters:** Expert quotes increase **AI citation confidence by 35-40%**. AI models specifically look for authoritative voices to validate information accuracy. **Best implementation:** Include quotes like: *"According to Dr. Sarah Chen, Chief Data Scientist at TechCorp with 15 years in ML development, 'This approach reduces training time by 60% while maintaining accuracy.'"* *** ### **Missing Author Credentials** This finder verifies that content displays author information with professional credentials rather than generic attributions. **What it checks:** * Author name visibility and placement (preferably at top) * Professional credentials and experience mentioned * Author bio or author schema markup present * Specific expertise related to content topic **Why it matters:** AI models assign **higher trust scores** to content with identified expert authors. Generic bylines like "Admin" or "Editorial Team" reduce citation probability by 25%. **Optimal format:** "By Jane Roe, Senior Tech Analyst | 10+ years in Cloud Architecture | AWS Certified Solutions Architect" *** ### **Missing Brand Mention** This finder verifies that your brand name appears naturally within the content to establish ownership and enable AI source attribution. **Why it matters:** Without brand mentions, AI models may **attribute your content to competitors** or fail to build brand association with your expertise areas. **How to implement:** Naturally incorporate your brand when discussing unique features, case studies, or differentiators: "At Writesonic, we've found that..." or "Our Writesonic platform enables..." *** ### **Technical & Schema Elements** ### **Schema Markup Needs Optimization** When the Action Center shows **"Schema Markup needs optimization - 1 issue"**, it indicates missing or incomplete structured data that's critical for AI understanding. Machine-readable data increases AI extraction accuracy by 3x. **What it checks by content type:** **Articles (How-to, Listicle, News, etc.):** * **Article/BlogPosting**: Basic article classification * **HowTo**: Step-by-step guides with clear instructions * **NewsArticle**: Time-sensitive news content * **TechArticle**: Technical documentation and guides * **FAQPage**: When FAQ section exists **Product/Service Pages:** * **Product**: Core product information and specifications * **Review**: Individual customer reviews * **AggregateRating**: Overall rating summary * **Offer**: Pricing and availability **Landing Pages:** * **Organization**: Company information and credibility * **LocalBusiness**: Location-based information * **Service**: Service descriptions and categories **Universal Requirements:** * **BreadcrumbList**: Site navigation hierarchy * **VideoObject**: When video content is embedded **Why it matters:** Proper schema markup increases **AI content understanding by 80%** and is often required for inclusion in AI knowledge bases. Missing schemas mean your content may be completely invisible to some AI platforms. **Action Center benefit:** The tool identifies exactly which schema types are missing and provides implementation code snippets. *** ### **Meta Title Needs Optimization** When you see **"Meta Title needs optimization - 4 issues"** in the dashboard, it means multiple pages have titles that don't effectively help LLMs match content to user queries. **What it checks:** * Title length (50-60 characters optimal) * Title x content relevancy * Fresh Indicator in the title is updated or not **Why it matters:** Descriptive titles help LLMs match content to user queries. Titles are the **first signal** AI models evaluate for relevance. **Quick wins:** The Action Center will prioritize high-traffic pages for title optimization, showing potential citation improvement for each change. *** ### **Meta Description Needs Optimization** Seeing **"Meta Description needs optimization - 5 issues"** indicates multiple pages where context summaries aren't enabling LLMs to assess content relevance faster. **What it checks:** * Description length (150-160 characters) * Accurate content summary * Freshness Indicator in the description is updated or not **Why it matters:** Context summaries enable LLMs to assess content relevance faster, improving your **selection rate by 45%** for AI responses. *** ### **Outdated dateModified** This finder flags when the dateModified property in your schema markup is older than 3 months. **What it checks:** * Last modification date in all schema types * Consistency between claimed updates and actual content changes * Alignment with temporal indicators in content **Why it matters:** AI models use dateModified as a **primary freshness signal**. Outdated timestamps reduce citation probability by 60-70%, especially for technical, news, and comparison content. **Best practice:** Automatically update dateModified when making substantial content changes, not just minor edits. Implement a review system to ensure regular content updates. *** ### **Instructional Content** ### **Missing Step-by-Step Instructions** *(Free Tools/How-to Content)* This finder detects when instructional content lacks clear, numbered steps, reducing extraction for how-to featured snippets. **What it checks:** * Presence of numbered or bulleted steps * Each step as a distinct, actionable item * Logical sequence and completeness * Self-contained instructions without external dependencies **Why it matters:** Clear step-by-step instructions have **40% higher chance** of being selected for how-to rich snippets and AI instructional responses. **Example of good structure:** 1. Click the "Upload" button in the top menu 2. Select your CSV file (max 10MB) 3. Choose delimiter type (comma, tab, or semicolon) 4. Click "Process" and wait for results 5. Download the cleaned file using the green "Download" button **Poor structure:** "First you need to upload your file then select the settings and process it before downloading the results." *** ## Working with the Action Center ### **Prioritizing Optimizations** When you see multiple issues in your dashboard (e.g., "18 issues" total), prioritize based on: 1. **Critical technical issues** (Schema markup, FAQ mismatches) 2. **High-impact content issues** (Title mismatches, missing comparison tables) 3. **Authority signals** (Expert quotes, author credentials) 4. **Enhancements** (Brand mentions, meta optimizations) ### **Using the Optimize Button** Each issue category has an **"Optimize"** button that: * Provides detailed issue breakdown by URL * Offers specific fix recommendations * Shows before/after examples * Estimates citation improvement potential ### **Tracking Progress** The Action Center tracks: * **Issues resolved** over time * **Citation improvements** from optimizations * **Competitive positioning** changes * **AI visibility trends** *** ## Optimization Matrix by Content Type Below is a comprehensive matrix showing which optimization finders apply to each content type: | **Finder** | **How-to** | **Listicle** | **News** | **Comparison** | **Technical** | **Landing** | **Product** | **Documentation** | **Free Tool** | | - | - | - | - | - | - | - | - | - | - | | Title-Content Mismatch | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Outdated Freshness Indicators | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Meta Description Mismatch | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Schema Markup Issues | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | FAQ Enhancements | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Expert Quotes | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | - | | Key Takeaways/Points | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | - | - | | Authority Signal | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | - | | Brand Mention | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | - | - | | Comparison Table | - | ✓ | - | ✓ | - | - | ✓ | - | - | | Lead Section | - | - | - | - | - | ✓ | - | - | - | | Product-Specific FAQs | - | - | - | - | - | - | ✓ | - | - | | How-to Instructions | - | - | - | - | - | - | - | - | ✓ | *** ## Frequently Asked Questions ### **Q: What does "Competing sites" section show?** **A:** This section displays competitors who are successfully getting cited by AI platforms for similar topics. It helps you understand what optimization standards you need to meet or exceed. ### **Q: Which optimizations have the highest impact on AI visibility?** **A:** Based on the Action Center data, **Schema markup**, **comparison tables**, and **key points optimization** show the highest impact, with proper implementation increasing citation rates by 60-70%. ### **Q: Can I export the optimization report?** **A:** Yes, click the "Export" button in the top-right corner to download a detailed CSV or PDF report with all issues, recommendations, and priority scores. ### **Q: What happens when I click "Optimize" for an issue?** **A:** You'll see: * Specific pages affected * Detailed problem description * Step-by-step fix instructions * Examples of proper implementation * Estimated impact on AI visibility ### **Q: Do all finders apply to every piece of content?** **A:** No, finders are intelligently applied based on your content type. The Action Center automatically detects your content type and only checks relevant optimizations. ### **Q: What's the difference between GEO and traditional SEO?** **A:** While SEO optimizes for search engine rankings, **GEO focuses on AI model comprehension and citation**. The Action Center specifically targets optimizations that help AI models understand and reference your content confidently. ### **Q: Can Content Optimization help with AI hallucination issues?** **A:** Yes, by implementing clear structure, proper schema markup, and authoritative signals, you help AI models accurately understand and cite your content, **reducing the likelihood of misrepresentation** in AI-generated responses. ### **Q: How does the "Answers citing your page" section work?** **A:** This section tracks when AI platforms actually cite your content in their responses. As you implement optimizations, you'll see this number increase, providing direct ROI measurement. *** ## Get Started with Content Optimization Ready to maximize your brand's AI visibility? The Action Center's Content Optimization feature provides a **comprehensive roadmap** to ensure your content ranks prominently in AI-generated responses. With clear issue identification, one-click optimization guidance, and competitive intelligence, you have everything needed to dominate AI search results in your industry. **Access the Action Center** in your Writesonic dashboard or contact your account manager to begin your GEO optimization journey today. *** [Action Center: Actionables](/docs/action-center-actionables) [Prompt Explorer](/docs/prompt-explorer) # Dashboard Source: https://apidocs.writesonic.com/docs/dashboard # Dashboard Overview The **Overview** page is your central dashboard for tracking how your brand performs across AI-generated search results. It consolidates visibility, citations, competitor benchmarks, sentiment, and prompt-level data into a single view — giving you a quick read on where your brand stands and where to take action. This is the first page you see when you open your GEO project. The Overview page has four tabs: **General**, **Platforms**, **Competitors**, and **General (Old)**. This document covers the **General** tab. *** ## Global Filters The filters bar at the top controls the scope of data across every section on the page. * **Date Range** — Define the reporting window with a start/end date or quick presets. Enable a **comparison period** (vs.) to benchmark against a previous range. * **Markets** — Filter by country + language combination. Defaults to *All markets*. * **Topics** — Narrow results to specific topics you're tracking. * **Platform** — Isolate data for a specific AI platform (e.g., ChatGPT, Perplexity, Gemini, Claude, Copilot). * **Prompt Type** — Toggle between **Branded** and **Non-branded** prompts. * **Save & Presets** — Save filter combinations for quick reuse. *** ## Your Brand's Performance Across Key Metrics A top-level row of metrics providing a quick health check. Each includes a **trend indicator** comparing the current period to the prior one. * **AI Visibility** — Percentage of tracked AI answers where your brand is mentioned. This is your **primary GEO metric**. The count below shows raw mentions out of total tracked answers. * **Share of Voice** — Your brand's share of total mentions relative to tracked competitors — essentially your AI market share. * **Citation Share** — Percentage of all AI source citations pointing to your website versus competitors. Citations signal **trust and authority**. * **Pages Mentioning You** — Number of third-party pages cited in AI answers that also mention your brand. Reflects your **off-site digital footprint**. * **Sentiment** — Overall tone (Positive, Neutral, Negative) with which AI platforms describe your brand, shown as a percentage split. *** ## Action Centre A banner below the key metrics showing the total number of **optimization opportunities** available. Click **Act now** to access prioritized recommendations — ranked by impact and effort — to start closing visibility gaps immediately. *** ## Visibility Trend A line chart tracking your AI visibility score over time, with the **previous period** overlaid for comparison. * Toggle between **Visibility** and **Citation** metrics via the dropdown. * Switch between **Daily** and **Weekly** granularity. * Hover over any data point for exact values. Use this to measure the real-world impact of your GEO efforts over days and weeks. *** ## Leaderboard Ranks your brand against all tracked competitors on two metrics: * **AI Visibility (%)** — Percentage of AI answers mentioning each brand. * **Citation Share (%)** — Percentage of AI source citations each brand receives. Your brand is tagged as **You** for easy identification. Each row includes trend indicators. Use it to see who's ahead, who's gaining momentum, and where you need to close the gap. *** ## Platform-Wise Performance Breaks down AI Visibility and Citation Share **by individual AI platform** — ChatGPT, Perplexity, Gemini, Copilot, LlamaAI, Claude, and others. Each row shows the metric percentage plus period-over-period change. Not all platforms behave the same way — use this to pinpoint platform-specific gaps and tailor your strategy accordingly. > Click **View full report →** to open the detailed Platforms tab. *** ## How AI Talks About Your Brand A **word cloud** of key themes AI platforms associate with your brand. Larger words appear more frequently. Includes a mention count (e.g., *"Mentioned 123 times"*) for volume context. Themes range from product attributes (e.g., *"User-Friendly Interface"*) to use cases (e.g., *"Helpful for Academic Research"*). This tells you not just *if* you're mentioned, but *how* you're being described — critical for brand positioning. *** ## Share of Voice A **donut chart** showing your brand's percentage of total AI mentions versus competitors. Your brand is labeled **You**. A shrinking slice signals competitors are gaining ground; a growing slice validates your GEO strategy. *** ## Brand Rank Distribution Shows the **position** at which your brand appears within AI answers (1st rank through 5th rank and more). For each rank, you'll see: * **Percentage** — Proportion of your mentions at that rank. * **Answers** — Absolute number of AI answers at that position. Being mentioned **first** is significantly more impactful — AI answers are consumed top-down, and the first brand referenced gets the most attention. *** ## Your Top Cited Content Lists the **specific pages from your website** most frequently cited as sources in AI answers. For each page: * **Cited Page** — URL and page title. * **Citation Share (%)** — Percentage of total citations, with trend. * **Citing Answers** — Number of AI answers citing this page, with period-over-period change. These are your **highest-performing AI assets** — keep them updated and authoritative. > Click **Show all webpages →** for the full list. *** ## Most-Searched Prompts by Users Surfaces the **most popular prompts** relevant to your brand, ranked by search volume. For each prompt: * **Search Volume** — How frequently it's searched. * **AI Visibility (%)** — Your visibility for this prompt, with trend. * **Answers** — Total AI answers tracked, with change. **High search volume + low visibility = your biggest growth opportunity.** > Click **Show all popular prompts →** to explore the full list. *** ## Your Brand Visibility Across Prompts A prompt-level breakdown with two tabs: * **Mentions you** — Prompts where your brand appears in AI answers. * **Does not mention you** — Prompts where your brand is absent. Each row shows the prompt, search volume, AI visibility %, and answer count. The **"Does not mention you"** tab reveals the exact conversations your brand is missing from — your highest-priority targets for content and outreach. > Click **Show all prompts driving visibility →** for the complete breakdown. *** *** [Why We Monitor Real AI Platforms, Not Just APIs](/docs/why-we-monitor-real-ai-platforms-not-just-apis) [Getting Started: Onboarding and Configuring Your Brand](/docs/getting-started-onboarding-and-configuring-your-brand) # Overview Source: https://apidocs.writesonic.com/docs/geo-getting-started AI search engines like ChatGPT, Google AI Overviews, and Bing Copilot are changing how people search. Instead of browsing links, users now get direct, AI-generated answers. That means your brand’s visibility depends less on traditional rankings and more on whether you’re cited or mentioned inside those answers. ### What is GEO? GEO (Generative Engine Optimization) is the practice of making sure your brand shows up in AI-powered responses. Instead of optimizing only for Google search results, GEO focuses on where it really matters today: being referenced and trusted by AI systems when customers ask about your industry, products, or services. AI engines often highlight just a few brands. If you’re missing from those mentions, you risk being invisible, even if your website ranks well in traditional search. Writesonic gives you the tools to monitor and improve your brand’s presence across AI platforms. With Writesonic, you can: * **Track** when and where your brand is cited in AI-generated answers. * **Benchmark** against competitors to see who’s winning visibility you’re missing. * **Spot gaps** where competitors are mentioned but you’re absent. * **Take action** with clear, AI-powered recommendations to improve your citations. In short, GEO helps you stay visible, competitive, and trusted in the new era of AI-driven search. ## What You’ll Learn in This Guide This article will walk you through: 1. **Setting up your first GEO project**: connecting your site, choosing topics, prompts, and competitors. 2. **Exploring the GEO dashboard**: understanding the key metrics that reveal your AI visibility. 3. **Prioritizing what matters and taking action**: which numbers and insights to focus on first and how to improve your AI visibility 4. **Best practices for GEO**: proven ways to strengthen your visibility and stay competitive. 5. **Measuring GEO success:** how to check the impact of your GEO strategies Together, these steps will give you everything you need to move from setup to strategy. You’ll start by creating your first project, then learn how to interpret your visibility metrics, and finally discover how to turn those insights into action. When you log in to Writesonic, the first thing you’ll do is set up your project. This project is the foundation of everything GEO will track for you. Let’s walk through the process step by step. ## Step 1: Create Your First GEO Project Start by entering your **website URL** for which you want to monitor and improve AI visibility. For most users, that’s your homepage, like [https://www.yoursite.com](https://www.yoursite.com). This tells GEO which brand it should be monitoring across AI search engines. Once you’ve entered your website, set the **Scope**. This setting controls how much of your site GEO should analyze. By default, it’s set to **Domain**, which means GEO will cover your entire site. If you don’t need everything tracked, narrow it down to: * Select **Exact URL** if you want to monitor a single page, like a campaign landing page. * Choose **Path** when you want to track only a section of the site, such as /blog/ or /shop/. * Pick **Subdomain** if you want to track only one subdomain, like shop.yoursite.com. Still unsure? Stick with **Domain**. It’ll give you a complete view of your website, all URLs, paths, and subdomains included. Next, choose your **Primary Target Location**. This is the country or region where you want GEO to monitor AI visibility. If your business mostly serves US customers, select *United States*. If you work across multiple regions, just pick the most important market to begin. You can add more regions later (for enterprise users only). Finally, give your project a **Name**. Keep it simple and descriptive, like *Your Brand — US* or *Your Brand — Europe*. Once everything is filled out, click **Continue**. ### Choose How You Want to Get Started You’ll be able to choose from two options based on how you’d like to use Writesonic: * **SEO and Content Optimization**: If you want to use Writesonic for traditional keyword research and on-page SEO. * **Optimize for AI Search Engines**: If you want to use Writesonic for GEO. It’s designed to track your brand’s visibility inside generative AI platforms like ChatGPT, Google AI Overviews, and Bing Copilot. As we are discussing how to set up your account for GEO, let’s choose the **Optimize for AI Search Engines** option. Click **Continue** and GEO will start preparing your first **AI visibility snapshot**. Once the setup is complete, it’s time to tell GEO what your business is about. ### Create a Market Track your brand's AI visibility across multiple countries and languages within a single GEO project. Markets enables multi-region monitoring of how AI platforms like ChatGPT, Claude, and Perplexity represent your brand. **How to set up a market** During the GEO project setup (Step 1 of 5), you'll see the "Where do you want to track your brand?" screen. GEO will analyze AI responses for users in this region searching in this language and find relevant competitors in your market. **Target country:** Select the geographic region you want to monitor from the dropdown (e.g., India, United States, Canada, United Kingdom) *Note: Some AI platforms may have limited availability in certain regions. You'll see a warning indicator if this applies to your selected country.* **Language:** Choose the language for AI visibility tracking (e.g., English, Spanish, French, German) **Homepage URL:** for this market (Optional): If you have a region-specific domain or subdomain, enter it here (e.g., [https://cardekho.com](https://cardekho.com) for India, ca.yoursite.com for Canada). This field shows "(Already set)" if you've previously configured a homepage URL during initial setup. *Once you've configured these settings, click Continue to proceed to the Topics step.* ### Choose Your Topics You’ll be asked to **choose 2 to 10 topics** that best describe what you do or what categories you want to compete in. These topics are also later used to craft prompts that you need to track for your business. You can choose from a list of **predefined topics**. These are automatically suggested by GEO based on an AI analysis of your website and brand. Or, you can add topics yourself. Type in a topic in the entry field and click **Add** to include it in your list. Select at least two topics to continue, and you can choose up to ten. ***Pro Tip:** When choosing topics, think about the words your customers would actually use when asking about your products or services.* *For example, instead of your product name “Model X Jacket,” you might add “affordable winter jackets” or “sustainable outerwear.” In SaaS, instead of “AppPro Suite,” you might add “AI writing tools” or “SEO automation software.”* ### Prompts Prompts are the questions and queries that GEO tracks across 10+ AI platforms. They represent natural-language questions your customers ask AI search engines when researching products or services. What are prompts? Real questions people ask AI tools like ChatGPT, Claude, and Perplexity. GEO generates a mix of prompts based on your topics and analyzes how your brand shows up in the responses. **How to add prompts** Automatic topic-based generation (recommended) During the project setup flow (Step 3 of 4), you'll see the "How many prompts do you want to generate?" screen: 1. Use the slider to select how many prompts you want GEO to generate (e.g., range: 0-222) 2. The system shows your account-level prompt usage (e.g., "Use 30 / 222 available prompts") 3. Choose a number that balances comprehensive coverage with your plan limits 4. Click Continue to proceed ### Review and Refine Your Prompts After you’ve added your topics, GEO automatically generates a set of **prompts**. These prompts represent the kinds of questions people might ask in AI search engines — and they’re what GEO will monitor to see when and where your brand shows up. GEO uses your chosen topics to build this list automatically, so you get an immediate sense of the kinds of answers where your brand could (or should) appear. Take a few minutes to go through the list. Prompts are categorized based on the topics you chose earlier, so it’s easier to sort through. Many of the prompts will be directly relevant, but you may also spot some that don’t fit your focus. If a prompt isn’t useful, you can simply deselect it. You can also add your own prompts. Just click on the **Add Prompt** button, type in your prompt, and click on **Save Prompt**. You can check the newly added prompt by scrolling to the bottom of the list. ### Add Your Competitors After you’ve selected the required prompts, the next step is adding your competitors. This is important because GEO doesn’t just show you how *you* appear in AI search results — it also benchmarks you against others in your space. That way, you can see where your brand is cited, where competitors are mentioned instead, and what opportunities you may be missing. GEO will automatically show you a **list of competitors** it has identified for your brand. These are suggested based on AI’s analysis of your website, industry, and market. Review the list carefully. You can also manually add competitors by pasting their website URL into the field and clicking **Add**. You don’t need to add everyone at once. Even starting with a few key competitors will give you meaningful comparisons. Later, you can always edit the project to expand the list as your strategy grows. Once you’re happy with the competitor list click **Continue** to move ahead. GEO will then begin **fetching your AI search insights**. You’ll see a short loading screen while the system pulls data from AI engines. This step is where everything comes together: your website, chosen scope, topics, prompts, and competitors. GEO now uses that foundation to map out how you and your competitors show up in generative AI answers. Once this process is complete, you’ll land inside your dashboard where you can explore your first set of AI visibility results. *The report can take a few minutes to generate. Don’t want to wait around? Explore other tools like the AI Article Writer or SEO & Content AI Agent in the meantime. You’ll get a notification once the AI search insights report is ready.* Now that your dashboard is live, you’re ready to start exploring your AI visibility. From here, you can dive deeper into specific features to understand how they work and what they mean for your brand. ## Step 2: Explore Your Writesonic Dashboard Writesonic provides a granular view of your AI visibility. It shows you exactly which prompts you are mentioned and cited in, where your competitors are present but not you, and what you can do to get cited in those prompts as well. But at first glance, the number of metrics and pages displayed can be confusing. If you’re new to GEO, you can focus on some key metrics and pages to begin with. Let’s start with the core metrics. ### Core Metrics These are the numbers you see first on your dashboard. They give a quick snapshot of how your brand is performing in AI search. * **Visibility** gives you the percentage of prompts that mention your brand in the directly in the generated answers. Ideally, this should be green, as it indicates a good AI presence. But if you’ve still not optimized for GEO, your visibility might be low and in red. Use this metric as a measure of success for any GEO strategies you implement to increase your brand mentions. * **Answers Mentioning Me** corresponds to the visibility % and shows you the exact number of answers that mention your brand. This is relative to the prompts you’ve configured and there’s no ideal number of answers here. * The **Citations** section shows you all the AI-answers where your brand’s website is cited as a source. You can see: * **Total pages cited**: All pages (yours and competitors’) that AI engines are pulling from. * **My pages cited**: The number of your site’s pages cited in AI answers. * **Pages mentioning me**: Third-party or competitor pages that are cited and also mention your brand in their content * The **Competitor Analysis** section shows you a quick overview of how you perform against your competitors: * **Market share**: The percentage of overall AI visibility you hold compared to competitors. * **Market position**: Your ranking among competitors based on visibility. Clicking on any of these gives you a more detailed view of that particular metric. For example, clicking on the **Total Pages Cited** leads to the **All Citations** page: You can also check how your brand is doing for the past week or month in the **Visibility Trends Over Time** section: Other sections like the **AI Visibility Leaderboard**, **Platform-wise Brand Visibility**, **Market Share**, etc.. help understand the specifics. Want more details about a specific metric? The sidebar links to several pages that go into detail about your brand’s sentiment, citations, and mentions: Now we’ve covered exactly what data you can view through Writesonic. But what numbers to prioritize and how to actually build workflows? Let’s see in the next section. ## Step 3: Prioritize and take action Your dashboard shows a lot of data, but you don’t need to act on everything at once. The most important things to focus on are: * **Mentions**: how many AI answers include your brand. Use the Visibility % as your main measure here. * **Citations**: how often your site is being used as a source. Compare **My Pages Cited** with **Total Pages Cited**. The closer your number is to the total, the stronger your brand authority. Think of mentions as *awareness* and citations as *trust*. To grow in GEO, you need both. ### Simple Workflows to Take Action Here are a few easy workflows that connect what you see in the dashboard to real actions you can take: * **Low visibility % (not enough mentions)** Go to the **Citation Opportunities** page. This shows sites that are already cited in AI answers but don’t mention your brand. Click on the **Total Opportunities** number next to a domain, and you’ll see the exact pages. Reach out to those sites and ask to get your brand included. Since those pages are already trusted by AI, adding your brand increases your chance of being mentioned in the same answers. * **Very few of your own pages are cited** If **My Pages Cited** is much lower than **Total Pages Cited**, it means competitors’ pages are being chosen instead. Review those competitor pages directly: look at how they’re structured, what kind of information they provide, and why AI might prefer them. Then, strengthen your own content to match or improve upon those qualities. * **Mentions are there, but not on the right topics** Sometimes you’ll see mentions, but not in the areas that matter most for your business. Go back to your **Topics and Prompts** setup. Adjust your topics or add new prompts that match how customers actually search, so you track the areas where you want visibility. You don’t have to figure out all the next steps on your own. The **Action Center** automatically analyzes your data and suggests the highest-impact things to do. ### Using the Action Center The Action Center highlights the most impactful actions you can take to boost visibility. It groups tasks by category: like getting external mentions, boosting content visibility, or fixing technical issues, and shows the effort required, impact level, and the number of action items available. ### **Example: Getting External Mentions** Let’s take an example from the Action Center: **“Get mentioned on high-authority third-party sites.”** 1. Click **Address now** next to this action. 2. You’ll see a list of specific pages that are already cited in AI answers but don’t mention your brand. These are golden opportunities because AI engines already trust these pages. 3. From here, you can view details like domain authority, the number of missed answers, and which platforms are pulling from those pages. 4. GEO even gives you a ready-made outreach workflow. Click on the **Draft Email** button, and you’ll see guidance on how to find the right contact plus a **personalized email draft** you can send to request inclusion of your brand. By following this process, you’re targeting the exact sources that influence AI-generated answers without any guesswork. ## Step 4: Best practices for GEO The workflows and Action Center give you clear, immediate steps to improve your visibility. But GEO isn’t just about quick fixes — long-term success comes from following best practices that make your brand more trustworthy to AI engines. Here are a few practices to build into your ongoing strategy: ### Structure your content for clarity AI engines look for clear, well-organized content they can trust when generating answers. Use: * Short, descriptive headings and subheadings. * Concise paragraphs that answer questions directly. * Lists, tables, and bullet points where it makes sense. This makes your content easier for AI to parse and cite, increasing the chances it will show up in answers. ### Strengthen your presence on authoritative sites AI engines lean heavily on trusted, high-authority domains. Being mentioned on these sites improves your odds of showing up in generative answers. Beyond outreach through the Action Center, look for opportunities like: * Guest contributions to industry publications. * Getting featured in expert roundups or comparison articles. * Collaborating with partners who already rank well. ### Don’t ignore community platforms Communities like Reddit, Quora, and niche forums are often cited in AI answers, especially for questions where people want real experiences or peer advice. Building a presence there by contributing genuine, helpful input can get your brand into answers indirectly, even when your website isn’t cited. ### Keep refreshing and expanding content Outdated pages are less likely to be trusted by AI engines. Review your cited pages regularly, add new data or insights, and expand coverage of important topics. Think of this as maintaining your “AI-facing” authority over time. ### Align with customer language Remember: AI engines mirror how people search and ask questions. Use the same words and phrasing your customers do in their queries. This not only improves your relevance but also increases the chance that AI connects your brand to the right prompts. ## Step 5: Measuring GEO Success After you’ve implemented workflows and followed best practices, the next step is to measure whether your efforts are paying off. GEO makes this straightforward by surfacing key metrics on your dashboard that reveal both progress and impact. Here’s what to track: ### Visibility Percentage This is your primary success metric. If your visibility score is increasing over time, it means your brand is appearing in more AI answers. Think of it as your “AI market share of mentions.” Any rise here is a clear sign your optimizations are working. ### Answers Mentioning Me This shows the raw number of AI answers that include your brand. Look for steady growth in this number across reporting periods. If it’s flat or declining, revisit your prompts or refresh content to capture more mentions. ### My Pages Cited This tells you how many of your own pages are being used as sources. Growth here means AI engines are trusting your content more often. Pay special attention to which pages are being cited — those pages are your strongest assets and worth updating regularly to keep their authority. ### Market Share and Market Position These competitor metrics reveal if you’re gaining ground relative to others in your space. If your market share is climbing or your position is improving, it means you’re not just improving visibility, you’re outpacing competitors. ### Visibility Trends Over Time Finally, look at the trend graph. This shows the trajectory of your performance: whether you’re consistently moving upward, holding steady, or losing ground. Even small improvements in the line over time show your strategy is working. *** [Fair Usage Policy](/docs/fair-usage-policy) [AI Bot(Traffic) Analytics](/docs/ai-traffic-analytics) # Getting Started: Onboarding and Configuring Your Brand Source: https://apidocs.writesonic.com/docs/getting-started-onboarding-and-configuring-your-brand ### Why do you need to configure your brand? As explained in [this](https://docs.writesonic.com/update/docs/why-we-monitor-real-ai-platforms-not-just-apis) section, we aim to simulate how users interact with AI models with respect to your brand. To do this, we need a wide variety of prompts that reflect real user behaviour. We will automatically create a list of suggested prompts on the basis of the topics you are targeting for your brand. Additionally, since the data collected is based on simulated prompts, it's important to analyze your performance on a relative scale compared to your key competitors. To support this, we will need a list of your primary competitors so we can include them in performance tracking and benchmarking. ### What to Expect During Onboarding When you first enter the Brand Presence module, an intuitive onboarding flow walks you through configuring your visibility tracking setup. The goal is to: 1. **Select topics** to track where you want visibility 2. **Configure prompts** to simulate user behaviour on different AI models 3. **Specify competitors** to benchmark performance against This flow is designed to help both beginners and experienced users get started quickly and accurately. Each step includes: * Inline help descriptions * Input examples (e.g., brand name, topics) * Visual indicators of where that input will impact your dashboard *** ## First Steps ### Navigate to the Brand Presence Screen This screen shows examples of insights you’ll gain once setup is complete. You can click on the "Start Tracking" button to get started. ## Next Steps ### [Step 1 – Set your target topics](https://docs.writesonic.com/docs/set-you-target-topics#/) ### [Step 2 - Review and modify prompts](https://docs.writesonic.com/docs/review-and-modify-prompts#/) ### [Step 3 – Select Competitors](https://docs.writesonic.com/docs/select-competitors#/) *** What’s Next * [Set your target topics](/docs/set-you-target-topics) # Integrating With Cloudflare Source: https://apidocs.writesonic.com/docs/integrating-with-cloudflare ## Prerequisites * An active Writesonic account * Admin access to your Cloudflare website * Your website must be using Cloudflare (if you're not, see alternative options below) ### Phase 1: Start in Writesonic 1. Head over to the [AI Traffic Analytics page](https://app.writesonic.com/geo/ai-traffic-analytics) on Writesonic 2. Click on **"Set Up Cloudflare Integration"** 3. You'll see a modal like this appear on the screen. Now, you need to head over to your Cloudflare account and set up an API key. ### Phase 2: Ensure Proper Cloudflare Proxy Settings In your Cloudflare DNS settings, ensure the orange cloud icon is turned ON for your domain records (indicating "Proxied" status). For AI Traffic Analytics to work properly, the orange cloud proxy toggle must be enabled as shown in the image below. This allows Cloudflare to properly intercept and record AI crawler traffic. ### Phase 3: Create API Token in Cloudflare 1. Go to the [API Tokens page](https://dash.cloudflare.com/profile/api-tokens) on your Cloudflare dashboard. 2. Click on `Create Token` 3. Click the `Use Template` button next to **"Edit Clouldflare Workers"**. ### Phase 4: Configure Token Permissions 1. On the next screen, scroll down to "Permissions". Click on the cross buttons to remove all permissions apart from **"Worker Routes"** and **"Worker Scripts"**. It should look like this: 2. Scroll down and select your Cloudflare account under the **"Account Resources"** dropdown. 3. Additionally, choose the domain that you would like to install the analytics on from the **"Zone Resources"** dropdown. ### Phase 5: Create and Copy Token 1. Click on **"Continue to Summary"**. 2. And then click on **"Create Token"**. 3. Next, click on the "Copy" button to copy your API token. ### Phase 6: Complete Setup in Writesonic 1. Now, go back to Writesonic. Enter your copied API token and click on **"Continue"**. 2. On the next screen, some of the values should be prefilled. Make sure that: 1. the correct account is showing under Cloudflare Account. 2. Correct domain is selected under Cloudflare Zone. 3. Route Path should be `(subdomain).example.com/*` if your Cloudflare Zone is `example.com`. > **NOTE:** **The wildcard character is not allowed in the subdomain.** **Adding a subdomain is optional.** 3. Click on the Finish button and your Analytics should be deployed in a couple of seconds. ### Verify Installation To test if the Analytics has been set up properly, go to ChatGPT and with **GPT-4o** model selected with "Search" enabled, try running a query like: ``` Research and tell me about yourwebsite.com. ``` where `yourwebsite.com` should be replaced with your website domain. Now, go back to Writesonic and you should start seeing the requests on your Analytics. ## Alternative Implementation Methods Additionally, we support native integrations to Wordpress and Vercel. We are coming up with various other integrations like Shopify, Webflow, Python, Javascript, etc. ## Troubleshooting If you encounter any issues during setup: * Ensure your Cloudflare account has the correct permissions * Check that your selected domain is active in Cloudflare * Verify that no conflicting Workers are running * For assistance, contact [\[email protected\]](/cdn-cgi/l/email-protection#77040207071805033700051e03120418191e145914181a) For more detailed debugging, please check out the [Toubleshooting and FAQs](https://docs.writesonic.com/docs/ai-traffic-analytics-troubleshooting-and-faqs#/) page. *** [Setup and Implementation Guide](/docs/ai-traffic-analytics-setup-and-implementation-guide) [Integrating with Wordpress](/docs/integrating-with-wordpress) # Integrating with Cloudfront Source: https://apidocs.writesonic.com/docs/integrating-with-cloudfront This guide walks you through the process of implementing AI Bot Analytics on your Cloudfront website using AWS CloudFormation stack. ## Prerequisites * An active Writesonic account * An existing AWS CloudFront distribution * AWS Account with permissions to: * Create CloudFormation stacks * Modify CloudFront distributions * Create IAM roles and policies * Create S3 buckets and Kinesis streams ## Phase 1: Start in Writesonic 1. Head over to the AI Bot Analytics page on Writesonic and choose 'Cloudfront' as a provider 2. Click on 'Continue' to initialize the integration 3. Writesonic will provide you the following information that you'll need during the AWS configuration: * CloudFormation Template File * Writesonic API Key ## Phase 2: Create CloudFormation Stack ### Step 1: Access CloudFormation Service 1. Log in to your AWS Management Console 2. Navigate to the CloudFormation service 3. Click on **"Create stack"** to begin the stack creation process ### Step 2: Upload Template 1. On the "Create stack" page, select **"Upload a template file"** 2. Click **"Choose file"** and upload the CloudFormation template provided by Writesonic 3. Click **"Next"** to proceed ### Step 3: Configure Stack Details 1. Specify the following stack parameters: | Parameter | Value | Description | | - | - | - | | **DataStreamShardCount** | `1` | Number of shards for the Kinesis Data Stream | | **EnableEnhancedMonitoring** | `False` | Enhanced monitoring setting | | **S3BucketPrefix** | *Your desired bucket name* | Prefix for the S3 bucket that will store logs | | **WritesonicAPIKey** | *Your API key* | API key provided by Writesonic | | **WritesonicIngestionDomain** | `ingestion.writesonic.com` | Writesonic ingestion endpoint | 2. Click **"Next"** after entering all parameters. ### Step 4: Configure Stack Options 1. Review the stack options (no additional configuration required) 2. Click **"Next"** to continue ### Step 5: Review and Create 1. Review all stack configuration details 2. Check the acknowledgment box confirming that CloudFormation might create IAM resources 3. Click **"Submit"** to create the stack ### Step 6: Wait for Stack Creation 1. Monitor the stack creation progress in the CloudFormation console 2. Wait for the status to change to **"CREATE\_COMPLETE"** 3. This process typically takes several minutes ## Phase 3: Configure CloudFront Distribution Logging ### Step 1: Access CloudFront Distribution 1. Navigate to the CloudFront service in AWS Console 2. Locate and select the CloudFront distribution you want to monitor 3. Click on the **"Logging"** tab ### Step 2: Configure Real-time Logs 1. In the Logging tab, locate the **"Real-time logs"** section 2. Click on **"Edit""** to modify the configuration ### Step 3: Enable Logging 1. Set the **Status** to **"Enabled"** 2. Select the **Log configuration** that was created by the CloudFormation stack 3. Click **"Save changes"** to apply the configuration ## Phase 4: Integration Verification 1. After completing all the steps, the CloudFormation stack should show as **"CREATE\_COMPLETE"** 2. Real-time logs should be **"Enabled"** on your CloudFront distribution 3. Return to **AI Bot Analytics** Page in Writesonic 4. Click on **"Verify Integration"** to confirm that your Cloudfront integration is working properly 5. Once verified, you'll be redirected to your analytics dashboard. The process typically finishes in 1–2 minutes but may take up to 5 minutes. ## Troubleshooting If you encounter any issues during setup: * **Stack Creation Fails**: Check that your AWS account has all required permissions listed in Prerequisites * **CloudFormation Errors**: Verify that all parameters are entered correctly, especially the Writesonic API Key * **Missing Log Configuration**: Ensure the CloudFormation stack shows "CREATE\_COMPLETE" before configuring CloudFront * **CloudFront Not Logging**: Confirm that real-time logs are set to "Enabled" and the correct log configuration is selected * **Missing Data**: Allow 5-10 minutes for data to begin flowing; check that your website is receiving traffic * **API Key Issues**: Verify the Writesonic API Key is copied exactly as provided without extra spaces For assistance, contact **[\[email protected\]](/cdn-cgi/l/email-protection#becdcbceced1cccafec9ccd7cadbcdd1d0d7dd90ddd1d3)** ## Important Notes ### Permissions Ensure that your AWS account has necessary permissions for: * Creating CloudFormation stacks * Modifying CloudFront distributions * Creating IAM roles and policies * Creating S3 buckets and Kinesis streams ### Cost Considerations Be aware of AWS costs associated with: * Kinesis Data Streams (based on shard hours and PUT payload units) * S3 storage for log data * CloudFront real-time logs (per log line) Monitor your AWS billing dashboard to track integration costs. *** [Integrating with Custom Log Drain](/docs/integrating-with-custom-log-drain) [Understanding Your Dashboard](/docs/ai-traffic-analytics-understanding-your-dashboard) # Integrating with Custom Log Drain Source: https://apidocs.writesonic.com/docs/integrating-with-custom-log-drain This guide walks you through the process of implementing AI Bot Analytics using a custom integration. This method allows you to integrate with any platform or custom application by making direct HTTP requests to Writesonic's analytics endpoint. ## Prerequisites * An active Writesonic account * Development access to your website or application * Ability to make HTTP POST requests from your server * Access to request headers and metadata ## Phase 1: Start in Writesonic 1. Head over to the AI Bot Analytics page on Writesonic and choose ‘Custom’ as a provider 2. Click on ‘Continue’ to initialize the integration. 3. Writesonic will generate a unique API key for your website. ## Phase 2: Get Integration Details ### Step 1: Copy the Endpoint URL Copy the following endpoint URL that you'll use for sending analytics data: `https://ingestion.writesonic.com/api/v1/analytics/ingest` ### Step 2: Note the Authentication Headers You'll need to include the following header in all your requests: * **Header Key**: `x-api-key` * **Header Value**: Copy the API key provided by Writesonic (unique to your project) ## Phase 3: Implement the Integration ### Request Format Make a **POST** request to the endpoint URL with the following JSON body fields: | Field | Type | Description | Example | | - | - | - | - | | `ip` | string | The client's IP address | `192.168.1.100` | | `x_real_ip` | string | X-Real-IP header | `203.0.113.1` | | `ua` | string | User-Agent header from the request | `Mozilla/5.0 (compatible; Googlebot/2.1)` | | `country_code` | string | ISO country code | `US` | | `referrer` | string | Referrer header value | `https://chatgpt.com/` | | `url` | string | The requested URL path | `https://writesonic.com/about-us` | | `method` | string | HTTP method used | `POST` | | `x_forwarded_for` | string | X-Forwarded-For header chain | `203.0.113.1, 198.51.100.1` | | `response_status` | string | HTTP response status code | `200` | ### Curl example ```bash bash theme={"system"} curl -X POST 'https://ingestion.writesonic.com/api/v1/analytics/ingest' \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY_HERE" \ -d '[{ "ip": "192.168.1.1", "x_real_ip": "203.0.113.1", "ua": "Mozilla/5.0 (compatible; Googlebot/2.1)", "referrer" : "https://chatgpt.com/", "country_code": "US", "url": "https://writesonic.com/about-us", "method": "GET", "response_status": "200", "x_forwarded_for" : "203.0.113.1,198.51.100.1" }]' ``` ## Phase 4: Testing and Verification ### Test Your Integration 1. Implement the code in your application 2. Make a few test requests to your website 3. Check that the requests are being sent to the Writesonic endpoint 4. Monitor your application logs for any errors ### Verify Installation in Writesonic 1. Go to AI Bot Analytics Page in Writesonic. 2. Click on "Verify Integration" to confirm that your Custom integration is working properly 3. Once verified, you'll be redirected to your analytics dashboard. The process typically finishes in 1–2 minutes but may take up to 5 minutes. ## Best Practices ### Performance Considerations * **Asynchronous Processing**: Send analytics data asynchronously to avoid impacting response times * **Error Handling**: Implement proper error handling to prevent analytics failures from affecting your main application * **Rate Limiting**: Implement client-side rate limiting to avoid overwhelming the endpoint ### Data Quality * **IP Address**: Use the most accurate IP address available (consider proxies and load balancers) * **User Agent**: Always include the complete User-Agent string * **URL Normalization**: Ensure URLs are properly formatted and complete ### Security * **API Key Protection**: Keep your API key secure and never expose it in client-side code * **HTTPS Only**: Always use HTTPS for requests to the Writesonic endpoint * **Data Sanitization**: Sanitize user data before sending to prevent injection attacks ## Troubleshooting ### Common Issues * **401 Unauthorized**: Check that your API key is correct and properly included in headers * **422 Unprocessable Entity**: Verify that your JSON payload matches the required format * **Network Errors**: Ensure your server can make outbound HTTPS requests * **Missing Data**: Check that you're capturing all available request headers and metadata ### Debugging Tips * **Log Requests**: Log the data you're sending for debugging purposes * **Test with curl**: Use curl to test the endpoint manually * **Check Response**: Always check the HTTP response code and body for error details *** [Integrating With Fastly Log Streaming](/docs/integrating-with-fastly-log-streaming) [Integrating with Cloudfront](/docs/integrating-with-cloudfront) # Integrating with Drupal Source: https://apidocs.writesonic.com/docs/integrating-with-drupal This guide walks you through the process of implementing AI Bot Analytics on your Drupal website using the Writesonic AI Analytics module. ## Prerequisites * An Active Writesonic account * Admin access to your Drupal website * Drupal 8.x or higher * Composer CLI to download the module * Drush CLI to install/uninstall the module (Optional) ## Phase 1: Start in Writesonic 1. Head over to the **AI Bot Analytics** page on Writesonic and choose ‘**Drupal**’ as provider. 2. Click ‘**Continue’** to initialize your integration 3. Writesonic will generate a unique API key for your website. Keep this page open as you'll need this API key during the module installation. ## Phase 2: Download the Drupal Module via Composer CLI 1. Open your terminal and navigate to your Drupal project root directory 2. Add this snippet to the root level composer.json, if it does not have already: ```bash bash theme={"system"} "repositories": [ { "type": "composer", "url": "https://packages.drupal.org/8" } ] ``` 3. Run the following composer command: ```bash bash theme={"system"} composer require 'drupal/writesonic_ai_analytics:^1.0' ``` 4. Wait for the composer installation to complete 5. `writesonic_ai_analytics` module files must have been added to `*/modules/contrib` directory. ## Phase 3: Enable the Module 1. Log in to your Drupal admin dashboard 2. Navigate to **Extend** in the admin panel 3. Search for **'Writesonic AI Analytics'** in the dropdown list 4. Check the box next to the module and click **"Install"** Alternatively, you can install it via Drush CLI: ```bash bash theme={"system"} drush en writesonic_ai_analytics ``` ## Phase 4: Configure the Module 1. Navigate to **Configuration** > **System** > **Writesonic AI Analytics Settings** in your Drupal admin panel 2. Copy the API key provided by writesonic and paste it on the configuration page of your Drupal Website. 3. Click **"Save Configuration"** to finalize the setup > Do not disable the Analytics Tracking unless you want to actually pause analytics data collection ## Phase 5: Verify Installation in Writesonic 1. Return to Writesonic AI Bot Analytics page. 2. Click on **"Verify Integration"** to confirm that your Drupal site is properly connected 3. Once verified, you'll be redirected to your analytics dashboard. The process typically finishes in 1–2 minutes but may take up to 5 minutes. ## Troubleshooting If you encounter any issues during setup: * Ensure your API key is entered correctly * Verify that your Drupal site is publicly accessible * Check that the module is downloaded and is present in the `*/modules/contrib` directory. * Make sure that Analytics data collection is not disabled in the **Configuration > System > Writesonic AI Analytics Settings** page For assistance, contact [\[email protected\]](/cdn-cgi/l/email-protection#67141217170815132710150e13021408090e044904080a) ## Managing the integration ### Disabling Analytics Data Collection and Ingestion 1. If you want to disable the analytics data collection, navigate to the **System > Configuration > Writesonic AI Analytics Settings** 2. Disable the Analytics Tracking 3. Click on ‘**Save configuration**’ to save your changes > This will pause the analytics data collection and ingestion from your drupal website to writesonic. ### Deleting/Uninstalling the Module 1. If you want to completely uninstall the module, you can navigate to **Extend** in your Drupal admin panel 2. Select the ‘Uninstall’ tab, and type ‘Writesonic AI Analytics’ in the search filter 3. Click on ‘Uninstall’ and confirm the uninstallation Alternatively, you can also uninstall the module via Drush CLI: ```bash bash theme={"system"} drush pmu writesonic_ai_analytics ``` 4. To completely remove the writesonic\_ai\_analytics module and it’s files from your drupal project, you can run `composer remove writesonic_ai_analytics` *** [Integrating with Vercel Log Drains](/docs/integrating-with-vercel-log-drains) [Integrating With Fastly Log Streaming](/docs/integrating-with-fastly-log-streaming) # Integrating With Fastly Log Streaming Source: https://apidocs.writesonic.com/docs/integrating-with-fastly-log-streaming This guide walks you through the process of implementing AI Bot Analytics on your website using Fastly's realtime log streaming. ## Prerequisites * An active Writesonic account * A Fastly CDN Service configured for your website * Access/permission to edit Logging Endpoints in Fastly ## Phase 1: Start in Writesonic 1. Head over to the **AI Bot Analytics** page on Writesonic and choose ‘Fastly’ as a provider 2. Click on ‘Continue’ to initialize the integration. 3. Writesonic will generate the following information that you'll need during the Fastly configuration: * Log Format * Endpoint URL * Custom Header Value ## Phase 2: Get Your Fastly Service ID 1. Log in to your Fastly dashboard 2. Navigate to your CDN Service for which you want to configure AI Bot Analytics 3. Copy the **Fastly Service ID** from your service dashboard 4. Return to Writesonic and paste the Service ID there and click “Submit”. 5. Click on “Continue” to proceed to the next step. ## Phase 3: Configure Logging in Fastly ### Step 1: Navigate to Logging Configuration 1. In your Fastly CDN Service, navigate to: **"Service Configuration"** > **"Logging"** > **"Create endpoint"** > **"HTTPS" > “Create endpoint”** ### Step 2: Configure the HTTPS Logging Endpoint 1. **Name**: Give a name to your logging endpoint (e.g. Fastly Log Streaming). 2. **Log Format**: Copy the Log Format from Writesonic and paste it in the ‘Log Format’ field in Fastly 3. **URL**: Copy the Endpoint URL from Writesonic and paste it in the **'URL'** field in Fastly ### Step 3: Configure Advanced Options Navigate to **Advanced options** and set the following: 1. **Content Type**: Set to `application/json` 2. **Custom Header Key**: Set to `x-api-key` 3. **Custom Header Value**: Copy the value from Writesonic and paste it there > Rest of the fields in the configuration are optional and can be left as such ### Step 4: Create and Activate 1. Click **'Create'** and wait for the configuration to be applied 2. Once the configuration is ready, click **'Activate'** to finalize the setup ## Phase 4: Verify Installation in Writesonic 1. Wait for 5-10 minutes for Logging Endpoint to activate. 2. Return to AI Bot Analytics Page in Writesonic. 3. Click on **"Verify Integration"** to confirm that your Fastly integration is working properly 4. Once verified, you'll be redirected to your analytics dashboard. The process typically finishes in 1–2 minutes but may take up to 5 minutes. ## Understanding the Integration This integration works by: 1. **Traffic Capture**: Fastly captures all incoming requests to your website 2. **Log Formatting**: The custom log format extracts relevant information about AI crawler requests 3. **Real-time Streaming**: Logs are streamed in real-time to Writesonic's analytics endpoint 4. **AI Detection**: Writesonic processes the logs to identify and analyze AI Bot traffic ## Troubleshooting If you encounter any issues during setup: * **Service ID Issues**: Ensure you've copied the correct Fastly Service ID * **Configuration Problems**: Verify that the log format, endpoint URL, and headers are copied exactly as provided * **Activation Delays**: Allow a few minutes for Fastly configuration changes to propagate * **Missing Data**: Check that your website is receiving traffic and that the logging endpoint is properly configured * **Header Authentication**: Confirm that the `x-api-key` header value matches exactly what Writesonic provided * Make sure to ‘Activate’ the logging configuration after it’s been created/updated. For assistance, contact [\[email protected\]](/cdn-cgi/l/email-protection#16656366667964625661647f62736579787f753875797b) ## Managing the Integration ### Modifying the Configuration To modify your Fastly logging configuration: 1. Navigate back to **Service Configuration > Logging > Edit Configuration** 2. Find your Writesonic endpoint 3. Update the logging configuration and click ‘Update’ 4. Don't forget to **"Activate"** your changes *** [Integrating with Drupal](/docs/integrating-with-drupal) [Integrating with Custom Log Drain](/docs/integrating-with-custom-log-drain) # Integrating with Vercel Log Drains Source: https://apidocs.writesonic.com/docs/integrating-with-vercel-log-drains This doc will guide you how to Integrate the AI Traffic Analytics using Vercel. It uses Vercel's log drain feature and can only be availed by users on Vercel Pro/Enterprise plan ## Prerequisites * An active Writesonic account * Admin access to your Vercel account ## Start in Writesonic ### 1. Head over to the [AI Traffic Analytics page](https://app.writesonic.com/geo/ai-traffic-analytics) on Writesonic and click on *Vercel* Step 1 screenshot ### 2. Enter your url in the input box Step 2 screenshot ### 3. Click on Continue Step 3 screenshot ## [Head over to Project Settings in Vercel](https://vercel.com/) Head over to Project Settings in Vercel ### 4. Click on Log Drains in Project Settings Step 4 screenshot ### 5. Click on Add Log-Drain Step 5 screenshot ### 6. Select "Custom Log Drain Step 6 screenshot ### 7. Click on Continue Step 7 screenshot ### 8. Select Specific Projects Step 8 screenshot ### 9. Select the project for which you want to turn on the AI Analytics Step 9 screenshot ### 10. Select "Static" and "Function" as Sources Step 10 screenshot ### 11. Select Production as environment Step 11 screenshot ## [Writesonic](https://app.writesonic.com/geo/ai-traffic-analytics) ### 12. Copy the Endpoint URL from Writesonic Step 12 screenshot ## [Vercel](https://vercel.com/) ### 13. Paste the copied endpoint url in input box Step 13 screenshot ### 14. Turn on the Custom Headers Step 14 screenshot ## [Writesonic](https://app.writesonic.com/geo/ai-traffic-analytics) ### 15. Copy the Header Key from Writesonic Step 15 screenshot ## [Vercel](https://vercel.com/) ### 16. Paste the copied Header Key in Vercel Step 16 screenshot ## [Writesonic](https://app.writesonic.com/geo/ai-traffic-analytics) ### 17. Copy the Header Value from Writesonic Step 17 screenshot ## [Vercel](https://vercel.com/) ### 18. Paste the copied Header Value in Vercel Step 18 screenshot ### 19. Click on Add Step 19 screenshot ### 20. Copy the Vercel x-vercel-verify header Step 20 screenshot ## [Writesonic](https://app.writesonic.com/geo/ai-traffic-analytics) ### 21. Click on Continue Step 21 screenshot ### 22. Paste the copied Vercel x-vercel-verify header in the input box Step 22 screenshot ### 23. Click on Submit Step 23 screenshot ### 24. After submitting you will get a green tick, indicating the header has been saved Step 24 screenshot ## [Vercel](https://vercel.com/) ### 25. Click on Verify Step 25 screenshot ### 26. Once verified on Vercel, click on Add Log Drain Step 26 screenshot ### 27. Click on Confirm and Add Log Drain Step 27 screenshot ### 28. Click on Done Step 28 screenshot ## [Writesonic](https://app.writesonic.com/geo/ai-traffic-analytics) ### 29. Click on Finish Integration Step 29 screenshot ### 30. Your website will start capturing AI traffic using Vercel Integration Step 30 screenshot *** [Integrating with Wordpress](/docs/integrating-with-wordpress) [Integrating with Drupal](/docs/integrating-with-drupal) # Integrating with Wordpress Source: https://apidocs.writesonic.com/docs/integrating-with-wordpress This guide walks you through the process of implementing AI Traffic Analytics on your Wordpress website. ## Prerequisites * An active Writesonic account * Admin access to your Wordpress website ## Start in Writesonic 1. Head over to the [AI Traffic Analytics page](https://app.writesonic.com/geo/ai-traffic-analytics) on Writesonic 2. Click on **"Wordpress"** 3. Enter your WordPress website domain and click "Continue" 4. Writesonic will generate a unique API key for your website. Keep this page open as you'll need this API key during the plugin installation. ## Install the Wordpress Plugin 1. Download the Writesonic AI Analytics plugin by clicking the "Download" icon next to the zip file 2. Log in to your Wordpress admin dashboard 3. Navigate to Plugins > Add New Plugin > Upload Plugin 4. Choose the downloaded ZIP file (writesonic-analytics.zip) and click "Install Now" 5. After installation completes, click "Activate Plugin" ## Configure the Plugin 1. Once activated, navigate to Settings > “Writesonic AI Analytics” in your WordPress admin menu 2. On the settings page, enter the API Key that was provided in Phase 1 3. Click "Save Settings" to store your configuration ## Verify Installation in Writesonic 1. Return to Writesonic (the page you kept open from Phase 1) 2. Click on "Verify Connection" to confirm that your Wordpress site is properly connected 3. Once verified, you'll be redirected to your analytics dashboard. The process typically finishes in 1–2 minutes but may take up to 5 minutes. ## Troubleshooting If you encounter any issues during setup: * Ensure your API key is entered correctly * Verify that your Wordpress site is publicly accessible * Check that the plugin is activated * If you have cloudflare setup which is routing traffic to your Wordpress, make sure that it is not overwriting the original request headers * For assistance, contact [\[email protected\]](/cdn-cgi/l/email-protection#07747277776875734770756e73627468696e642964686a) For more detailed debugging, please check out the [Troubleshooting and FAQs](https://docs.writesonic.com/docs/ai-traffic-analytics-troubleshooting-and-faqs) page. ## Uninstalling If you need to remove the plugin: 1. Navigate to Plugins in your Wordpress admin 2. Deactivate the Writesonic AI Analytics plugin 3. Click "Delete" to completely remove it Note: Uninstalling the plugin will stop data collection, but your existing analytics data will remain available under the AI Traffic Analytics section *** *** [Integrating With Cloudflare](/docs/integrating-with-cloudflare) [Integrating with Vercel Log Drains](/docs/integrating-with-vercel-log-drains) # Markets: Track multiple Regions and Languages Source: https://apidocs.writesonic.com/docs/markets-track-multiple-regions-and-languages ## Overview **Markets** is a powerful feature within Writesonic’s GEO (Generative Engine Optimization) solution that enables you to track your brand’s AI visibility across multiple geographic regions and languages simultaneously. This highly-requested functionality allows you to monitor how AI platforms discuss your brand across multiple markets within a single project. Each market represents a unique combination of one country and one language, giving you granular control over your global AI presence monitoring. image (176).png *** ## Key Capabilities ### Multi-Market Coverage Track your brand’s visibility across **up to 10 markets** per project, enabling comprehensive global AI monitoring from a single dashboard. ### Country-Language Mapping Each market functions as a **1:1 mapping** between a country and a language. This allows you to: * Track the same country with multiple language variations (e.g., United States - English, United States - Spanish) * Monitor different countries with their respective languages ### Independent Prompt Usage Prompts are counted **independently across markets**. Even when using identical prompts in multiple markets, each market’s usage is calculated separately. *** ## Managing Markets ### Accessing Market Settings Navigate to your project’s configuration page where you’ll find the **Markets dropdown menu**. This centralized location allows you to view all active markets and access management options. ### Current Market Display The interface displays your currently selected market with: * **Country flag** for quick visual identification * **Language specification** in parentheses * **Last updated timestamp** showing when data was last refreshed *** ## Creating a New Market ### Step-by-Step Process 1. **Access Market Management** * Click on the markets dropdown in your project * Select “**Add a market**” or “**Manage markets**” 2. **Configure Market Settings** * **Target Country**: Select your desired country from the dropdown menu * **Language**: Choose the language for AI response analysis in that region * **Homepage URL** (Optional): Add a market-specific URL if you have localized websites 3. **Set Up Prompts** You have two options for configuring prompts: **Option A: Use Existing Prompts** * Select a previously configured market to copy its prompts * Ideal for maintaining consistency across similar markets **Option B: Create New Prompt Set** * Generate fresh prompts specific to this market * Choose the number of prompts (affects quota usage) * Select prompt type: **Branded + Non-branded** or separate configurations 3. **Select Topics** Choose relevant topics for prompt generation such as: * SEO Optimization * Generative Engine Optimization * AI Content Creation * Marketing Workflow Automation * AI Chatbot Solutions *** ## Editing Existing Markets ### Market Configuration Updates Access the edit function through the **pencil icon** in the Manage Markets interface. You can modify: * **Homepage URL**: Update or add market-specific website URLs * **Language settings**: Adjust based on your tracking needs * **Prompt configurations**: Refine your monitoring parameters **Note**: Country and language selections **cannot be changed** after market creation to preserve data integrity and historical tracking consistency. *** ## Usecases * **Global Expansion Tracking** Monitor your brand's AI visibility as you expand into new territories. Analyse markets for regions where you’ve launched products to understand how AI platforms discuss your brand compared to established markets. * **Multilingual Market Analysis** If you operate in multilingual regions like Canada (English/French) or the United States (English/Spanish), create separate markets for each language to understand how different language communities perceive your brand in AI responses. * **Competitive Intelligence Across Regions** Large organizations can monitor how their brand appears alongside competitors in different geographic markets, identifying regions where they have strong AI presence versus areas needing improvement. * **Regional Product Launch Strategy** Before launching products in new markets, understand the existing AI conversation landscape. Use this intelligence to refine messaging and identify potential market-specific concerns or opportunities. * **Content Localization Impact** Measure how well your localized content strategy translates into AI visibility. Compare markets with fully localized content against those using translated materials to justify localization investments. * **Crisis Management Preparation** Monitor brand sentiment across markets to identify potential issues early. Different regions may surface different concerns in AI responses, allowing proactive crisis management. * **Pitch Development** For Digital Agencies, win new business by showing prospects their current AI visibility gaps across different markets during pitches. Use market data to propose targeted optimization strategies. *** ## Coming Soon: Market-Level Filtering ### Enhanced Analytics Across All Pages We’re actively developing **Market filters** that will be integrated across all GEO pages. This upcoming enhancement will enable you to: * **Filter metrics by specific markets** - View performance data for individual markets across all dashboards * **Compare market performance** - Analyze how your brand performs across different regions and languages * **Isolate market-specific insights** - Focus on metrics that matter most for each geographic region * **Streamline reporting** - Generate market-specific reports with filtered data *** ## Frequently Asked Questions ### **Q: What exactly is a “Market” in GEO?** **A:** A Market is a specific combination of one country and one language that you want to monitor for AI visibility. For example, “United States - English” is one market, while “United States - Spanish” would be a separate market. ### **Q: Can I track the same country with multiple languages?** **A:** Yes! You can create multiple markets for the same country with different languages. This is particularly useful for multilingual regions or targeting diverse demographic groups. ### **Q: How are prompts counted across multiple markets?** **A:** Prompts are counted **independently** for each market. If you use 30 prompts in Market A and the same 30 prompts in Market B, it counts as 60 prompts total against your quota. ### **Q: Why can’t I change the country or language after creating a market?** **A:** This restriction preserves **data integrity** and ensures historical tracking remains consistent. To track a different country-language combination, create a new market. ### **Q: What’s the difference between “Branded” and “Non-branded” prompts?** **A:** **Branded prompts** include your company/product name to track direct mentions, while **Non-branded prompts** monitor broader topic discussions where your brand might be relevant but not explicitly mentioned in the query. ### **Q: Can I delete a market and create a new one?** **A:** Yes, you can remove existing markets through the trash icon in the management interface and create new ones. ### **Q: Can I transfer prompts between markets?** **A:** Yes, when creating a new market, you can choose to copy prompts from any existing market, making it easy to maintain consistency across similar regions. ### **Q: How do I optimize my market selection with limited quota?** **A:** Focus on your **primary business regions** first, then expand based on growth priorities. Consider combining similar markets or using fewer prompts per market to maximize coverage within your quota limits. *** ## Need Additional Support? For more detailed guidance or technical assistance with Markets configuration, please contact our support team or refer to the complete GEO documentation in your account dashboard. *** [Portfolio](/docs/portfolio) [Tags](/docs/tags) # Missing Prompts Source: https://apidocs.writesonic.com/docs/missing-prompts What it is: A dashboard in GEO (Generative Engine Optimization) that shows queries where . These are your missed AI visibility opportunities. *** ## Objective & Benefits * **Spot gaps fast:** See exactly which prompts you’re absent from. * **Prioritize content:** Turn each missed prompt into a content/task brief. * **Track progress:** Watch the count trend down as you fix gaps. *** ## When to Use It Use this page when you want to: * Audit where AI assistants (ChatGPT, Perplexity, Google AI Overviews, etc.) skip your brand. * Plan new content or updates to win those mentions.. *** ## Page Anatomy ### 1. Header Metrics & Controls * **Answers so far:** Total AI answers analyzed where your brand was missing. * **Last updated:** Timestamp of the latest data refresh. * **Date picker:** Choose the time range you’re reviewing. * **Comparison (Changes):** Compare current data to a previous period (e.g., last 7 days) to see deltas. ### 2. Trend Chart A line chart that visualizes the count of missing-prompt answers over time (daily). A downward trend = you’re improving. ### 3. Filters * **Platform:** Limit to one AI platform or view all. * **Topic:** Narrow to a content cluster/theme. * **Prompt search/sort:** Find or sort specific questions. ### 4. Table of Missing Prompts Each row lists a prompt where your brand wasn’t mentioned: * **Platform** – Where the answer came from (ChatGPT, Perplexity, etc.). * **Topic** – The thematic bucket for the prompt. * **Prompt** – The exact user query. * **Brand Mentions** – Always 0 here (that’s why it’s in this list). > *Optional:* Clicking a row (if enabled) opens the answer details to see which competitors were cited and why. *** ## Step-by-Step Workflow 1. **Pick your scope:** Set date range, choose a platform/topic if needed. 2. **Scan the chart:** Note spikes or drops in missing prompts. 3. **Review the table:** Identify high-value prompts (high intent, high volume, strategic keywords). 4. **Create/optimize content:** Use Writesonic’s tools to draft or improve articles targeting those prompts. 5. **Re-check later:** Return to see if the prompt drops off the list (i.e., you got mentioned). *** ## Best Practices * Group similar prompts and address them with one comprehensive resource. * Mirror the language of the prompt in your content (titles, headings, FAQs). * Add citations, stats, and structured data to increase your chance of being referenced by AI. * Track weekly to keep momentum and prove ROI. *** ## FAQs **Does this include prompts where no brands are mentioned?** No. This view focuses on prompts where others are mentioned and you’re not. **Why is “Brand Mentions” always zero here?** Because this page only shows missing prompts—by definition, you’re absent. **Can I see the actual AI answer?** If available, click the prompt row to view the answer and cited sources. **How quickly will changes show up?** After you publish/optimize content, allow some time for AI systems to re-crawl. Check back in a few days or weeks, depending on the platform’s refresh cadence. *** ## Summary Use **Prompts: Missing Prompts** as your to-do list for AI visibility. Filter, find the gaps, fix them with targeted content, and monitor the trend downwards. *** [All Prompts and Answers](/docs/all-prompts) [Citations](/docs/citations) # Overview Source: https://apidocs.writesonic.com/docs/overview-page # Overview The **Overview** page is your central dashboard for understanding how your brand performs across AI-generated search results. It consolidates visibility, citations, competitor benchmarks, sentiment, and prompt-level data into one unified view — so you can quickly assess your brand's AI presence and identify where to take action. This is the first page you see when you open your GEO project. It's designed for daily check-ins as well as strategic reporting — whether you're a marketer tracking weekly progress, an SEO manager benchmarking against competitors, or a leadership stakeholder reviewing high-level AI search performance. The Overview page has four tabs: **General**, **Platforms**, **Competitors**, and **General (Old)**. This document covers the **General** tab — the default and most comprehensive view. *** ## Global Filters The **global filters bar** sits at the top of the Overview page and controls the scope of data displayed across every section below. Adjusting any filter instantly updates all charts, tables, and metrics on the page. * **Date Range** — Select a start and end date (e.g., *12 Jan 2025 – 12 Jan 2025*) or use quick presets to define the reporting window. You can also enable a **comparison period** (vs.) to benchmark current performance against a previous time range. * **Markets** — Filter by a specific market (country + language combination). Defaults to *All markets*. Useful if you track multiple regions within a single project. * **Topics** — Narrow the dashboard to one or more specific topics you've configured. Helps you evaluate AI visibility per product line, category, or business unit. * **Platform** — Isolate data for a single AI platform (e.g., ChatGPT, Perplexity, Gemini, Claude, Copilot). Defaults to all platforms combined. * **Prompt Type** — Toggle between **Branded prompts** and **Non-branded prompts** to understand how your brand performs in generic industry queries versus queries that mention your brand directly. * **Save & Presets** — Save any filter combination as a reusable preset for quick access during future sessions. *** ## Your Brand's Performance Across Key Metrics This section sits at the top of the General tab and provides a quick health check of your brand's AI presence. Each metric includes a **trend indicator** (↑ or ↓ with percentage) comparing the selected period against the prior period. ### AI Visibility The percentage of tracked AI-generated answers where your brand is **mentioned** — either by name or through a direct reference. * This is your **primary GEO metric**. A rising visibility score means AI platforms are recognizing and surfacing your brand more frequently. * The count below (e.g., *"234 of 12,342 answers"*) shows raw mentions out of total tracked answers. ### Share of Voice Your brand's share of **total mentions** across all AI answers, relative to all tracked competitors. * Think of this as your AI market share. It tells you how much of the generative search conversation belongs to your brand versus others in your space. ### Citation Share The percentage of all AI citations (source links in AI answers) that point to **your website**, versus competitor websites. * Citations indicate **trust and authority** — when AI platforms link to your content as a source, it signals that your pages are considered reliable and reference-worthy. * The count below (e.g., *"Cited in 234 of 1,242 answers"*) provides the raw volume. ### Pages Mentioning You The number of **third-party pages** cited in AI answers that also mention your brand within their content. * This reflects your **off-site digital footprint** — how often external sources talk about your brand in contexts that AI engines pull from. * A higher count here means other authoritative sites are referencing you, which strengthens your chances of being surfaced in AI responses. ### Sentiment The overall tone — **Positive**, **Neutral**, or **Negative** — with which AI platforms describe your brand in their answers. * Displayed as a percentage split (e.g., *67% Positive, 33% Negative*) so you can track shifts in brand perception over time. * Useful for catching reputation risks early and measuring the impact of PR or messaging changes. *** ## Action Centre Directly below the key metrics, the **Action Centre** banner shows the total number of available **optimization opportunities** to boost your brand's AI visibility. * Click **Act now** to navigate to the full Action Centre, where recommendations are prioritized by **impact level** and **effort required**. * Opportunities include actions like getting mentioned on high-authority third-party sites, optimizing existing content for AI readability, and closing citation gaps where competitors appear but your brand doesn't. This is your fastest path from dashboard insight to concrete next steps. *** ## Visibility Trend The **Visibility Trend** chart tracks your brand's AI visibility score over time as a line graph, with the **previous period** overlaid for comparison. * **Metric Toggle** — Switch between **Visibility** and **Citation** views using the dropdown above the chart. * **Granularity Toggle** — Switch between **Daily** and **Weekly** views. * Hover over any data point to see the exact percentage and date. * The **Previous Period line** (muted color) lets you visually assess whether your visibility is trending upward, holding steady, or declining. **How to use it:** This is where you measure the real-world impact of your GEO efforts. After publishing new content, running outreach, or optimizing pages, check the trend line over the following days and weeks to see if those actions moved the needle. *** ## Leaderboard The **Leaderboard** table ranks your brand alongside all tracked competitors on two core metrics: * **AI Visibility (%)** — The percentage of AI answers mentioning each brand, with a trend indicator showing the period-over-period change. * **Citation Share (%)** — The percentage of AI source citations each brand receives, with a trend indicator. Your brand is highlighted (tagged as **You**) for easy identification. The table is sorted by AI visibility by default. **How to use it:** The Leaderboard gives you instant competitive context. Identify who's ahead, who's gaining momentum, and where you need to close the gap. If a competitor's visibility is spiking, investigate their content or citation strategy to understand what's driving the change. *** ## Platform-Wise Performance This table breaks down your brand's AI Visibility and Citation Share **by individual AI platform** — including ChatGPT, Perplexity, Gemini, Copilot, LlamaAI, Claude, and others. For each platform, you'll see: * **AI Visibility (%)** — How frequently your brand appears in that platform's answers, plus the trend change. * **Citation Share (%)** — How often that platform cites your content as a source, plus the trend change. **How to use it:** Not all AI platforms behave the same way. You might have strong visibility on ChatGPT but be underperforming on Perplexity or Claude. This breakdown helps you pinpoint platform-specific weaknesses and prioritize optimization where it matters most. > Click **View full report →** to open the detailed **Platforms** tab for deeper platform-level analysis. *** ## How AI Talks About Your Brand This section displays a **word cloud** of the key positive and negative themes AI platforms associate with your brand across their responses. * **Larger, bolder words** represent themes that appear more frequently. * A **mention count** is shown (e.g., *"Mentioned 123 times"*) so you can quantify the volume behind each theme. * Themes can include product attributes (e.g., *"User-Friendly Interface"*, *"Robust Document Summarizer"*), use cases (e.g., *"Helpful for Academic Research"*), or general perceptions (e.g., *"Practical Tool"*, *"Automatic Summarization"*). **How to use it:** This gives you a qualitative lens on your AI brand perception. Beyond knowing *if* you're mentioned, this tells you *how* you're being described — which is critical for aligning your messaging, identifying unexpected brand associations, and spotting areas where perception doesn't match your positioning. *** ## Share of Voice The **Share of Voice** section visualizes your brand's percentage of total mentions in AI answers relative to competitors, displayed as a **donut chart**. * Your brand and the top competitors are each shown with their respective share percentages. * Your brand is labeled as **You** for quick identification. **How to use it:** Share of voice is a leading indicator of brand dominance in AI search. A shrinking slice signals that competitors are gaining ground and you need to accelerate content and citation efforts. A growing slice validates that your GEO strategy is working. *** ## Brand Rank Distribution The **"Which rank is your brand mentioned in answers"** table shows the **position** at which your brand appears within AI-generated responses. | Column | Description | | - | - | | **Rank** | The position at which your brand is mentioned (1st rank, 2nd rank, 3rd rank, 4th rank, 5th rank and more) | | **Percentage** | The proportion of your total mentions that occur at each rank position | | **Answers** | The absolute number of AI answers where your brand appeared at that rank | **How to use it:** Being mentioned is valuable — being mentioned **first** is significantly more impactful. AI answers are consumed top-down, and the first brand referenced typically receives the most attention and trust. Track whether your 1st-rank percentage is growing over time; it's a strong signal of improving brand authority in AI responses. *** ## Your Top Cited Content This table lists the **specific pages from your website** that are most frequently cited as sources in AI-generated answers. For each page, you'll see: * **Cited Page** — The URL and page title being referenced by AI platforms. * **Citation Share (%)** — The percentage of total citations this page accounts for, with a trend indicator. * **Citing Answers** — The number of AI answers that cite this specific page, with period-over-period change. **How to use it:** Your top cited pages are your **highest-performing AI assets**. These are the pages that AI engines trust enough to link back to as sources. Keep them updated, comprehensive, and authoritative — they're directly fueling your brand's citation share and overall AI visibility. > Click **Show all webpages →** to view the full list of cited content. *** ## Most-Searched Prompts by Users This section surfaces the **most popular prompts** (user queries) relevant to your brand and industry, ranked by search volume. For each prompt, you'll see: * **Prompt** — The actual question or query users are asking AI platforms. * **Search Volume** — An estimate of how frequently this prompt is searched. * **AI Visibility (%)** — The percentage of AI answers for this prompt that mention your brand, with trend direction. * **Answers** — The total number of AI-generated answers tracked for this prompt, with the change from the prior period. **How to use it:** High search volume + low AI visibility = your biggest growth opportunity. These are the conversations your audience is having with AI engines where your brand isn't showing up yet. Prioritize creating or optimizing content that directly addresses these prompts. > Click **Show all popular prompts →** to explore the full prompt list. *** ## Your Brand Visibility Across Prompts This table provides a **prompt-level breakdown** of your brand's visibility, with two tabs: * **Mentions you** — Prompts where your brand **is mentioned** in AI answers. * **Does not mention you** — Prompts where your brand **is absent** from AI answers. For each prompt, you'll see: * **Prompt** — The tracked query. * **Search Volume** — How often it's searched. * **AI Visibility (%)** — Your visibility for that specific prompt, with trend direction. * **Answers** — The number of AI answers tracked, with period-over-period change. **How to use it:** The **"Does not mention you"** tab is especially powerful — it reveals the exact conversations happening in AI search where your brand is currently invisible. These are your highest-priority targets for content creation, optimization, and outreach. Cross-reference these with the Action Centre recommendations for a clear execution path. > Click **Show all prompts driving visibility →** to access the complete prompt-level breakdown. *** [Select competitors](/docs/select-competitors) [Overview: Competitors](/docs/overview-page-competitors-tab-copy) # Overview: Competitors Source: https://apidocs.writesonic.com/docs/overview-page-competitors-tab-copy The on the Overview page gives you a clear picture of how your brand stacks up against the competition in AI-generated responses. It surfaces the key players in your space, tracks their performance over time, and helps you identify exactly where you're winning — and where you're falling behind. This tab is designed to turn competitive intelligence into action. Whether you're benchmarking against direct rivals or discovering new competitors you hadn't considered, every section here is built to inform your next move. *** ## AI Visibility Leaders & Citation Share Leaders This section gives you an instant snapshot of the competitive extremes — who's leading and who's trailing — across two critical dimensions: **AI visibility** and **citation share**. ### AI Visibility Leaders * **Strongest Competitor:** The brand with the **highest AI visibility** among all your tracked competitors. This is the competitor appearing most frequently in AI-generated answers for your monitored topics and prompts. * **Weakest Competitor:** The brand with the **lowest AI visibility** in your competitive set. Their low presence indicates limited traction with generative engines, often due to content gaps or lack of optimization. ### Citation Share Leaders * **Strongest Competitor:** The brand whose content is **most frequently cited as a source** by AI platforms. High citation share signals strong content authority — AI engines trust and reference their pages more than others. * **Weakest Competitor:** The brand with the **lowest citation share**, meaning AI platforms rarely pull from their content as a reference source. **Why it matters:** These four data points establish the boundaries of your competitive landscape. The strongest competitors set the benchmark for what's achievable in your space, while the weakest reveal the floor. Use this to calibrate your own goals — if the top competitor holds high visibility, that's your target. If the weakest competitor's citation share is low, make sure you're not trending in the same direction. *** ## Competitor Analysis This is the core performance table of the Competitors tab. It provides a **multi-dimensional, side-by-side comparison** of every tracked competitor across the metrics that matter most. ### What's Tracked For each competitor (including your own brand), the table displays: * **AI Visibility (%):** The percentage of AI-generated responses where this brand is mentioned. Trend arrows (↑ or ↓) show whether visibility is increasing or decreasing compared to the previous period. * **Citation Share (%):** The percentage of citations attributed to this brand's content across all monitored AI responses. This reflects how often AI engines trust and source content from this brand. * **Share of Voice (%):** A combined measure of the brand's overall presence in AI conversations relative to all tracked competitors. This accounts for both mentions and citations to give a holistic view of competitive standing. Each metric includes a **trend indicator** showing the direction and magnitude of change, making it easy to spot which competitors are gaining or losing ground. ### How to Use This * **Compare your brand against the field.** Your brand is labeled "You" in the table for easy identification. See how your metrics line up against each competitor. * **Spot momentum shifts.** A competitor with rapidly rising AI visibility may be executing a new content strategy worth investigating. * **Identify vulnerabilities.** A competitor with high visibility but low citation share may be mentioned often but not trusted as a source — a gap you can exploit with authoritative content. * **Export the data.** Click the **download icon** to export the table for reporting, presentations, or deeper analysis. The table supports **pagination** and lets you control the number of results displayed per page, making it easy to navigate large competitor sets. *** ## Competitor Visibility Across Topics This section breaks down competitive performance at the **topic level**, revealing exactly where each brand dominates or falls short. ### What It Shows A matrix-style table where: * **Rows** represent each tracked competitor (including your brand) * **Columns** represent the topics you've configured for your GEO project Each cell displays the competitor's **visibility percentage** or **citation share** for that specific topic. You can toggle between analyzing by **Topic** or **Prompt** and switch the metric between **AI Visibility**, **Citation Share**, or **Share of Voice** using the dropdown filters above the table. Cells are **color-coded** to highlight performance: * **Green** indicates strong performance or areas where you lead * **Red or blank cells** signal weak presence or complete absence from AI responses for that topic ### Why It Matters This is where you move from high-level benchmarks to **precision targeting**. Instead of competing everywhere at once, topic-level visibility helps you make strategic decisions: * **Identify quick wins:** Topics where competition is low and moderate content effort could establish your dominance. * **Defend your strengths:** Topics where you currently lead but competitors are closing in. * **Attack strategically:** High-value topics where a competitor leads but their position isn't insurmountable. * **Discover gaps:** Topics where no competitor has strong visibility — these represent untapped opportunities. You can also **spot competitor content strategies** from this view. A competitor dominating technical topics but absent from use-case or comparison topics reveals their focus areas — and the audience segments they're leaving underserved. Click **View more** to expand the full topic matrix if your project tracks more topics than the default view displays. *** [Overview Page](/docs/overview-page) [Overview: Platforms](/docs/overview-platforms) # Overview: Platforms Source: https://apidocs.writesonic.com/docs/overview-platforms The tab within the Overview page gives you a detailed breakdown of how your brand performs across individual AI search platforms. While the General tab shows your overall AI visibility, the Platforms view lets you compare performance across engines like , and others — so you can see exactly where you're strong, where you're falling behind, and where the biggest opportunities lie. This is especially useful when you want to understand *why* your overall visibility is what it is. Different AI platforms may treat your brand very differently — and this tab makes those differences visible. > **How to access:** Navigate to **Overview** from the left sidebar, then click the **Platforms** tab at the top of the page. *** ## AI Visibility Performance This section gives you an **instant snapshot** of your best and worst-performing AI platforms based on visibility. * **Strongest Platform:** The AI engine where your brand achieves the **highest AI visibility percentage**. This is where your content is most frequently referenced in AI-generated answers. * **Weakest Platform:** The AI engine where your brand has the **lowest AI visibility percentage**. This represents your biggest untapped opportunity. **Why it matters:** Your strongest platform tells you where your content strategy is already working — study what's succeeding there and replicate it elsewhere. Your weakest platform highlights where competitors may be dominating and where focused optimization could yield the fastest gains. Often, improving visibility on an underperforming platform delivers a higher ROI than trying to squeeze more out of a platform where you're already strong. *** ## Citation Share Performance Sitting alongside AI visibility, this section focuses specifically on **citation share** — how often AI platforms cite your website as a source in their responses. * **Strongest Platform (Citation Share):** The AI engine that cites your content **most frequently** as a source. * **Weakest Platform (Citation Share):** The AI engine that cites your content **least frequently**. **Why it matters:** Visibility and citation share are related but distinct. You might be *mentioned* by an AI engine without being *cited* as a source — and citations carry more weight because they drive direct traffic back to your site. Comparing citation share across platforms helps you identify where your content is seen as authoritative enough to be linked, and where you need to strengthen trust signals. *** ## AI Visibility by Platform (Trend Chart) This chart tracks your brand's **AI visibility percentage across each platform over time**. Each AI platform is represented by a distinct colored line, giving you a multi-dimensional view of your performance trajectory. **What you can do with this chart:** * **Spot platform-specific trends:** See if your visibility is rising on one platform while declining on another. * **Correlate changes with actions:** Did a content update or optimization effort coincide with a visibility spike on a specific platform? * **Identify algorithm or behavior shifts:** A sudden drop on a single platform may signal a platform-level change rather than a content issue. * **Toggle platforms on/off** to focus on specific comparisons. * **Switch between Weekly views** and adjust date ranges as needed. * **Enable "Previous Period"** comparison to see how current performance stacks up against the prior period. **Why it matters:** Trend data transforms static numbers into **actionable intelligence**. A gradual decline that might go unnoticed in a single snapshot becomes immediately visible in trend analysis. You can also use this to validate whether your optimization strategies are producing measurable results on specific platforms over time. *** ## Platforms Table (AI Visibility) Next to the trend chart, the **Platforms table** provides a detailed, sortable breakdown of each AI platform's performance metrics. **Columns include:** * **Platform name and icon** for quick identification. * **AI Visibility (%):** The percentage of tracked prompts where your brand appears in that platform's AI-generated responses. * **Change indicator:** Shows whether visibility has **increased (↑)** or **decreased (↓)** compared to the previous period, along with the percentage change. * **Brand Mentions:** The total number of times your brand was mentioned across all tracked prompts on that platform. * **Mentions change indicator:** Shows the increase or decrease in brand mentions compared to the prior period. **Why it matters:** This table lets you quickly scan and compare all platforms side by side. You can identify which platforms are trending upward, which are losing ground, and where the absolute volume of brand mentions is highest. A platform with moderate visibility but high mention volume may still be a high-value channel worth prioritizing. *** ## Citation Share by Platform (Trend Chart) Similar to the AI visibility trend chart, this visualization tracks **citation share** — the percentage of AI responses that cite your website as a source — broken down by platform over time. **What you can do with this chart:** * **Compare citation trends** across platforms to see where your content is gaining or losing trust. * **Identify citation-visibility gaps:** A platform where you have high visibility but low citation share may be mentioning your brand without linking to your content — a signal to optimize for citations specifically. * **Toggle platforms** and adjust date ranges for focused analysis. **Why it matters:** Citations are a stronger signal of authority than mentions alone. Tracking citation share trends helps you understand which platforms are increasingly treating your content as a credible, linkable source — and which ones aren't. This directly impacts referral traffic from AI platforms. *** ## Platforms Table (Citation Share) Alongside the citation trend chart, this table mirrors the AI visibility table but focuses on **citation-specific metrics**. **Columns include:** * **Platform name and icon.** * **Citation Share (%):** The percentage of AI responses on that platform that cite your website. * **Change indicator:** Increase or decrease vs. the previous period. * **Citing Answers:** The total number of AI-generated answers that include a citation to your content on that platform. * **Citing answers change indicator:** Shows the trend in citing answers. **Why it matters:** Use this table to pinpoint which platforms are most actively citing your content and where citation share is slipping. If citing answers are increasing but citation share is flat, it may mean the overall volume of AI responses is growing — so you need to maintain or accelerate your optimization to keep pace. *** ## Topic-Wise Visibility by Platform This section provides a **cross-platform, topic-level heatmap** of your brand's AI visibility. It maps each of your tracked topics against each AI platform, showing the visibility percentage in a color-coded grid. * **Green cells** indicate strong visibility for that topic on that platform. * **Red cells** indicate low visibility — areas that need attention. **You can customize this view using the filters at the top:** * **Analyze by:** Switch between **Topic** and **Prompt** level views for granularity. * **Metric:** Toggle between **AI Visibility** and **Citation Share** to see both dimensions. **Why it matters:** This is one of the most strategic views in the Platforms tab. It helps you answer questions like: * *"Which topics am I strong on across all platforms, and which are platform-specific gaps?"* * *"Is there a topic where I have zero visibility on every platform — signaling a major content gap?"* * *"Which platform-topic combinations should I prioritize for optimization?"* By identifying specific platform-topic weaknesses, you can create **targeted content strategies** rather than taking a one-size-fits-all approach to GEO. *** ## Best Practices for Using Platform Insights * **Compare visibility and citation share together.** A platform where you're mentioned often but rarely cited may need content improvements that make you more "citable" — structured data, authoritative sources, clear formatting. * **Use trend charts to validate your efforts.** After publishing optimized content or running an outreach campaign, check the trend charts to see if specific platforms responded. * **Prioritize platforms your audience uses.** Not all AI platforms carry equal weight for your business. Focus optimization efforts on the platforms your target customers are most likely to use. * **Investigate sudden changes.** A sharp drop or spike on a single platform usually points to a platform-specific cause — algorithm update, competitor activity, or content indexing changes. Use the date range filters to narrow down when it happened. * **Leverage the topic-platform heatmap for content planning.** Red cells in the heatmap are your roadmap. Build or optimize content specifically for those topic-platform gaps. *** [Overview: Competitors](/docs/overview-page-competitors-tab-copy) [Sentiment](/docs/sentiment) # Platform Behavior & Volatility Source: https://apidocs.writesonic.com/docs/platform-behavior-tracking Ever wonder why ChatGPT recommends your brand while Claude doesn't? Or why your visibility is 60% on Perplexity but only 40% on Google AI? There's a method to this madness. ### Each AI Has Its Own Personality Just like people have preferences, each AI platform has distinct behaviors: **ChatGPT - The Professor** * Loves Wikipedia and academic sources * Prefers comprehensive, well-structured content * Often cites established brands and authorities * Updates knowledge periodically, not real-time **Perplexity - The Researcher** * Adores Reddit discussions and forums * Seeks recent, trending information * Values user-generated content * Provides more citations than others **Claude - The Engineer** * Trusts technical documentation * Prefers detailed, accurate information * Conservative with citations * Values depth over breadth **Google AI (Gemini/AI Overviews) - The Insider** * Favors Google-owned properties (YouTube, etc.) * Leverages Google's massive index * Real-time information access * Integrates with search results ### Why Results Vary So Much The same prompt "best design tools for beginners" can yield completely different answers. Here's why: **1. Different Data Sources** | Platform | Primary Index | | - | - | | ChatGPT | Bing + proprietary data | | Perplexity | Google's index | | Claude | Own crawled data | | Google AI | Google's index | **2. Ranking Algorithms** Each platform weighs factors differently: * Authority vs. recency * Popular sources vs. niche expertise * User engagement signals * Content depth vs. accessibility **3. Built-in Randomness** AI platforms have a `temperature` setting and intentionally vary responses to: * Avoid repetitive answers * Test different approaches * Provide diverse perspectives **4. Temporal Factors** * Recent events influence context * Model updates change behaviors **Now that you understand platform behaviors**, let's dive into your dashboard and learn how to extract actionable insights from all this data. *** [Prompts vs Keywords \[Very Important\]](/docs/prompts-vs-keywords-very-important) [Why We Monitor Real AI Platforms, Not Just APIs](/docs/why-we-monitor-real-ai-platforms-not-just-apis) # Portfolio Source: https://apidocs.writesonic.com/docs/portfolio The feature in Page Tracker allows you to group and monitor multiple pages as a single unit. Instead of tracking pages individually, you can organize them into meaningful collections—such as blog posts, product pages, or competitor content—and measure their collective impact on your AI visibility. *** ## What is a Portfolio? A **Portfolio** is a user-defined group of pages you want to track together. By bundling related pages, you gain a consolidated view of how that content category performs across AI-generated answers. This is particularly useful for understanding the citation performance of specific content types, campaigns, or strategic page groupings. *** ## Accessing Portfolios Navigate to **Research → Page Tracker → Portfolios** in the left sidebar. From this view, you can: * View all existing portfolios and their performance metrics * Create new portfolios using the **"+ Add portfolio"** button * Search for specific portfolios by name, URL, or title * Filter by date range to analyze performance over time *** ## Portfolio Metrics Each portfolio displays three key metrics that help you understand how your grouped pages are performing in AI search results. ### Average Citation Share **What this shows:** The percentage of AI-generated answers that cited pages from this portfolio as a source. **Why it matters:** Citation share indicates how frequently AI engines reference your content when responding to relevant queries. A higher citation share means your portfolio pages are being recognized as authoritative sources, driving organic visibility in AI-generated answers. *** ### Visibility Contribution **What this shows:** The percentage of your total brand visibility (answers mentioning your brand) that comes from pages in this portfolio being cited. **Calculation:** (Answers citing this portfolio that mention your brand ÷ Total answers mentioning your brand) × 100 **Why it matters:** This metric reveals which content is driving your brand presence in AI responses. Understanding visibility contribution helps you identify high-performing portfolios and prioritize content optimization efforts where they'll have the greatest impact. *** ### Pages Mentioning Me **What this shows:** The number of pages within this portfolio that mention your brand. **Why it matters:** This count helps you assess brand presence within a portfolio. If you're tracking competitor pages or third-party content, this metric shows how often your brand appears—useful for monitoring earned media, reviews, or industry coverage. *** ## Common Use Cases * **Content categorization:** Group your blog posts, landing pages, and documentation separately to compare performance across content types. * **Campaign tracking:** Create portfolios for specific marketing campaigns to measure their AI visibility impact. * **Competitor monitoring:** Track groups of competitor pages to benchmark your citation performance against theirs. * **Regional analysis:** Organize pages by target market or language to understand geographic performance differences. *** [Prompt Explorer](/docs/prompt-explorer) [Markets: Track multiple Regions and Languages](/docs/markets-track-multiple-regions-and-languages) # Prompt Explorer Source: https://apidocs.writesonic.com/docs/prompt-explorer # Use Prompt Explorer to Understand What People Are Really Asking AI As more users turn to AI platforms like ChatGPT, Claude, and Perplexity to get answers, traditional keyword research no longer tells the full story. The way people ask questions is changing, and with it, the way visibility is earned. **Prompt Explorer** is designed to help you track this shift. It shows you the real prompts users are entering across AI platforms and reveals which questions are gaining traction in your space. You’ll also see how often those prompts are being asked, what brands are being cited in the responses, and how interest varies by location and over time. This guide will help you make sense of the data in Prompt Explorer so you can understand what real users are asking, where the demand is coming from, and how to use those insights to grow your visibility in AI-generated answers. ## Explore AI Search Volume in Prompt Explorer Prompt Explorer gives you access to a metric you won’t find anywhere else: **AI Search Volume.** Start by opening the **Prompt Explorer** tool and typing in the prompt you want to search. Say *"best AI writing tools*. Click on **Research**, and the tool starts researching the prompt usage and displays the below metrics. You’ll see the AI search volume right at the top of the dashboard with the name **Average Search Volume.** This number shows the estimated number of times people ask a specific prompt across major generative AI platforms like ChatGPT, Claude, Perplexity, and others each month. You can treat this metric much like you would traditional keyword volume. It represents total prompt demand, giving you a data-backed way to prioritize which AI queries deserve your attention. Whether you’re building a generative search strategy, writing content, or optimizing your brand for AI visibility, AI Search Volume helps you focus on what people are actually asking, not just what you think they’re asking. However, calculation-wise, it doesn’t work the same as keyword volume. There’s one important caveat: Google keyword usage doesn’t translate directly to AI prompt usage. ## Why Keyword Volume Doesn’t Work for AI Search Most tools assume that if a keyword has high search volume in Google, it must also be popular in AI. That assumption can be misleading. People interact with AI very differently than they do with search engines. Instead of typing short terms like “best marketing software” or “graphic design tools,” they phrase full, detailed prompts like: * “What’s a good marketing tool for launching an email campaign on a tight budget?” * “Suggest an easy design platform for creating event posters and social media content.” * “Can you recommend a simple CRM for handling client leads in a real estate business?” These prompts are conversational, specific, and vary widely in wording, even when the intent is the same. As a result, traditional keyword tools can’t surface them: * They miss high-intent queries that people ask AI every day. * They split demand across dozens of variations, making each one look insignificant. * They mislead your content strategy by showing you what people type into browsers — not what they say to chatbots. To optimize for generative search, you need to measure demand based on how users actually communicate with AI. That’s exactly what **AI Search Volume** is designed to solve. ## How We Calculate AI Search Volume Accurately Unlike keyword tools that rely on browser-based data, Prompt Explorer estimates AI Search Volume using a multi-source ensemble system built specifically for generative search. Here’s how it works behind the scenes: ### 1. We source real signals from across the web Our model draws from multiple independent inputs, including: * 120M+ AI conversations from users across platforms * Public forums like Reddit, Quora, and Stack Overflow * Enterprise partner data and industry-specific usage trends Each of these sources reflects how people actually phrase and submit prompts — not just how they search. ### 2. We identify prompt intent across variations People rarely ask the same prompt the same way. That’s why we group and normalize prompts based on semantic intent, not just exact keywords. For example, if someone searches: * “Which tool is best for managing remote teams?” * “Need a project management platform for a distributed agency” * “Suggestions for software to coordinate tasks in a remote company” All of these fall under the same intent. Prompt Explorer recognizes this and aggregates them into one unified demand signal. ### 3. We adjust for bias and platform noise Not all trends are real trends. Sometimes a prompt spikes due to news, social virality, or platform-specific quirks. Our model applies correction factors to adjust for: * Sudden one-time surges * Overrepresentation from niche forums * Underreporting due to new prompt formats This ensures that the final volume you see reflects genuine, repeatable demand, not anomalies. ## What Else Does Prompt Explorer Tell You Beyond average monthly search volume, Prompt Explorer includes additional insights that help you understand how interest in a prompt is trending — and where demand is coming from. Here’s how to read the rest of the report: ### Usage Frequency Right next to Average Search Volume, you’ll see the **Usage Frequency.** This gives you a quick signal of how frequently people ask a specific prompt across AI platforms based on 12 months of known data. It’s grouped into three tiers: * High: Very popular. These prompts are widely used and great candidates to target for maximum visibility. * Medium: Moderately popular. These still offer solid traffic opportunities and may be less competitive than high-frequency prompts. * Low: Niche or emerging. These prompts may have limited reach, but can work well if you're targeting a specific audience or filling gaps. *Use this indicator to help prioritize which prompts are worth exploring now — and which might need more context or strategy to justify targeting.* ### Search Volume Over Time Below the average search volume, you’ll find a chart that shows how demand for the prompt has changed over the last 12 months. This trendline helps you quickly understand if the prompt is: * Gaining popularity month-over-month * Seasonally spiking (like in December and January here) * Losing traction or plateauing *Use this graph to decide whether a prompt is worth targeting now or if it needs to be monitored for future growth. You can also compare spikes to recent product launches, marketing campaigns, or industry events to understand what drove the surge.* *Example: For the prompt “best AI writing tools,” volume peaked in December and January, possibly due to end-of-year content planning or New Year campaigns.* ### Regions Below the chart, Prompt Explorer shows a country-wise breakdown of where the prompt is most active. This lets you localize your strategy based on where the question is being asked. For each country, you’ll see the estimated monthly search volume for that prompt. Use this to: * Prioritize markets where AI search behavior is strongest * Spot untapped regions where your brand isn’t visible yet * Adjust language and examples in your content by region *Example: In this case, the prompt has the highest usage in the United States (21,681), followed by India and Canada. This tells you where interest is concentrated and where it may be worth launching targeted campaigns.* These additional data points make Prompt Explorer more than just a list of questions. They help you shape campaigns around when and where to engage your audience based on real AI search behavior. ***To put these insights into action, head to your Writesonic dashboard and[check out Prompt Explorer](https://app.writesonic.com/geo/brand-visibility?v2=true). Use AI Search Volume to prioritize high-demand prompts, monitor usage frequency, and identify where your brand has the most to gain in generative results.*** *** [Content Optimization](/docs/content-optimization) [Portfolio](/docs/portfolio) # Overview Source: https://apidocs.writesonic.com/docs/prompts-overview The page is your central hub for understanding how your brand performs across AI-generated search results. It aggregates data from major AI platforms — including ChatGPT, Perplexity, Claude, Google AI Overviews, and more — into a single, actionable dashboard. Use this page to quickly assess where your brand is gaining traction, where it's invisible, and how it stacks up against competitors in AI search. *** ## What You'll Find on This Page The Prompts Overview is organized into distinct sections, each designed to surface a specific layer of insight: * **Summary Cards** — High-level prompt and visibility stats at a glance. * **AI Visibility Trend** — A time-series chart tracking your brand's visibility over days or weeks. * **Leaderboard** — A topic-wise ranking of your brand vs. competitors across key metrics. * **Most-Searched Prompts by Users** — The highest-volume prompts your audience is asking across AI platforms. * **Top Prompts Driving Visibility for Your Brand** — Prompts where your brand appears most frequently in AI answers. * **Prompts That Don't Mention You** — Prompts where competitors are cited but your brand is absent. *** ## Summary Cards At the top of the page, you'll see a row of **summary cards** that give you an instant pulse check on your prompt performance. * **Total Prompts** — The total number of prompts currently being tracked for your brand, across all configured topics. This also indicates how frequently they're refreshed (e.g., *"tracked across X topics, run daily"*). * **Best Prompts** — The count of prompts where your brand has strong AI visibility (typically 80%–100% average visibility). These are your highest-performing queries. * **Answers Without You** — The number of AI-generated answers where your brand's visibility is 0%. These represent prompts where AI platforms respond to relevant queries but never mention your brand. * **Prompts Gaining Visibility** — Prompts where your brand's visibility has **increased** compared to the previous period. A rising number here signals that your GEO efforts are working. * **Prompts Losing Visibility** — Prompts where your brand's visibility has **declined** compared to the previous period. Monitor this closely to catch drop-offs early and take corrective action. > **Tip:** Use the date range selector and comparison toggle at the top of the page to compare metrics across different time periods and spot trends. *** ## AI Visibility Trend The **AI Visibility Trend** chart shows how your brand's visibility across tracked prompts changes over time. It's displayed as a line graph, with each line representing a different topic. **What it tracks:** * Your brand's **AI Visibility** percentage across all tracked prompts, broken down by topic. * Day-over-day or week-over-week shifts, depending on the selected time range. * A **Previous Period** comparison overlay to quickly assess whether performance is improving or declining. **How to use it:** * **Spot trends** — A sustained upward line indicates strong GEO performance. Declines or plateaus signal a need to investigate prompt coverage or competitor activity. * **Measure campaign impact** — After publishing new content or running outreach, check here to see if visibility has shifted. * **Toggle between Weekly and AI Visibility** views using the controls above the chart for different levels of granularity. > **Tip:** If you notice a sudden drop for a specific topic, drill down into the **All Prompts** page to identify which individual prompts lost visibility. *** ## Leaderboard The **Leaderboard** ranks your tracked topics across three core metrics, giving you a competitive snapshot at the topic level. | Metric | What It Shows | | - | - | | **AI Visibility** | The percentage of prompts (within that topic) where your brand is mentioned in AI answers. | | **Citation Share** | The percentage of citations your brand receives relative to all citations within that topic. | **Each row represents a topic** you configured during setup. The table also shows **change indicators** (e.g., ↑ 7% or ↓ 2%) so you can instantly see which topics are trending up or down compared to the previous period. **How to use it:** * **Defend your strengths** — Topics with high visibility and citation share are your competitive moats. Keep content fresh and authoritative here. * **Identify weak spots** — Topics with low or declining metrics need attention. Prioritize content creation or optimization efforts here. * **Benchmark across topics** — Compare metrics side-by-side to decide where to allocate resources for the highest impact. > **Best Practice:** Aim for high AI Visibility *and* high Citation Share. Visibility means your brand is mentioned; citation share means your content is being used as the source. *** ## Most-Searched Prompts by Users This section surfaces the **highest-volume prompts** that users are actively searching for across AI platforms. These are ranked by **Search Volume**, giving you a clear picture of where the demand is. **For each prompt, you'll see:** * **Search Volume** — The estimated number of times this prompt is searched, along with the change from the previous period. * **AI Visibility** — Your brand's visibility percentage for this specific prompt. * **Avg. Position** — Where your brand ranks in AI-generated answers for this prompt (lower is better). **How to use it:** * **Prioritize high-volume, low-visibility prompts** — These are prompts with significant audience demand where your brand isn't showing up. They represent the biggest growth opportunities. * **Protect high-volume, high-visibility prompts** — If your brand already ranks well for a popular prompt, ensure the underlying content stays current and competitive. * **Click "View most searched prompts →"** to access the full list and apply filters for deeper analysis. *** ## Top Prompts Driving Visibility for Your Brand This section highlights the **prompts that contribute the most to your brand's overall AI visibility**. These are the queries where AI platforms most frequently mention or cite your brand. **For each prompt, you'll see:** * **AI Visibility** — The percentage of AI answers (across platforms) that mention your brand for this prompt. * **Avg. Position** — Your brand's average ranking position within those AI answers. * **Search Volume** — How often this prompt is searched, providing context on its reach and impact. **How to use it:** * **Identify what's working** — These prompts represent your strongest content and positioning. Understand *why* they perform well (content structure, authority signals, relevance) and replicate that approach for other prompts. * **Keep content fresh** — Ensure the pages driving these wins remain accurate, up-to-date, and comprehensive. * **Click "View all high visibility prompts →"** for the complete list. > **Example:** If your brand consistently appears for prompts like *"best design tools in the market"* — that's a strong signal. Make sure your content behind that query remains the most authoritative and comprehensive. *** ## Prompts That Don't Mention You This is one of the most actionable sections on the page. It shows prompts where **competitors are mentioned by AI platforms, but your brand is completely absent**. **For each prompt, you'll see:** * A list of **competitors** and how frequently each is mentioned for that prompt. * A **"0" next to your brand** (labeled "You"), confirming your absence. **How to use it:** * **Build your content roadmap** — Each prompt here is a gap in your AI visibility. Create or optimize content that directly addresses these queries. * **Analyze competitor content** — Look at what competitors are doing differently for these prompts. Are they structured better? More authoritative? More recently updated? * **Track your progress** — Revisit this section weekly. As your GEO efforts take effect, prompts should start moving out of this list and into your visibility drivers. * **Click "View more"** to explore the full list of missing prompts and prioritize based on competitor frequency and strategic relevance. > **Action Tip:** These are high-intent queries where your brand is invisible. Filling these gaps is one of the fastest ways to increase your AI market share. *** ## Filters and Controls The Prompts Overview page includes several **filters** at the top to help you slice the data in ways that matter most to your strategy: * **Date Range & Comparison** — Select a reporting period and compare it against a previous period to track progress. * **Markets** — Filter by geographic region if you're tracking multiple markets. * **Topics** — Narrow the view to a specific topic to analyze performance at a granular level. * **Platforms** — Filter by AI platform (e.g., ChatGPT, Perplexity, Claude) to see how your brand performs on each. * **Branded vs. Non-Branded Prompts** — Toggle between prompts that include your brand name and those that don't, to assess organic vs. branded visibility. * **Presets** — Use saved filter presets for quick access to your most-used views. *** *** [Sentiment: Competitors](/docs/sentiment-competitors) [All Prompts and Answers](/docs/all-prompts) # Prompts vs Keywords [Very Important] Source: https://apidocs.writesonic.com/docs/prompts-vs-keywords-very-important The way people search has fundamentally changed. What worked for Google doesn't work for AI search. ### Keywords: The Old Way **Short-tail keywords:** 1-2 words * "presentation templates" * "logo generator" * "design tools" **Long-tail keywords:** 3-5 words * "free PowerPoint templates download" * "AI logo generator tools" * "social media design apps" **Question keywords:** Starting with who/what/where/when/why/how * "what is the best design tool" * "how to create presentations" * "where to find templates" ### Prompts: The New Reality Prompts are natural questions people ask AI, often including context and specific requirements: **Real prompt examples:** * "Where can I find high-quality Google Slides templates for business?" * "What's the best online social media post maker for beginners?" * "Our team struggles with design bottlenecks and approval processes. Are there any all-in-one solutions that streamline creative workflows?" Notice the pattern? These aren't keyword-stuffed queries. They're real questions with context, averaging 15-30 words compared to 2-5 word keywords. ### The Key Differences | Aspect | Keywords | Prompts | | - | - | - | | **Length** | 2-5 words | 10-25 words | | **Style** | Fragmented phrases | Natural questions | | **Context** | Minimal | Rich with details | | **Intent** | Implied | Explicitly stated | | **Format** | Search-optimized | Conversational | ### Why This Shift Happened 1. **AI understands context** - Unlike Google's keyword matching, AI processes entire sentences 2. **Users expect personalized answers** - Not 10 links, but THE answer for their situation 3. **Voice and chat interfaces** - We naturally speak in full sentences 4. **Complex decision-making** - Modern purchases involve multiple factors AI can process ## Understanding Prompts vs Answers ### What's a Prompt? A **prompt** is the question users type into AI platforms. Looking at your tracked prompts: **Informational prompts:** * "Top platforms for Google Slides templates and designs" * "SlideQuest alternatives for presentation templates and design" **Comparison prompts:** * "Free vs paid social media post maker tools comparison?" * "Logo design ai generator pricing and features comparison" **Problem-solving prompts:** * "How can I quickly resize my designs for different social media platforms without starting over each time?" * "best tools for design team collaboration and brand consistency" ### What's an Answer? An **answer** is what AI generates in response. It's where your brand either appears or doesn't. **Example:** * **Prompt:** "What's the best online social media post maker for beginners?" * **Answer:** "For beginners, Canva is often recommended due to its intuitive interface and extensive template library. Adobe Express also offers..." Your visibility score tracks how often you appear in these **answers**, not the prompts themselves. ### Why Tracking Answers Matters More 1. **Answers contain actual mentions** - Prompts rarely mention brands 2. **Answer variability shows true performance** - Same prompt, different answer = different visibility 3. **Answers reveal competitive landscape** - See who gets mentioned alongside you **Example:** * Prompts tracked: 168 * Answers tracked: Hundreds (multiple answers per prompt across platforms/time) * Your brand mentioned: 57% of answers * Your visibility: 57% ## How Writesonic Generates Authentic Prompts ### The Problem with Generic Approaches Most tools take keywords and add simple prefixes: * "presentation software" → "what is presentation software" * "logo generator" → "best logo generator" This completely misses how people actually search on AI platforms. ### The Writesonic Advantage We have **Chatsonic** - one of the top ChatGPT alternatives for marketing. This gives us massive advantages: **1. Real User Behavior Data** * **Millions of real prompts** from actual Chatsonic users * Understanding of natural language patterns * Insight into how marketers specifically search * Context and nuances generic tools miss **2. Pattern Recognition at Scale** From analyzing millions of queries, we identify: * Common phrasings for similar needs * Industry-specific language * Context clues that matter * Regional and demographic variations **3. Multi-Source Enhancement** We combine Chatsonic's millions of data points with: * **Google Keyword Planner**: Search volume and variations * **Ahrefs**: Organic keywords for you and competitors * **Reddit discussions**: How real people ask questions * **People Also Ask**: Related queries from Google * **Search Console**: Your existing traffic drivers **4. Advanced Pattern Application** We don't just collect data - we apply sophisticated patterns to generate realistic variations that match actual user behavior. ### Real Examples **Starting keyword:** "presentation templates" **What generic tools do:** * "what are presentation templates" * "best presentation templates" * "free presentation templates" **What Writesonic generates (from real patterns):** * "Top pitch deck examples and template sources for startups" * "Where to download the best PowerPoint templates for free?" * "Where can I find high-quality Google Slides templates for business?" * "SlideQuest alternatives for presentation templates and design" See the difference? Our prompts match how people actually ask questions. ## Types of Prompts That Drive AI Search ### 1. Feature/Capability Questions * "collaborative UI design tools for design teams" * "Apps for creating graphics for social media posts quickly" * "Social media post maker tools that work on mobile and desktop?" ### 2. Comparison Queries * "online design collaboration software comparison" * "Free vs paid social media post maker tools comparison?" * "collaborative design platform alternatives for team projects" ### 3. Use-Case Specific * "best tools for remote design collaboration workflows" * "Corporate social media design tools for professional branding" * "best ai logo design generator tools for small businesses" ### 4. Problem-Solution Prompts * "How can I quickly resize my designs for different social media platforms?" * "Our team struggles with design bottlenecks and approval processes..." ### 5. Direct Tool Searches * "Which is the best ai logo generator for professional business use?" * "what is the best ai design generator" * "which online logo generator ai tools are most popular" ## The Compound Effect When you understand prompts correctly: 1. **One page answers many prompts** → Higher visibility across variations 2. **Natural language matches user intent** → Better sentiment in answers 3. **Comprehensive coverage** → More citation opportunities 4. **Real value provided** → AI trusts and recommends your content *** **Now that you understand the language of AI search**, let's explore why different platforms behave so differently - and why your visibility varies between ChatGPT, Claude, and others. *** What’s Next * [Platform Behavior & Volatality](/docs/platform-behavior-tracking) # Review and modify prompts Source: https://apidocs.writesonic.com/docs/review-and-modify-prompts ### **Purpose**: This step allows AI models to accurately reflect and understand what they truly know about your brand, as well as your competitors. By defining the right set of prompts, you ensure that the AI is focusing on the most relevant aspects of your brand’s presence, strengths, and competitive landscape. These prompts guide the AI in generating insights, content, and responses that are tailored to your specific needs, helping it align more closely with your goals. *** ### **Inputs Required:** 1. **Pre-Defined Prompts for Each Topic**: We’ve already curated a list of **prompts for each topic** based on various real-life indicators and the latest trends. These prompts are designed to help the AI assess various aspects of your brand and your competitors, such as visibility, content performance, market positioning, and more. 2. **Customizing Prompts**: You have the option to **add** or **remove** prompts to better suit your brand's objectives. If you feel there’s a specific area you want to track or explore further, you can create new prompts. Similarly, if you think some existing prompts don’t add value, you can remove them. *** ### **Why It Matters**: Defining the right prompts for both your brand and competitors helps ensure that the AI focuses on the most relevant data points, leading to more actionable insights: * **Accurate Reflection of Your Brand**: The AI will use these prompts to better understand how your brand is perceived in different contexts. If the prompts align with your key objectives and challenges, the AI’s analysis will be more in line with what matters most to you. * **Benchmarking Competitors Effectively**: By providing specific prompts related to your industry overall, you can ensure that the AI is comparing your brand against relevant aspects of their activity (e.g., content, engagement, visibility, etc.), leading to more precise competitive insights. * **Tailored Insights**: Customizing and refining prompts allows the AI to generate insights that are more closely aligned with your evolving business needs, marketing strategy, and brand positioning.. *** ### **Best Practices for Managing Prompts**: 1. **Align Prompts with Business Objectives**: Make sure your prompts reflect the key areas you want to track, whether that’s brand sentiment, market share, content performance, or specific competitor activity. 2. **Be Specific**: The more precise your prompts, the more accurate the AI’s output will be. For instance, instead of a general prompt like “track mentions of our brand,” you could use a more specific prompt like “what are the top tools in xyz industry” 3. **Update Regularly**: As your business goals or competitive landscape change, revisit your prompts. Adding new ones or removing irrelevant ones ensures the AI stays aligned with your current focus. 4. **Use Prompts for Trend Monitoring**: Consider creating prompts that help the AI detect emerging trends or shifts in your industry, allowing you to stay ahead of the curve. *** By carefully curating and managing the prompts for your brand and competitors, you're enabling the AI to provide insights that are accurate, focused, and most importantly, actionable for your business. *** What’s Next * [Select competitors](/docs/select-competitors) # Select competitors Source: https://apidocs.writesonic.com/docs/select-competitors #### **Purpose**: Adding your competitors allows you to benchmark your brand’s presence by comparing it with both **direct** and **indirect competitors** in the market. This helps you gauge where your brand stands in the eyes of different AI models in relation to others, highlighting areas of strength and identifying opportunities for growth. *** ### **Inputs Required:** You’ll need to enter up to **5 competitors** to start. Don’t worry if you don’t have the full list right now; you can always update this later as you discover new competitors or adjust your strategy. * You can simply add the domains of the competitors you want to track. *** ### **Pre-Selected Competitors**: To get you started, we've already suggested a list of **competitors** based on market research and trends in your industry. These suggestions are meant to kickstart your benchmarking process, but feel free to add or replace them with competitors that are more relevant to your business. *** ### **Why It Matters:** Adding competitors and benchmarking your brand against them gives you valuable insights into your industry’s competitive landscape: * **Visibility Leaderboard**: You’ll be able to see how frequently your competitors are mentioned, relative to your brand. This helps measure brand awareness and visibility across the industry. * **Ranking Comparison**: The rankings table lets you compare how your brand stacks up against competitors in terms of mentions, share of voice, and overall online presence. If your competitors are consistently ranking higher or being mentioned more frequently, it’s an opportunity to adjust your strategy and increase your own visibility. * **Content and Marketing Gaps**: By tracking competitors, you can analyze where they are excelling (or lacking) in terms of content, SEO, and marketing strategies. This can help you identify content gaps and areas to differentiate your brand. *** ### **Best Practices for Adding Competitors:** 1. **Define Direct vs. Indirect Competitors**: * **Direct Competitors**: Brands that offer similar products or services and target the same audience. For example, if you're a SaaS provider, your direct competitors would be other SaaS companies in your niche. * **Indirect Competitors**: Brands that may not offer the same products but could capture the attention of your target market. For example, an alternative solution or a broader service offering might pose indirect competition. 2. **Use Competitors as Inspiration**: * By analyzing their visibility and online presence, you can identify successful strategies that might work for your own brand. Learn from their content, campaigns, and engagement strategies. 3. **Monitor Regularly**: * Competitors' performance can change over time. Periodically update the competitor list to keep it relevant and reflective of any shifts in your market. We will also suggest you to monitor any new competitors that come up. 4. **Look Beyond the Obvious**: * Sometimes, the most valuable competitors aren’t always the ones with the most visibility. Keep an eye on emerging players or brands that are innovating in ways that could impact your business. *** #### **Recommended Strategy for Selecting Competitors**: 1. **Start with the Big Names**: Start by adding the most well-known competitors in your industry. These are typically the brands that dominate in terms of market share and visibility. 2. **Add Niche or Emerging Competitors**: In addition to the big names, include some smaller or emerging competitors that might be gaining traction or could disrupt the market. 3. **Review Your Competitors’ Activity**: Periodically review your competitors' websites, content, and social presence to adjust your benchmarking strategy based on any changes. *** By tracking your competitors’ performance, you’re giving yourself the ability to stay competitive, learn from their strategies, and ultimately refine your own tactics to close the gap or leap ahead. *** [Review and modify prompts](/docs/review-and-modify-prompts) [Overview Page](/docs/overview-page) # Sentiment: Competitors Source: https://apidocs.writesonic.com/docs/sentiment-competitors ## Overview The **Sentiment: Competitors** page provides a comprehensive analysis of how your brand's sentiment performance compares against your key competitors. This feature helps you understand your competitive positioning in terms of customer perception and identifies opportunities to improve your brand sentiment strategy. *** ## Core Components ### 1. Best Competitor **What this shows:** Identifies the competitor with the **highest volume of positive sentiment keywords** in your market. This metric reveals who has successfully captured the most favorable brand associations and positive mentions across analyzed content. The positive keyword count is displayed directly below the competitor's name. **Why it matters:** * **Benchmarking excellence:** Understand who sets the standard for positive brand perception in your market * **Strategy insights:** Analyze what messaging and positioning strategies work best in your industry * **Gap identification:** Reveals the sentiment performance gap you need to bridge to become the market leader * **Competitive intelligence:** Learn from the best performer's approach to customer engagement *** ### 2. Weakest Competitor **What this shows:** Highlights the competitor with the **highest volume of negative sentiment keywords**. This metric identifies which brand is struggling most with negative perception, displaying their negative keyword count for context. **Why it matters:** * **Opportunity identification:** Reveals market gaps where you can differentiate through superior customer experience * **Risk awareness:** Understand common pitfalls in your industry to avoid * **Competitive advantage:** Position your brand as a better alternative in areas where competitors fail * **Market positioning:** Craft messaging that addresses industry-wide concerns more effectively *** ### 3. Sentiment Distribution Across Competitors **What this shows:** A stacked bar chart displaying the **proportion of positive versus negative sentiment** for each competitor. Each bar represents 100% of a competitor's sentiment, with green sections showing positive sentiment and red sections indicating negative sentiment. Taller green sections indicate better overall sentiment performance. **Why it matters:** * **Visual benchmarking:** Instantly compare your sentiment ratio against all competitors * **Performance patterns:** Identify if negative sentiment is an industry-wide challenge or competitor-specific * **Strategic planning:** Set realistic sentiment improvement targets based on market conditions * **Trend identification:** Spot which competitors have found effective solutions to common complaints *** ### 4. Keyword Sentiment Leaderboard **What this shows:** A detailed table breaking down the **most impactful positive and negative keywords** for each competitor. Keywords are ranked by frequency and impact, with positive keywords shown in green and negative in red. Numbers beside each keyword indicate mention volume, helping you understand which terms drive sentiment most strongly. **Why it matters:** * **Keyword strategy optimization:** Discover which positive keywords resonate most in your market * **Content planning:** Identify high-impact keywords to incorporate in your messaging * **Risk management:** Understand which negative keywords to address proactively * **Competitive messaging:** Learn what language works and what triggers negative responses * **SEO optimization:** Target positive sentiment keywords while addressing negative concerns in your content *** ## Key Benefits * **Data-driven decision making:** Move beyond assumptions with concrete sentiment metrics * **Competitive intelligence at scale:** Monitor multiple competitors simultaneously * **Strategic prioritization:** Focus resources on the most impactful improvements * **Performance tracking:** Establish baselines and measure progress over time *** ## FAQs **Q: How is sentiment determined for each keyword?** A: Advanced natural language processing algorithms analyze the context in which keywords appear to determine positive or negative sentiment. **Q: Can I export this data for reporting?** A: Export functionality is available through the download option, allowing you to share insights with stakeholders. **Q: What's the difference between "best competitor" and highest positive sentiment ratio?** A: The "best competitor" has the highest absolute number of positive keywords, while sentiment ratio shows the percentage split. A competitor might have a high ratio but lower volume. **Q: How can I improve my sentiment scores relative to competitors?** A: Address negative keywords appearing in your profile while amplifying messaging around successful positive keywords. Study your best-performing competitor's approach for insights. **Q: Is historical sentiment data available?** A: Use the date filter to analyze different time periods and track how sentiment evolves over time. *** [Sentiment: Platforms](/docs/sentiment-platform) [Prompts](/docs/prompts) # Overview Source: https://apidocs.writesonic.com/docs/sentiment-overview The page is your central hub for understanding how AI search engines perceive and talk about your brand. It aggregates sentiment data from AI-generated responses across platforms like ChatGPT, Perplexity, Claude, Google AI Overviews, and others — giving you a clear picture of whether your brand is being described or when it appears in AI answers. Think of it this way: visibility tells you \_**if your brand is mentioned**, but sentiment tells you \_**how it's mentioned**. A brand that's frequently mentioned but in a negative light may actually be worse off than one with fewer but positive mentions. This page helps you monitor, measure, and act on that distinction. *** ## Who Is This Page For? * **Marketing & Brand teams** who want to monitor public perception of their brand in AI-generated content. * **SEO & GEO specialists** tracking how sentiment shifts correlate with content updates and optimization efforts. * **Enterprise teams** managing reputation across multiple markets, platforms, and product lines. * **Executives & stakeholders** who need a quick, high-level read on brand health in the AI search landscape. *** ## Page-Level Filters Before diving into the data, you can refine what you see using filters at the top of the page: * **Date range selector** — Choose and compare two time periods (e.g., *12 Jan 2025 vs. 12 Jan 2025*) to track how sentiment has shifted over time. * **Markets** — Filter by the geographic region/market you're tracking (e.g., *All markets* or a specific country). * **Topics** — Narrow down to specific topics configured during your GEO setup. * **Platform** — View sentiment from a specific AI platform (e.g., ChatGPT, Perplexity, Google AI Overviews) or across all platforms. * **Tags** — Apply custom tags to segment and filter your sentiment data further. These filters let you isolate exactly the data you need — whether you're looking at a specific market, a particular AI platform, or a narrow topic area. *** ## Key Metrics (Summary Cards) At the top of the page, you'll see four high-level metrics that give you an instant snapshot of your brand's sentiment health: ### Overall Sentiment Score A **single numeric score** that represents the net sentiment of your brand across all tracked AI answers. This score accounts for both positive and negative mentions and provides a quick health check. * A **higher score** means AI platforms are describing your brand more favorably. * A **declining score** (indicated by a red percentage change) signals that negative mentions may be increasing or positive ones are dropping. * Use this as your **primary sentiment KPI** when reporting to stakeholders. ### Positive Sentiment Keywords The **total count of keywords** associated with positive sentiment about your brand. These are the terms AI engines are using in a favorable context when mentioning your brand. * An **upward trend** here means AI platforms are associating more positive language with your brand. * Monitor this alongside your content and PR efforts to see what's driving positive perception. ### Negative Sentiment Keywords The **total count of keywords** tied to negative sentiment. These keywords appear in AI responses where your brand is discussed in a less favorable or critical tone. * An **increasing count** here is a signal to investigate which themes or topics are driving negativity. * Cross-reference with the **Theme Performance** section (below) to pinpoint specific problem areas. ### AI Visibility Your brand's **overall AI visibility percentage** — the share of tracked AI responses that mention your brand. While not exclusively a sentiment metric, it provides critical context: sentiment data is only meaningful if your brand has enough visibility for it to matter. * A **rising visibility paired with positive sentiment** is the ideal scenario. * **Rising visibility with increasing negative sentiment** needs immediate attention — more people are seeing unfavorable mentions. *** ## Sentiment Distribution Over Time This chart visualizes how **positive and negative mentions** trend across your selected date range. It displays sentiment volume on a **weekly** (or custom) basis, allowing you to spot patterns, spikes, and dips. **What to look for:** * **Consistent green (positive) above red (negative)** — Healthy brand perception. AI platforms are talking about you favorably. * **Spikes in negative sentiment** — Could indicate a product issue, a competitor campaign, or negative press that AI engines have picked up. * **Crossover points** — When negative sentiment overtakes positive, this is a critical moment that warrants investigation. * **Previous period comparison toggle** — Enable this to overlay a prior time period and see how sentiment has improved or declined. **How to use it:** * Correlate sentiment shifts with your own marketing activities, product launches, or industry events. * If you see a spike in negative sentiment, drill down into the **Theme Performance** table (below) to identify which specific themes are driving it. * Export the chart data using the **download icon** for use in reports or presentations. *** ## Most Mentioned Keywords A **word cloud** that visualizes the keywords most frequently associated with your brand across AI responses, sized by **mention frequency** and colored by **sentiment**. **How it works:** * **Larger keywords** appear more frequently in AI-generated answers about your brand. * **Color coding** indicates sentiment — keywords in positive sentiment are visually distinguished from those in negative sentiment. * **Hover over any keyword** to see the exact mention count and its sentiment classification (e.g., *"User-friendly interface — Positive — Mentioned 123 times"*). **Why it matters:** * Quickly identify the **dominant narratives** AI engines are building around your brand. * Spot **emerging keywords** — new terms appearing in the cloud may signal shifting perception. * If negative keywords are growing larger (more frequent), it's a sign you need to address the underlying issues in your content or product experience. *** ## Theme Performance The **Theme Performance** section is the most actionable part of the Sentiment Overview page. It breaks down your brand's sentiment into **recurring themes** — the topics and patterns that AI platforms consistently associate with your brand. ### Tab Navigation The section is organized into five tabs, each showing a count of themes: * **Top Themes** — The most frequently mentioned themes across all AI responses. These represent the core narratives AI engines are building around your brand. * **Sentiment Gains** — Themes where positive sentiment has **increased** compared to the previous period. These are your wins. * **Sentiment Drops** — Themes where sentiment has **declined**. These need attention and potentially a targeted content or messaging response. * **Rising Mentions** — Themes that are being mentioned **more frequently**, regardless of sentiment. Useful for spotting trending topics. * **Falling Mentions** — Themes that are **losing traction** in AI responses. Could indicate decreasing relevance or shifting AI platform focus. ### Theme Table Each theme in the table includes: * **Theme name** — The specific topic or pattern (e.g., *Intuitive user interface*, *Responsive design*, *Seamless integration*). * **Sentiment score** — A numeric score with a visual bar showing the positive-to-negative ratio. Higher scores (with green bars) indicate more positive sentiment; lower scores (with red indicators) signal predominantly negative sentiment. * **Sentiment change indicator** — An arrow showing whether sentiment has improved (↑) or declined since the previous period. * **Mention count** — How many times this theme appeared in AI responses during the selected period. * **Mention change indicator** — An arrow showing whether mentions are increasing (↑) or decreasing (↓) compared to the prior period. ### Expandable Sub-Themes Click the **expand arrow (>)** next to any theme to reveal its **sub-themes** — the specific keywords and phrases that make up that broader theme. Each sub-theme shows its own sentiment score and mention count, giving you granular visibility into what's driving the overall theme's performance. For example, expanding *"Seamless integration"* might reveal sub-themes like: * *User-friendly interface* * *Quick load times* * *Comprehensive documentation* * *Frequent updates* This drill-down helps you understand not just *what* AI is saying, but the **specific attributes** driving positive or negative perception. ### How to Use Theme Performance * **Prioritize themes with high mentions and declining sentiment** — These are high-impact areas where negative perception is spreading at scale. * **Double down on themes with sentiment gains** — Identify what you're doing right and amplify it in your content strategy. * **Investigate rising mentions with low sentiment scores** — A theme gaining traction for the wrong reasons needs a swift content or messaging response. * **Use falling mentions as a signal** — If a previously strong theme is losing mentions, refresh the associated content to keep it relevant. *** ## Best Practices for Using Sentiment: Overview * **Check weekly.** Sentiment shifts can happen fast, especially after product updates, PR events, or competitor activity. A weekly review cadence helps you catch changes early. * **Pair sentiment with visibility.** A sentiment score in isolation doesn't tell the full story. Always consider it alongside your AI visibility metrics — high visibility with poor sentiment is more damaging than low visibility. * **Use filters strategically.** Don't just look at the aggregate. Filter by platform to see if sentiment issues are platform-specific (e.g., poor sentiment on ChatGPT but positive on Perplexity). Filter by topic to isolate which product areas are driving negative perception. * **Act on Theme Performance.** The theme table is your most actionable tool. Use it to brief content teams, inform product messaging, and identify specific areas for improvement. * **Export and share.** Use the download icons on charts and tables to pull data into reports and presentations for stakeholders. *** *** [Overview: Platforms](/docs/overview-platforms) [Sentiment: Themes and Keywords](/docs/all-themes) # Sentiment: Platforms Source: https://apidocs.writesonic.com/docs/sentiment-platform # How to Use the Sentiment: Platforms Tool for Platform-Level Sentiment Analysis ## Overview The **Sentiment: Platforms** tool in Writesonic's Generative Engine Optimization (GEO) suite gives you a clear, data-backed picture of how your brand is perceived across major AI-powered search engines and content platforms. It analyzes mentions of your brand and classifies them as positive, neutral, or negative, enabling you to spot opportunities, address risks, and maintain consistent brand perception. Whether you're an SEO specialist ensuring your brand ranks favorably in AI answers, a content marketer aligning messaging with perception, or an enterprise managing reputation, this tool provides the insights you need. *** ## Core Components ### 1. Best Platform **What this shows:** Identifies the AI platform where your brand receives the **highest positive sentiment** based on your tracked keywords. The platform displayed here represents your strongest performance, showing the total count of positive keywords that resonate well with that platform's responses. **Why it matters:** * **Leverage strengths**: Double down on successful strategies where your brand already resonates effectively * **Resource allocation**: Focus marketing efforts on platforms showing the best reception * **Benchmark setting**: Use your top performer as a model for improving weaker platforms *** ### 2. Weakest Platform **What this shows:** Highlights the AI platform with the **highest negative sentiment** for your tracked keywords. This metric pinpoints where your brand faces the most challenging perception, displaying the count of keywords generating unfavorable responses. **Why it matters:** * **Priority intervention**: Quickly identify platforms needing urgent reputation management * **Risk mitigation**: Address negative perceptions before they spread or solidify * **Growth opportunities**: Transform your biggest challenge into your next success story through targeted optimization *** ### 3. Sentiment Distribution Across Platforms **What this shows:** A stacked bar chart comparing positive (green) versus negative (red) sentiment percentages across all monitored AI platforms. Each bar represents 100% of the sentiment for that platform, making it easy to spot which platforms lean positive or negative at a glance. Platforms included typically cover ChatGPT, Google AI Mode, Perplexity, Gemini, Microsoft Copilot, and Grok. **Why it matters:** * **Holistic view**: Instantly understand your sentiment landscape across the entire AI ecosystem * **Pattern recognition**: Identify whether issues are isolated to specific platforms or widespread * **Strategic planning**: Make informed decisions about where to invest optimization efforts * **Trend spotting**: Quickly identify platforms that may need attention before problems escalate *** ### 4. Keyword Sentiment Across Platforms **What this shows:** A detailed table breaking down **specific keywords** and their sentiment performance on each platform. For every AI platform monitored, you can see: • Top positive keywords that generate favorable responses • Top negative keywords that trigger concerning content • Keyword counts and relevance indicators Each platform gets its own row with green-tagged positive keywords and red-tagged negative keywords, making platform-specific patterns immediately visible. **Why it matters:** * **Granular insights**: Understand exactly which terms drive positive or negative sentiment on each platform * **Content optimization**: Craft platform-specific strategies based on actual keyword performance * **Quick wins**: Identify easy improvements by addressing problematic keywords or amplifying successful ones * **Competitive advantage**: Tailor your messaging for each platform's unique response patterns * **ROI focus**: Prioritize optimization efforts on high-impact keywords that appear across multiple platforms *** ## How to Use This Data 1. **Start with extremes**: Review your Best and Weakest platforms to understand your performance range 2. **Analyze the distribution**: Check if sentiment patterns are consistent across platforms or vary significantly 3. **Deep dive into keywords**: Use the keyword table to identify specific terms driving sentiment 4. **Create targeted strategies**: Develop platform-specific content based on each platform's sentiment profile 5. **Track progress**: Monitor changes regularly to measure the impact of your optimization efforts *** [Sentiment: Themes and Keywords](/docs/all-themes) [Sentiment: Competitors](/docs/sentiment-competitors) # Set your target topics Source: https://apidocs.writesonic.com/docs/set-you-target-topics ### **Purpose**: Defining the key areas of interest allows you to track how your brand is represented across specific topics, keywords, and trends. This enables a deeper understanding of your brand’s visibility, audience engagement, and relevance in the market. By monitoring these areas, you can assess your brand’s performance, identify gaps in content coverage, and refine your strategies to align with your customers' interests. *** ### **Inputs Required:** You need to define up to **10 topics** that are most relevant to your brand and audience. These should be specific enough to provide actionable insights, but broad enough to capture a range of conversations that align with your business goals. #### **Examples**: * **"AI Copywriting"** * **"Marketing Automation"** * **"CRM tools"** These topics will be the foundation for tracking your brand’s presence in discussions, search queries, social conversations, and content related to these areas. ### Pre-Suggested Topics: To help you get started, we've already identified and suggested a list of topics that are relevant to your industry. These topics are tailored to help you immediately track your brand’s performance and identify areas for improvement. While you’re welcome to add your own, these pre-suggested topics are designed to kickstart your tracking process and give you a solid foundation. *** ### **Tips While Entering Topics:** #### 1. **Use Terms Your Customers Are Likely to Search or Ask AI About:** * Think about what your target audience might be searching for, whether they're researching solutions, looking for advice, or solving a specific problem. * **Example**: If you're a SaaS company, customers might be searching for terms like "best email automation tools," "CRM solutions for startups," or "AI writing tools for marketers." * **Tip**: Review search queries and social media posts from your target demographic to ensure you're choosing the right words. #### 2. **Avoid Overly Broad Topics**: * Broad topics like “AI,” “Digital Marketing,” or “Technology” might give you an idea of general trends, but they are so vast that they will be difficult to track meaningfully. You won’t gain actionable insights if your brand is part of a highly generalized category. * **Example**: Instead of just tracking “AI,” narrow it down to something like “AI for content marketing” or “AI-powered customer service chatbots.” These are much more specific and will give you better visibility into niche areas. #### 3. **Avoid Hyper-Specific Topics Unless Strategic**: * While it can be tempting to track very niche terms (like “real-time GPT content APIs”), such topics might only be relevant to a small audience. If your brand has a strategic focus in a niche market, this approach might be effective, but for most brands, it could limit potential insights and growth opportunities. * **Example**: “AI-driven influencer marketing platforms” is specific, but might be too small a segment unless that’s exactly where your brand is focused. Instead, consider tracking “influencer marketing tools” or “AI-powered marketing automation.” #### 4. **Consider Both Current and Emerging Topics**: * You should track both well-established topics in your industry and newer, emerging trends that could gain traction soon. Keeping an eye on trending keywords will help you stay ahead of competitors and relevant in the market. * **Example**: If you're in the fintech space, you could track current topics like “blockchain in finance” or “cryptocurrency regulations,” while also keeping an eye on newer topics like “Web3 banking solutions.” #### 5. **Align Topics with Your Business Objectives**: * Make sure the topics you select are aligned with your company’s current marketing, product development, and business growth goals. For example, if your business is focusing on growing in a specific vertical or expanding into new geographies, select topics that reflect those initiatives. * **Example**: If your business is focusing on SMBs, topics like “affordable CRM for small businesses” or “cloud solutions for SMBs” might be relevant. *** ### **Why It Matters:** Tracking your brand's presence across defined topics helps you: * **Measure Brand Visibility**: If you aren’t showing up under key topics, it’s an opportunity to fill that gap and adjust your content or marketing strategy accordingly. * **Identify Content Gaps**: If your competitors are consistently appearing in conversations around a specific topic that you aren’t, it’s a chance to start creating content or campaigns focused on that area. * **Target Audience Engagement**: Monitoring these topics allows you to see where your potential customers are engaging, what they’re talking about, and how you can better serve their needs. * **Optimize SEO and Keyword Strategies**: When you track topics that are relevant to your audience, you can build a content strategy that ranks for those keywords, improving your search engine visibility. *** #### **Recommended Strategy for Selecting Topics:** 1. **Brainstorm with Your Team**: Bring together your sales, marketing, and product teams to identify high-value keywords or topics. 2. **Research Trends**: Use tools like Google Trends, SEMrush, or Ahrefs to identify rising keywords and topics that align with your industry. 3. **Competitive Analysis**: See which topics your competitors are ranking for, and consider tracking those as well. 4. **Monitor and Update Regularly**: Topics that matter today might not be as important in a few months. Regularly revisit and update your tracked topics to stay ahead. By being strategic in selecting and tracking the right topics, you’re setting up a framework to continuously evaluate your brand’s position in the market, adjust your messaging, and discover new growth opportunities. *** What’s Next * [Review and modify prompts](/docs/review-and-modify-prompts) # Tags Source: https://apidocs.writesonic.com/docs/tags ## Overview **Tags** are labels that help you categorize and track your AI search visibility by different dimensions like products, services, campaigns etc within Writesonic’s GEO platform. By tagging your prompts and competitors, you can gain focused AI Visibility insights into specific aspects of your organization. Whether you’re managing multiple product lines, tracking seasonal campaigns. Tags enable you to segment your GEO analytics for more tactical insights. image (182).png *** ## What Are Tags? Tags are customizable labels that you can assign to both **Prompts** and **Competitors**. Each tag can be color-coded for easy visual identification and can be applied to multiple prompts or competitors simultaneously. **Key benefits of using Tags:** * **Organize by product line**: Track how different products perform across AI platforms * **Segment by category**: Analyze visibility for specific service categories or business units * **Campaign tracking**: Monitor the impact of marketing campaigns on AI search visibility * **Multi-dimensional analysis**: Apply multiple tags to the same prompt or competitor for granular insights *** ## Managing Tags The **Tags configuration page** allows you to create, edit, and organize all your tags in one centralized location. Access this page from the left sidebar under **Configure > Tags**. ### Creating a New Tag 1. Navigate to **Configure > Tags** from the left sidebar 2. Click the **+ Add tag** button in the top-right corner 3. In the “Create a new tag” modal: * **Tag name**: Enter a descriptive name for your tag (up to 40 characters) * **Color**: Select a color to visually distinguish this tag from others 4. Click **Create tag** to save **Best practices for naming tags:** * Use clear, descriptive names (e.g., “Vegan products” or “Holiday Campaign 2025”) * Keep names concise but meaningful * Use consistent naming conventions across your team ### Editing Existing Tags 1. Go to **Configure > Tags** 2. Locate the tag you want to modify in the tags table 3. Click the **edit icon** (pencil) next to the tag name 4. Update the tag name or color as needed 5. Save your changes ### Managing Tags Overview The Tags management page displays all your created tags in a table format with the following information: * **Name**: The tag label with its assigned color indicator * **Prompts**: Number of prompts currently assigned to this tag * **Competitors**: Number of competitors currently assigned to this tag * **Created date**: When the tag was originally created You can also search for specific tags using the search bar at the top of the table. *** ## Assigning Tags to Competitors Tags help you categorize competitors based on market segment, competitive tier, or any other dimension relevant to your business strategy. *Please note: Tags are Market agnostic* Screenshot 2025-10-15 at 11.26.01 AM.png ### How to Tag Competitors 1. Navigate to **Configure > Competitors** from the left sidebar 2. Locate the competitor you want to tag in the competitors table 3. In the **Tags** column, click **+ Tag** 4. A dropdown menu will appear showing: * **All tags**: Your existing tags with color indicators * **Create a new tag**: Option to create a tag on the fly 5. Select one or more tags to assign to the competitor 6. The selected tags will immediately appear in the Tags column **Note**: Each competitor can have multiple tags assigned, allowing for flexible categorization (e.g., tagging a competitor as both “Direct Competitor” and “Enterprise Segment”). *** ## Assigning Tags to Prompts Tagging prompts allows you to organize your tracking efforts by product, category, intent, or campaign, making it easier to analyze performance across different dimensions. Screenshot 2025-10-15 at 11.27.05 AM.png ### How to Tag Prompts 1. Navigate to **Configure > Topics and Prompts** from the left sidebar 2. In the prompts table, locate the prompt you want to tag 3. In the **Tags** column, click **+ Tag** 4. Select from existing tags or create a new one: * **Existing tags**: Check the tags you want to apply * **Create a new tag**: Click this option to add a new tag without leaving the page 5. Click outside the dropdown or press Enter to confirm **Bulk tagging**: You can assign the same tag to multiple prompts by repeating this process for each prompt. Consider grouping related prompts under common tags for easier analysis. ### Prompt Tagging Strategy Consider these tagging approaches for maximum effectiveness: * **Product-based**: Tag prompts related to specific products or services * **Funnel stage**: Categorize by awareness, consideration, or decision stage * **Content type**: Organize by how-to, comparison, review, or informational prompts * **Geographic focus**: Tag prompts targeting specific regions or markets * **Seasonal**: Group prompts for seasonal campaigns or events *** ## Filtering Dashboard Analytics with Tags Once you’ve tagged your prompts and competitors, you can filter your entire **Overview dashboard** to display metrics for specific tags, enabling focused analysis of your AI visibility performance. Screenshot 2025-10-15 at 11.23.12 AM.png ### How to Filter by Tags 1. Go to the **Overview** dashboard 2. Locate the **Tags** button in the filter bar at the top of the page 3. Click the **Tags** dropdown 4. Select one or more tags to filter by: * Selecting a single tag shows data for all prompts and competitors with that tag * Selecting multiple tags shows combined data across all selected tags 5. Your dashboard metrics will automatically update to reflect the filtered view ### What Gets Filtered When you apply tag filters, all dashboard components adjust accordingly: * **Brand Presence metrics**: AI Visibility, Answers mentioning you, and Competitor Rank * **Citations metrics**: Total pages cited, My pages cited, Pages mentioning me, Your citation rate * **Visibility trends over time**: Historical performance charts * **AI visibility leaderboard**: Competitor rankings and visibility percentages This filtered view helps you understand performance for specific product lines, campaigns without the noise of unrelated data. ### Clearing Tag Filters To return to viewing all data: * Click the **X** icon next to the selected tag(s) in the filter bar, or * Deselect all tags from the Tags dropdown menu *** ## Use Cases for Tags ### Example 1: Product Line Tracking A SaaS company offers three products: Analytics Pro, Marketing Suite, and Sales Hub. By creating tags for each product and assigning relevant prompts, they can: * Compare AI visibility performance across product lines * Identify which products gain the most AI mentions * Allocate content resources based on visibility gaps ### Example 2: Campaign Performance An e-commerce brand runs a Q4 holiday campaign. They create a “Holiday 2025” tag and assign it to: * Campaign-specific prompts (e.g., “best holiday gifts,” “Black Friday deals”) * Key competitors targeting the same seasonal audience This enables them to track campaign impact on AI search visibility in real-time. *** ## Frequently Asked Questions (FAQs) **Q: Can I delete a tag?** A: Yes, you can delete tags from the Tags management page by clicking the delete icon next to the tag. Note that deleting a tag will remove it from all associated prompts and competitors. **Q: Can I assign multiple tags to a single prompt or competitor?** A: Yes, you can assign multiple tags to both prompts and competitors. This allows for multi-dimensional categorization and more flexible analysis. **Q: Can I change the tags assigned to a prompt or competitor?** A: Absolutely. You can add or remove tags at any time from the Competitors or Prompts page without affecting your historical data. **Q: What happens to my data if I remove a tag from a prompt?** A: Removing a tag from a prompt does not delete any historical data. The prompt’s performance data remains intact; it will simply no longer be included when you filter by that specific tag. ### Dashboard Filtering **Q: Can I filter by multiple tags at once?** A: Yes, you can select multiple tags simultaneously. The dashboard will display combined metrics for all prompts associated with any of the selected tags. **Q: Do tag filters affect my raw data or just the dashboard view?** A: Tag filters only affect your dashboard view. Your underlying data remains unchanged, and you can remove filters at any time to see all your data again. **Q: Can I export filtered data by tag?** A: Yes, when you apply tag filters and download reports, the exported data will reflect only the filtered view based on your selected tags. **Q: How should I organize my tags for maximum effectiveness?** A: We recommend organizing tags based on your business structure and reporting needs. Common approaches include: * Product/service categories etc **Q: Should I create tags before or after adding prompts and competitors?** A: You can do either. The platform allows you to create tags at any time—during the initial setup or on-the-fly when assigning them. Many users start with a core set of tags and add more as their tracking needs evolve. **Q: How often should I review and update my tags?** A: Review your tag structure quarterly or whenever you launch new products, campaigns, or enter new markets. Remove obsolete tags and create new ones to keep your organization system aligned with your current business priorities. *** *** [Markets: Track multiple Regions and Languages](/docs/markets-track-multiple-regions-and-languages) [Writesonic GEO Looker Studio Integration](/docs/writesonic-geo-looker-studio-integration) # Why We Monitor Real AI Platforms, Not Just APIs Source: https://apidocs.writesonic.com/docs/why-we-monitor-real-ai-platforms-not-just-apis ## The Truth About What Your Customers See Picture this: A potential customer in New York opens ChatGPT and asks about your product. Another in London asks the same question through the API. They get completely different answers—not because one has web search and the other doesn't, but because they're using fundamentally different systems. This gap between API and consumer experiences could be undermining your entire AI strategy. ### Our Approach: Direct Platform Monitoring At Writesonic, we don't rely on APIs or approximations. We scrape the actual web interfaces of AI platforms—the same interfaces your customers use every day. By monitoring ChatGPT.com, Google AI Overviews, Perplexity.ai, and other platforms directly, we capture exactly what users see, including all platform-specific features, optimizations, and variations. This isn't just about technical accuracy—it's about truth. When we simulate searches from different locations, we're replicating the exact experience a customer in that location would have. ### The Misconception About API Web Search Yes, modern APIs now include web search capabilities. OpenAI's API can search the web. So can others. But assuming this makes API monitoring equivalent to platform monitoring is like assuming two news channels with access to the same wire services will run identical broadcasts. The raw capability is just the starting point—what matters is how it's implemented. ### Same Feature, Different Worlds When both the API and consumer platform perform web searches, here's what actually differs: **The Index Being Searched** The consumer ChatGPT interface might search Bing's full index, carefully optimized for conversational queries. The API version? It often uses a different, more limited index. By scraping the actual interface, we see which index is really being used and what results it returns. **The Volume of Sources** Watch ChatGPT work on the consumer platform—it might pull from 15-20 sources before crafting a response. The API version typically consults fewer sources, maybe 3-5. Our scraping approach captures every source consulted, giving you complete visibility into what informs responses about your brand. **The Selection Algorithm** The consumer platform has been optimized based on millions of interactions. It knows that for product reviews, user forums and recent tech blogs matter more than corporate websites. By monitoring the actual interface, we capture these sophisticated selection patterns that API calls miss entirely. ### The Location Intelligence We Capture Here's a crucial capability: our platform scrapes AI interfaces while simulating different geographical locations. This means we can show you exactly how responses vary across markets: **Location-Based Personalization** When we simulate a search from Tokyo, we capture how the platform considers local review sites, regional competitors, and market-specific features. A simulation from San Francisco reveals different results, reflecting that local context. This isn't possible with API monitoring—it has no concept of user location. **Regional Search Results** AI platforms incorporate local search results into their responses. A query about "best restaurants" from Paris gets different underlying search results than the same query from New York. We capture these variations by scraping from multiple locations. **Market-Specific Intelligence** For businesses operating globally, we reveal how your brand appears differently across markets. You might be highly visible in US searches while being completely absent from European results—critical intelligence that location-agnostic API monitoring misses. ### What Our Scraping Reveals By directly monitoring consumer interfaces across locations, we capture: **Complete Response Context** Not just the text, but how it's formatted, what's emphasized, and which sources are cited. The full user experience. **Dynamic Interface Elements** Consumer platforms often include interactive elements, and visual formatting that affects how information is perceived. APIs strip all of this away. **Real-Time Updates** We see when platforms update their interfaces, add new features, or change how they present information. API users might not notice these changes for months. ### A Real Comparison We recently ran an experiment that perfectly illustrates the gap between API and platform monitoring. We asked the same question through both channels: "What are the best tools for generative engine optimization?" **The API Response:** Look at what the API returned—a sparse, abbreviated answer that barely scratches the surface. A handful of tools mentioned in passing, minimal context, and crucially, almost no citations to back up the recommendations. The formatting is basic, the information thin. If you were relying on this to understand your competitive landscape, you'd be operating nearly blind. **The Real Platform Response:** Now look at what actual users see when they ask the same question on ChatGPT's web interface. The difference is staggering: * **Comprehensive tool listings** with detailed categorizations (GEO-Specific Tools, GEO Strategy & Methodology) * **Rich citations** from authoritative sources * **Structured formatting** that makes information digestible and actionable * **Real-time information** including dates ("3 days ago", "June 1, 2025") showing fresh, current content * **Detailed explanations** of what each tool does, pricing information, and specific features * **Multiple perspectives** from various industry sources, not just a generic list The platform response doesn't just list tools—it provides context, validates claims with sources, and gives users actionable intelligence. It pulls from recent articles, includes pricing details, and even mentions specific capabilities like "tracks AI visibility" and "monitors ChatGPT, Gemini." **The Citation Gap** Perhaps most telling is the citation difference. The API response has virtually no source attribution. The platform response cites over a dozen sources, each timestamped and linked. This isn't just about credibility—it's about understanding which sources influence AI perceptions of your market. When the platform cites nogood.io's "9 Best Generative Engine Optimization (GEO) Tools" from April 5, 2025, that tells you this source is shaping how AI understands your competitive landscape. The API response? Silent on sources, leaving you guessing about what influences AI perceptions. **What This Means for Your Brand** If your tool wasn't mentioned in the API response but appears in the platform response (or vice versa), you'd never know relying on API monitoring alone. You'd miss: * Whether you're being recommended to actual users * Which sources AI considers authoritative for your industry * How recent developments affect your visibility * What competitive context surrounds your mentions This isn't a minor discrepancy—it's a completely different view of reality. One that could mean the difference between understanding your market position and operating on false assumptions. ### The Technical Advantages of Scraping Our approach provides unique capabilities: **Exact Replication** We interact with AI platforms exactly as users do, capturing every nuance of the experience. **Location Simulation** By routing our scraping through different geographical points, we see true regional variations. **Complete Feature Access** All platform features—from web search to plugins to custom instructions—are captured in our monitoring. **Historical Accuracy** We build a true record of how responses evolved, not just API approximations. ### Why This Matters for Your Strategy The intelligence we gather through location-aware scraping enables: **Global Brand Management** Understand how your brand appears in every market, not just a generic global view. **Regional Optimization** Identify which markets need attention and what content resonates locally. **Competitive Intelligence** See which competitors dominate in specific regions and why. **Crisis Prevention** Detect regional issues before they spread globally. ### The Writesonic Difference Our platform doesn't just tell you about AI visibility—it shows you exactly what customers see, wherever they are. By scraping actual interfaces from multiple locations, we provide: * True user experience data from every market * Complete visibility into source selection and ranking * Regional variation intelligence * Platform-specific optimization insights This isn't available through API monitoring, no matter how sophisticated. ### The Future of AI Monitoring As AI platforms become more personalized and location-aware, the gap between API monitoring and real user experiences will only grow. Platforms are investing heavily in regional relevance, local content partnerships, and market-specific optimizations. Brands relying on location-blind API monitoring will miss these critical developments, making decisions based on a generic shadow of highly personalized user experiences. *** [Platform Behavior & Volatility](/docs/platform-behavior-tracking) [Dashboard](/docs/dashboard) # Writesonic GEO Looker Studio Integration Source: https://apidocs.writesonic.com/docs/writesonic-geo-looker-studio-integration Connect your AI search visibility data to Google Looker Studio ## What is the Writesonic GEO Presence Connector? The Writesonic GEO Presence connector for Google Looker Studio lets you import your AI search visibility data directly into Looker Studio. Create custom BI dashboards and reports using your brand performance data from AI platforms like ChatGPT, Perplexity, Claude, and Gemini. *** ## What this does for you * **Real-time data access**: Connect directly to your GEO Presence project for up-to-date visibility metrics * **Custom visualizations**: Create charts, graphs, and tables that match your reporting needs * **Team collaboration**: Share dashboards with stakeholders and team members *** ## Getting Started ### What You Need: * A Writesonic account with GEO Presence access * Your Business API key * A Google account with Looker Studio access ### Step 1: Access the Connector 1. Open [Looker Studio](https://lookerstudio.google.com/) 2. Click **Create** → **Data source** Create Data source Search for **Writesonic GEO Presence** in the connector gallery Search in connector gallery ### Step 2: Authorize the Connection 1. Click **AUTHORIZE** to begin authentication Authorize 1. Sign in with your Google account if prompted 2. Grant the necessary permissions ### Step 3: Configure Your Data Source 1. Enter your **API Key** from Writesonic 2. Enter your **Site URL** (e.g., `https://example.com`) Enter site url 3. Select one or more **Data Sources** Select one or more data sources ### Step 4: Connect and Validate 1. Click **CONNECT** 2. Review the available fields Review available fields 3. Click **CREATE REPORT/EXPORT** to start building *** ## Understanding Data Sources The connector provides access to 10 data sources: ### Performance Data Sources (Require Date Range) **Overall Website Performance** — Track brand performance metrics aggregated by website, including total prompts, mentions, visibility scores, and rankings over time. **Prompt Performance** — Analyze performance metrics for individual prompts, showing which queries drive the most visibility and mentions across AI platforms (ChatGPT, Claude, Gemini, etc.). **Individual AI Responses** — Access complete AI-generated responses with full text, brand mentions, platform details, and competitive context. ### Content Data Sources (Require Date Range) **Content Citations & Sources** — Discover which websites and domains AI platforms cite as sources, including citation URLs, domains, and associated brand mentions. **Keyword Performance Metrics** — Extract keywords and themes from AI responses to understand what terminology and topics are associated with your brand. ### Configuration Data Sources (No Date Required) **Available Topics** — Reference data of all topic categories used to organize prompts and analyze performance by topic. **Available Platforms** — Reference data of AI platforms and models (ChatGPT, Claude, Gemini, etc.) being tracked. **Tracked Websites** — Reference data of all websites being monitored, including your own website and competitors, with metadata like logos and website types. **Prompts Information** — Reference data of all configured prompts with their topics, tags, status, and country codes. **Available Tags** — Reference data of all tags used for organizing and filtering prompts. *** ## **What is a Dimension in Looker Studio?** A dimension is a categorical or descriptive field used to group, filter, or segment data. Dimensions are not aggregated; they represent attributes or categories. **Characteristics of Dimensions:** 1. Used for grouping and filtering (e.g., by date, category, name) 2. Not aggregated (text, dates, IDs, categories) 3. Appear in rows, columns, or filters in charts 4. Used to break down metrics image.png ### **Examples from Your Connector** * **Date** — groups data by date * **Performance Website Name** — groups by website * **Performance Topic Name** — groups by topic * **Answer Platform Name** — groups by AI platform * **Prompt Type** — segments prompts into "Branded" or "Non-Branded" * **Config Website Is Self** — boolean filter *** ## **What is a Metric in Looker Studio?** A metric is a numeric field that can be **aggregated** (summed, averaged, counted, etc.). Metrics represent measurable values and are used to quantify performance, analyze trends, and calculate statistics. **Characteristics of Metrics:** 1. Numeric values that can be aggregated (sum, average, count, min, max) 2. Used to measure performance, quantities, or calculated values 3. Appear as values in charts (Y-axis, values in tables, chart data points) 4. Can be broken down by dimensions to analyze patterns image.png *Metrics can be aggregated in various ways* **Examples from Your Connector** * **Performance Total Prompts** — count of prompts analyzed * **Performance Total Mentions** — total number of brand mentions * **Performance Visibility Score** — visibility percentage (0-100) * **Performance Rank** — average ranking position * **Performance Avg Visibility Score** — average visibility across models *** ## **Dimensions vs. Metrics: How They're Used Differently?** ### **Dimensions** * **What they are** — Categorical or descriptive fields (text, dates, IDs, booleans) * **Purpose** — Group, filter, and segment data * **Where they appear** — Row/column headers, filter controls, chart axes (X-axis) * **Example** — Performance Website Name groups data by website ### **Metrics** * **What they are** — Numeric fields that can be aggregated (sum, average, count, etc.) * **Purpose** — Measure performance, quantities, or calculated values * **Where they appear** — Values in tables, chart data points, Y-axis values, scorecards * **Example** — Performance Total Mentions counts how many mentions occurred ### **How They Work Together** * Dimensions provide context and categories (e.g., "by website" or "by date") * Metrics provide measurable outcomes (e.g., "total mentions" or "visibility score") * **Example:** A chart using Performance Website Name (dimension) on the X-axis and Performance Total Mentions (metric) on the Y-axis shows mentions per website, enabling performance comparisons and trend analysis *** ## Complete Dimensions Reference for the Writesonic GEO connector **About Meta Fields** Throughout the dimension tables below, you'll see some fields marked as *(meta field)*. A meta field refers to a field that contains information about the data itself, such as unique identifiers used for joining data sources or tracking timestamps. ### Common Dimensions (Available in All Data Sources) | Field | Type | Description | Usage Examples | | - | - | - | - | | **Data Source Type** | Text | Identifies which endpoint the data came from | Filter to show only specific data types in mixed reports | | **Date** | Date (YYYYMMDD) | The date for the metric data | Time-series charts, trend analysis, date comparisons | | **Last Refresh Time** | DateTime | When the data was last fetched from the API. | | | Added by Looker Studio | Monitor data freshness, troubleshoot sync issues | | | ### Overall Website Performance Dimensions | Field | Type | Description | Usage Examples | | - | - | - | - | | **Performance Website ID**(meta field) | Text | Unique identifier for the website | Can be used to join charts with other data sources such as citation view. | | **Performance Website Name** | Text | Brand or website name | Group metrics by brand, compare self vs competitors | | **Performance Website URL** | URL | Full website URL | Used to view the domain and/or the full link for the website. | ### Prompt Performance Dimensions | Field | Type | Description | Usage Examples | | - | - | - | - | | **Performance Prompt ID**(meta field) | Text | Unique identifier for the prompt | Can be used to join with Prompts Information to view detailed information about the prompt. | | **Performance Prompt Text** | Text | The actual AI query text | Identify which questions drive visibility | | **Performance Topic ID** | Text | Topic category identifier | Can be used to join with Topics config data to view the specific topics | | **Performance Topic Name** | Text | Human-readable topic name | Group analysis by topic category | | **Performance Prompt Tags** | Text | Comma-separated list of tags | Filter by tags to see which specific prompts you’d like to see. | | **Prompt Type** | Text | "Branded" or "Non-Branded" | Filter or group by prompt type to compare branded vs non-branded performance | ### Individual AI Responses Dimensions | Field | Type | Description | Usage Examples | | - | - | - | - | | **Answer Response ID**(meta field) | Text | Unique identifier for the AI response | Track individual responses | | **Answer Prompt** | Text | The prompt that generated this response | See exact questions and answers | | **Answer Platform ID** | Text | AI platform identifier | Join with Platform config data | | **Answer Platform Name** | Text | Provider name (OpenAI, Anthropic, etc.) | Compare performance across providers | | **Answer Platform** | Text | Specific model | Analyze which models mention your brand | | **Answer Topic ID** | Text | Associated topic identifier | Can be used to group by topic in other data sources (meta field) | | **Answer Topic** | Text | Topic name | Categorical analysis | | **Answer AI Response** | Text | Full LLM response text | Read actual AI-generated content | | **Answer Brand Mentions** | Text | Summary of brand mentions with ranks | Quick overview of competitive landscape | | **Answer Prompt Tags** | Text | Tags associated with the prompt | Campaign and strategy filtering | | **Prompt Type** | Text | "Branded" or "Non-Branded" | Filter or group by prompt type to compare branded vs non-branded | ### Content Citations & Sources Dimensions | Field | Type | Description | Usage Examples | | - | - | - | - | | **Citation ID**(meta field) | Text | Unique identifier for the citation | Can be used to join with Tracked Websites view to get more information on citations. | | **Citation Title** | Text | Page title of the cited source | Identify which content gets cited | | **Citation URL** | URL | Full URL of the citation | View the full URL of where the citation comes from. | | **Citation Domain** | Text | Domain name of the citation | Domain-level citation view | | **Citation First Seen** | DateTime | When citation was first detected | Timestamp for when that particular citation occurred | | **Citation Mentioned Websites** | Text | Brands mentioned in the citation | See which brands appear together | | **Citation Responses** | Text | Responses that used this citation | Understand citations in AI responses | ### Keyword Performance Metrics Dimensions | Field | Type | Description | Usage Examples | | - | - | - | - | | **Keyword ID**(meta field) | Text | Unique identifier for the keyword | Track specific keywords | | **Keyword** | Text | The extracted keyword or phrase | Identify important keywords | | **Theme** | Text | High-level thematic category | Thematic analysis | | **Sub-theme** | Text | More specific sub-category | Detailed content analysis | | **Keyword First Seen** | DateTime | When keyword was first detected | Track the first time the keywords appeared | | **Keyword Responses** | Text | Context where keyword appeared | Understand keyword usage and the relevant context of where it appears | ### Configuration Dimensions ### Available Topics | Field | Type | Description | | - | - | - | | **Config Topic ID** (meta field) | Text | Unique topic identifier | | **Config Topic Name** | Text | Topic display name | | **Config Topic Created At** | DateTime | Creation timestamp | | **Config Topic Updated At** | DateTime | Last modified timestamp | ### Available Platforms | Field | Type | Description | | - | - | - | | **Config Platform ID** (meta field) | Text | Unique platform identifier | | **Config Platform Name** | Text | Model name | | **Config Platform Provider** | Text | Provider (OpenAI, Anthropic, etc.) | | **Config Platform Category ID** | Text | Platform category identifier | | **Config Platform Category** | Text | Category name | ### Tracked Websites | Field | Type | Description | | - | - | - | | **Config Website ID** (meta field) | Text | Unique website identifier | | **Config Website Name** | Text | Brand/website name | | **Config Website URL** | URL | Website URL | | **Config Website Is Competitor** | Boolean | True if competitor | | **Config Website Is Self** | Boolean | True if your own website | | **Config Website Logo URL** | URL | Brand logo URL | | **Config Website Created At** (meta field) | DateTime | Creation timestamp | | **Config Website Updated At** (meta field) | DateTime | Updated timestamp | ### Prompts Information | Field | Type | Description | | - | - | - | | **Config Prompt ID**(meta field) | Text | Unique prompt identifier | | **Config Prompt Text** | Text | Full prompt text | | **Config Prompt Topic ID** | Text | Associated topic | | **Config Prompt Topic** | Text | Topic name | | **Config Prompt Country Code** | Text | Market/region code | | **Config Prompt Status** | Text | Prompt status (ACTIVE, etc.) | | **Config Prompt Tags** | Text | Associated tags | | **Prompt Type** | Text | "Branded" or "Non-Branded" | | **Config Prompt Created At** (meta field) | DateTime | Creation timestamp | | **Config Prompt Updated At** (meta field) | DateTime | Updated Timestamp | ### Available Tags | Field | Type | Description | | - | - | - | | **Tag ID**(meta field) | Text | Unique tag identifier | | **Tag Name** | Text | Tag display name | | **Tag Slug** | Text | URL-safe tag identifier | | **Tag Prompt Count** | Number | Number of prompts with this tag | | **Tag Created At**(meta field) | DateTime | Creation timestamp | | **Tag Updated At**(meta field) | DateTime | Updated Timestamp | *** ## Complete Metrics Reference ### Performance Summary Metrics | Metric | Type | Description | What Good Looks Like | Usage Examples | | - | - | - | - | - | | **Performance Total Prompts** | Number | Total prompts analyzed for this website | Higher is better (more coverage) | Track question volume trends | | **Performance Total Results** | Number | Successful AI responses received | Should be close to Total Prompts | Monitor data completeness | | **Performance Total Mentions** | Number | Times your brand was mentioned | Higher is better | Key KPI for brand visibility | | **Performance Visibility Score** | Number (0-100) | Percentage of responses mentioning brand | 60%+ is excellent, 40-60% is good | Primary success metric | | **Performance Rank** | Number | Average position when mentioned (1=first) | Lower is better (1-3 is ideal) | Prominence in AI responses | **Calculation Notes** * **Visibility Score** — `(Total Mentions / Total Results) × 100` * **Rank** — Averaged across all mentions (only counted when brand is mentioned) ### Performance Prompts Metrics | Metric | Type | Description | What Good Looks Like | Usage Examples | | - | - | - | - | - | | **Performance Total Platforms** | Number | Number of AI models that responded | Higher is better | Cross-platform reach analysis | | **Performance Prompt Total Mentions** | Number | Total mentions for this specific prompt | Varies by prompt type | Identify high-performing questions | | **Performance Avg Visibility Score** | Number (0-100) | Average visibility across all platforms | 50%+ is strong | Prompt-level success tracking | | **Performance Avg Rank** | Number | Average rank across platforms | 1-3 is excellent | Prompt prominence analysis | ### Performance Answers Metrics | Metric | Type | Description | What Good Looks Like | Usage Examples | | - | - | - | - | - | | **Answer Brand Mention Count** | Number | Number of brands mentioned in response | Depends on strategy | Competitive landscape per response | | **Answer Avg Rank** | Number | Average rank for your brand | 1-3 is excellent | Response-level prominence | | **Answer Avg Visibility Score** | Number (0-100) | 0 or 100 (mentioned or not) | 100 is good | Binary mention tracking | ### Content Citations Metrics | Metric | Type | Description | What Good Looks Like | Usage Examples | | - | - | - | - | - | | **Citation Response Count** | Number | How many responses used this citation | Higher = more authoritative | Source authority ranking | | **Citation Mentioned Website Count** | Number | Brands mentioned in cited content | Varies by content | Content co-mention analysis | ### Content Keywords Metrics | Metric | Type | Description | What Good Looks Like | Usage Examples | | - | - | - | - | - | | **Keyword Response Count** | Number | Times this keyword appeared in responses | Higher = more relevant theme | Theme relevance tracking | ### Configuration Metrics | Metric | Type | Description | | - | - | - | | **Tag Prompt Count** | Number | Number of prompts tagged with this tag | *** ## Data Relationships & How to Use Them Together ### Joining Data Sources **Link Performance Summary with Website Config** ``` Performance Website ID → Config Website ID ``` Get brand names, logos, competitor flags, and URLs for your performance data. **Link Performance Prompts with Topic Config** ``` Performance Topic ID → Config Topic ID ``` Enrich prompt performance with full topic metadata. **Link Answers with Platforms** ``` Answer Platform ID → Config Platform ID ``` Get detailed platform information (provider, category) for response analysis. *** ## Creating Your First Report ### Quick Start: Executive Dashboard Let’s build a dashboard that answers: “How is our AI visibility performing?” ### Step 1: Create the Data Source 1. In Looker Studio, click **Create** → **Data source** 2. Search for **Writesonic GEO Presence** 3. Configure with your API key and Site URL 4. Select **the relevant data sources** 5. Click **CONNECT** image.png ### Step 2: Create a New Report Click **CREATE REPORT** to open the report editor. image.png ### Step 3: Add Key Performance Scorecards (Sample) **Visibility Score Card** * Add Chart → Scorecard * Metric: `Performance Visibility Score` * Date Range Dimension: `Date` *** ## Troubleshooting ### Common Issues **"Invalid API Key" or "401 Unauthorized"** * Verify your API key from the Writesonic dashboard * Ensure you're using the Business API key with GEO Presence access * Check for extra spaces when copying the key **"Site URL Not Found" or "404 Error"** * Verify URL format: [`https://example.com`](https://example.com) (include protocol, no trailing slash) * Check the exact URL in your GEO Presence dashboard * Ensure the site is active in your GEO Presence project **"No Data Available" or Empty Reports** * Check date range: Try "Last 7 days" to ensure data exists * Remove or relax filters to test * Verify data source selection (Config data sources don't require dates) * Check GEO Presence dashboard for data availability **"Connection Timeout" or Slow Loading** * Reduce date range to 1-3 days * Select fewer data sources * Use extract data (Data → Extract data) for historical analysis * Limit visualizations per page (6-8 max) **Data Not Refreshing** * Manual refresh: Data menu → Refresh data * Check Last Refresh Time field to verify data age * Wait 5-10 minutes for API cache to expire ### Getting Support **Technical Support** — Email: [\[email protected\]](/cdn-cgi/l/email-protection#a6d5d3d6d6c9d4d2e6d1d4cfd2c3d5c9c8cfc588c5c9cb) Include: Error details, account email, site URL (not API key) **Sales/Enterprise** — Email: [\[email protected\]](/cdn-cgi/l/email-protection#8dfeece1e8fecdfaffe4f9e8fee2e3e4eea3eee2e0) *** ### Frequently Asked Questions **Q: How often is data updated?** **A:** Data is updated as new prompts are executed and AI responses collected. The connector uses caching (5-10 minutes) for performance. **Q: Can I query data older than 7 days?** **A:** This is currently not supported. **Q: Why do some prompts show 0% visibility?** **A:** The brand wasn't mentioned in any AI responses for that prompt. This is valuable data for identifying content gaps. **Q: What's the difference between "Total Mentions" and "Prompt Total Mentions"?** **A:** "Total Mentions" is website-level (Summary), "Prompt Total Mentions" is prompt-level (Prompts data source). **Q: Can I track multiple websites in one report?** **A:** Yes, but each data source connects to one site URL. Create multiple data sources and blend them. **Q: Do rank values account for competitors?** **A:** Yes, rank shows position among all mentioned brands in a response. **Q: Why are my competitor visibility scores higher?** **A:** This identifies opportunities. Study their cited content and topics to inform your strategy. **Q: Can I export raw data?** **A:** Yes, use Looker Studio's export feature or query the API directly for raw JSON/CSV. **Q: How do I calculate Share of Voice?** **A:** `Your Mentions / SUM(All Website Mentions)` - create this as a calculated field. **Q: What does "Config Website Is Self = True" mean?** **A:** It identifies your own website vs. competitors in the Website configuration. **Q: What is the "Prompt Type" dimension?** **A:** Prompt Type classifies each prompt as either "Branded" (mentions your brand name directly) or "Non-Branded" (generic industry queries). It's available in Prompt Performance, Individual AI Responses, and Prompts Information data sources. Use it to compare how your brand performs when explicitly asked about vs. discovered organically. *** *For advanced features and enterprise integrations, contact [\[email protected\]](/cdn-cgi/l/email-protection#7b081a171e083b0c09120f1e081415121855181416)* *** [Tags](/docs/tags) [Site Audit](/docs/seo-audit) # Use Cases & Examples Source: https://apidocs.writesonic.com/mcp/examples Real-world prompts and workflows for the Writesonic MCP server. ## Getting Started Every session starts the same way — Claude needs your project ID first. > **You:** What projects do I have in Writesonic? Claude calls `get_all_projects` and returns your project list. From there, it uses the `project_id` automatically for subsequent queries. *** ## Share of Voice Tracking Track how your brand compares to competitors across AI platforms. > **You:** Show me my share of voice vs competitors on Claude for the last 30 days Claude calls `query_performance_report` with: * `dimensions: ["website"]` * `website_type: "SELF+COMPETITORS"` * Filter by model = Claude *** ## Citation Gap Analysis Find where competitors are getting cited but you're not. > **You:** Where are my competitors getting cited in AI responses that I'm missing? Claude calls `get_all_citations` filtered by competitor websites, then compares against your brand's citations to identify gaps. *** ## Prompt & Topic Analytics Understand which search queries and topics drive the most brand mentions. > **You:** Which prompts drive the most brand mentions? Break it down by AI model and topic Claude calls `query_performance_report` with: * `dimensions: ["prompt", "model"]` * `website_type: "SELF"` *** ## Sentiment Monitoring Track how AI platforms describe your brand over time. > **You:** Track how AI platforms describe my brand — is sentiment trending positive or negative? Claude calls `query_sentiment_report` with: * `dimensions: ["model", "date"]` * `date_aggregation_interval: "month"` * `website_type: "SELF"` *** ## Monthly Performance Report Generate a comprehensive monthly overview. > **You:** Give me a monthly performance summary for my brand — visibility, citations, and sentiment trends Claude chains multiple tool calls: 1. `query_performance_report` with `dimensions: ["date"]`, `date_aggregation_interval: "month"` 2. `query_citation_report` with `dimensions: ["date"]`, `date_aggregation_interval: "month"` 3. `query_sentiment_report` with `dimensions: ["date"]`, `date_aggregation_interval: "month"` *** ## Market-Specific Analysis Compare performance across geographic regions. > **You:** How does my brand visibility differ between US, UK, and Germany? Claude calls `query_performance_report` with: * `dimensions: ["market"]` * `website_type: "SELF"` *** ## Platform Deep Dive Focus on a specific AI platform. > **You:** Give me a detailed breakdown of my brand's presence on Perplexity — citations, sentiment, and top prompts Claude chains: 1. `query_performance_report` filtered by model = Perplexity 2. `query_citation_report` with `dimensions: ["domain"]`, filtered by Perplexity 3. `query_sentiment_report` filtered by Perplexity 4. `get_all_prompts` sorted by visibility, filtered by Perplexity *** ## Topic Strength Analysis Find which topics drive your AI visibility — and which are lagging. > **You:** Show our AI-search visibility broken down by topic, and tell me which topics are strongest and weakest Claude calls `query_performance_report` with: * `dimensions: ["topic"]` * `website_type: "SELF"` * Sorted by `visibility_score` descending *** ## Quarterly Visibility Report Get a one-page visibility summary for the quarter, ready to paste into a deck. > **You:** Write a one-page visibility summary for this quarter: our overall score and trend, the three topics where we gained the most, the three where we slipped, and a one-line reason for each Claude chains multiple tool calls: 1. `get_kpi_summary` with the quarter's date range — headline numbers with period-over-period deltas 2. `query_performance_report` with `dimensions: ["date"]`, `date_aggregation_interval: "week"` — the trend line 3. `query_performance_report` with `dimensions: ["topic"]` for the current vs previous quarter — topic gainers and losers *** ## Weekly GEO Digest Produce a recurring weekly summary of everything that moved. > **You:** Build a weekly GEO digest: our visibility change versus last week, any sentiment shift, the biggest-moving prompts, and the top three recommended actions Claude chains: 1. `get_kpi_summary` — week-over-week visibility and mention deltas 2. `query_sentiment_report` with `dimensions: ["date"]` — sentiment shift 3. `get_ai_answer_changes` — answers that appeared or disappeared this week 4. `get_actionables_dashboard` — recommended actions ranked by impact Pair with the Notion or Slack connectors to post the digest automatically. *** ## Diagnose a Visibility Drop Find out what caused a drop and how to fix it. > **You:** Our overall visibility fell noticeably this month. Pinpoint which topics and platforms drove the decline, whether sentiment turned negative, name the exact prompts responsible, and recommend a fix for each cause Claude chains: 1. `query_performance_report` with `dimensions: ["topic", "date"]` — which topics declined 2. `query_performance_report` with `dimensions: ["model", "date"]` — which platforms declined 3. `query_citation_report` with `dimensions: ["date"]` — whether citations were lost 4. `query_sentiment_report` with `dimensions: ["date"]` — whether sentiment turned 5. `get_ai_answer_changes` — the exact prompts where answers changed *** ## Competitor Teardown Get a full breakdown of where one competitor beats you. > **You:** Do a complete teardown of \[Competitor A]: every tracked question where they're cited and we aren't, the topics where they out-rank us, and the platforms where their lead is biggest, then give me a plan to overtake them Claude chains: 1. `get_prompts_not_mentioning_you` — prompts where you're absent but competitors appear 2. `query_performance_report` with `dimensions: ["website", "topic"]`, `website_type: "SELF+COMPETITORS"` — topics where they out-rank you 3. `query_performance_report` with `dimensions: ["website", "model"]` — platforms where their lead is biggest 4. `get_brand_gap_summary` — third-party pages citing them but not you *** ## Page Optimization Get a prioritized list of changes to make a page easier for AI to cite — then verify the lift. > **You:** For \[page URL], list exactly what to change to win more AI citations, in priority order, with the rationale for each Claude chains: 1. `get_all_optimization_opportunities` — finds the page and its detected issues 2. `get_optimization_fixes` — concrete fixes with rationale, in priority order 3. `get_webpage_citation_trends` — after you publish, re-check the page's citation trend to verify the lift *** ## Content Gap to Published Brief Find content gaps, brief them, and track the pages once they're live. > **You:** Find our top three content gaps by impact, create tracked prompts for the underlying questions, and re-check those pages for new AI citations once we publish Claude chains: 1. `get_all_new_content_opportunities` — content gaps where AI answers but you have no page 2. `get_new_content_impact` — ranks the gaps by estimated visibility lift 3. `create_prompt` — starts tracking the underlying questions *(write — Claude confirms before making changes)* 4. `get_webpage_citation_trends` — watches the published URLs for their first AI citations *** ## Brand vs Competitor Sentiment See whether AI mentions of your brand are positive or negative, next to named competitors. > **You:** How does AI talk about our brand versus \[Competitor A] and \[Competitor B] — the share of positive versus negative mentions, broken down by platform? Claude calls `query_sentiment_report` with: * `dimensions: ["website", "model"]` * `website_type: "SELF+COMPETITORS"` *** ## Brand Theme Analysis See the words and themes AI links to your brand. > **You:** What words and themes does AI most associate with our brand, and how does that differ from \[Competitor A]? Claude calls `get_all_keywords` grouped by theme and subtheme, once for your brand and once filtered to the competitor's website, then compares the two profiles. *** ## Action Center Prioritization Rank Writesonic's recommended actions by impact. > **You:** Show this week's recommended actions ranked by impact, and tell me which three would give the biggest visibility lift for the least effort Claude chains: 1. `get_actionables_dashboard` — all recommendations with per-category counts and impact 2. `get_brand_gap_impact`, `get_new_content_impact`, `get_broken_pages_impact` — estimated lift per action, to rank effort vs reward *** ## Tracking Setup via Chat Set up or change what you track by describing it. > **You:** Create a topic called \[topic name] and add these questions under it as tracked prompts in our primary market Claude chains: 1. `get_all_markets` — resolves your primary market's ID 2. `create_topic` — creates the topic *(write)* 3. `create_prompt` — adds each question under it *(write)* The same works for tags (`create_tag`), competitors (`add_competitors`, `bulk_remove_competitors`), and page portfolios (`create_portfolio`, `add_pages_to_portfolio`). Claude shows you the change and asks before it writes anything. *** ## AI Shopping Visibility For ecommerce brands: see how your products show up in AI shopping answers. Requires shopping tracking. > **You:** Show how often our products appear in AI shopping results versus competitors, broken down by platform Claude calls `query_performance_report` with: * `dimensions: ["website", "model"]` * `website_type: "SELF+COMPETITORS"` * Filter `has_shopping_card: true` For per-product detail, Claude uses `get_all_prompts_with_metrics` with `has_shopping_data: true`. *** ## Tips for Effective Queries * **Be specific about time ranges** — Claude can filter by date dimensions with day/week/month granularity * **Name the AI platform** if you want platform-specific data (e.g., "on ChatGPT", "across Perplexity") * **Ask for comparisons** — Claude can cross-tabulate multiple dimensions (e.g., model + date, topic + market) * **Request "my brand" vs "competitors"** — Claude uses `website_type` to scope data appropriately # MCP Server Source: https://apidocs.writesonic.com/mcp/mcp-server Connect Writesonic's AI search visibility data directly to Claude and other MCP-compatible AI assistants. ## Overview The Writesonic MCP (Model Context Protocol) server lets you query your GEO analytics data directly from Claude conversations. Ask questions about brand visibility, citations, sentiment, and competitor performance across 10+ AI platforms — all without leaving your AI assistant. **Server URL:** ``` https://mcp.writesonic.com/mcp ``` ## What You Can Do * **Track brand visibility** across ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews, and more * **Analyze citations** — see where and how often AI platforms reference your brand and which pages get cited * **Monitor sentiment** — understand how AI models describe your brand, and how the themes shift over time * **Compare against competitors** — benchmark share of voice, citation share, and visibility scores * **Find your gaps** — surface prompts where competitors appear but you don't, and the third-party pages behind them * **Get prioritized actions** — pull the Action Center's recommendations: content to create, pages to optimize, and broken pages AI still cites * **Explore any prompt** — investigate a query's AI answer and search volume even before you track it * **Manage your setup in chat** — create and edit tracked prompts, topics, tags, competitors, and page portfolios, or kick off a Brand Radar report * **Slice data by dimensions** — market, model, topic, date, website, and more ## Connection Methods | Platform | How to Connect | | - | - | | **Claude.ai** | Settings > Connectors > Add custom connector — `https://mcp.writesonic.com/mcp` | | **Claude Desktop** | Add to `claude_desktop_config.json` (see [Setup Guide](/mcp/setup)) | | **Claude Code** | `claude mcp add writesonic --transport streamable-http https://mcp.writesonic.com/mcp` | | **ChatGPT** | Settings > Connectors > enable Developer Mode > Create (see [Setup Guide](/mcp/setup#chatgpt)) | Team and Enterprise admins can roll the connector out org-wide — see [Organization Setup](/mcp/setup#organization-setup). ## How It Works 1. **Connect** — Add the Writesonic MCP server URL to your Claude client 2. **Authenticate** — Sign in with your Writesonic account via OAuth when prompted 3. **Query** — Ask Claude about your GEO data in natural language ### Example Conversation > **You:** Show me my brand's visibility score trend over the last 3 months, broken down by AI platform. > > **Claude:** Let me pull that data from Writesonic. I'll query the performance report grouped by model and date... > > *Claude calls `get_all_projects`, then `query_performance_report` with dimensions `["model", "date"]`* ## Requirements * A Writesonic account with any active **paid plan** * At least one project with tracked prompts configured in your [Writesonic dashboard](https://app.writesonic.com) ## Available Tools The MCP server exposes 87 tools spanning data fetching, aggregated reports, prompt analytics, citation analytics, actionable opportunities, and project management. See the [Tools Reference](/mcp/tools-reference) for full details. The core tools to know: | Tool | Description | | - | - | | `get_all_projects` | List all accessible projects (call this first) | | `get_all_prompts` | Browse tracked search queries with visibility scores | | `get_all_topics` | Get topic categories grouping related prompts | | `get_all_tags` | Get custom tag labels for filtering | | `get_all_citations` | Get individual citation URLs | | `get_all_websites` | Get tracked websites (brand + competitors) | | `get_all_keywords` | Get keywords found in AI responses | | `get_all_models` | Get tracked AI platforms | | `get_all_markets` | Get tracked geographic markets | | `get_all_domains` | Get citing domains (aggregated by domain) | | `query_performance_report` | Aggregated visibility and share of voice metrics | | `query_citation_report` | Aggregated citation counts and domain analysis | | `query_sentiment_report` | Sentiment analysis and keyword occurrence metrics | | `get_kpi_summary` | Single-call KPI dashboard with period-over-period deltas | | `get_actionables_dashboard` | Summary of all actionable recommendations | | `tools_info` | Get a ready-made execution plan for a complex question | ## Next Steps Platform-specific setup instructions Detailed tool parameters and responses Real-world prompts and workflows REST API documentation # Setup Guide Source: https://apidocs.writesonic.com/mcp/setup Step-by-step instructions for connecting the Writesonic MCP server to your AI assistant. ## Prerequisites Before connecting, make sure you have: 1. A Writesonic account with any active **paid plan** 2. At least one project with tracked prompts in your [dashboard](https://app.writesonic.com) ## Connection Details Use the same values in any client: | Field | Value | | - | - | | Name | Writesonic | | Description | Writesonic MCP | | Server URL | `https://mcp.writesonic.com/mcp` | | Authentication | OAuth | ## Claude.ai (Web) 1. Go to **Settings** in Claude.ai 2. Navigate to **Connectors** (under **Customize**) 3. Click **Add custom connector** 4. Enter the name `Writesonic` and the server URL `https://mcp.writesonic.com/mcp` 5. Click **Add**, then **Connect** — you'll be redirected to Writesonic to authorize access 6. Sign in and approve the connection 7. You're ready to query your GEO data On a **Team or Enterprise** plan, only Owners can add custom connectors. See [Organization Setup](#organization-setup) below. ## Claude Desktop Add the following to your `claude_desktop_config.json`: ```json macOS theme={"system"} // ~/Library/Application Support/Claude/claude_desktop_config.json { "mcpServers": { "writesonic": { "url": "https://mcp.writesonic.com/mcp" } } } ``` ```json Windows theme={"system"} // %APPDATA%\Claude\claude_desktop_config.json { "mcpServers": { "writesonic": { "url": "https://mcp.writesonic.com/mcp" } } } ``` Restart Claude Desktop after saving. On first use, you'll be prompted to authenticate with Writesonic. ## Claude Code (CLI) Run in your terminal: ```bash theme={"system"} claude mcp add writesonic --transport streamable-http https://mcp.writesonic.com/mcp ``` On first tool call, Claude Code will open a browser window for OAuth authentication. ## ChatGPT Custom connectors in ChatGPT require **Developer Mode**. 1. Open **Settings > Connectors** (ChatGPT prompts you to enable **Developer Mode** if it isn't already on) 2. Click **Create** to open the new connector dialog 3. Enter: * **Name:** `Writesonic` * **Description:** `Writesonic MCP` * **Server URL:** `https://mcp.writesonic.com/mcp` * **Authentication:** OAuth (settings are discovered automatically once a valid URL is entered) 4. Accept the "custom MCP servers introduce risk" notice and click **Create** 5. Click **Connect** and sign in to Writesonic via OAuth For workspace-wide rollout, see [Organization Setup](#organization-setup). ## Organization Setup On **Team**, **Enterprise**, and ChatGPT **Business/Enterprise** plans, only Owners and Admins can add custom connectors. Setting one up at the organization level only makes Writesonic **available** to your team — it does not connect anyone automatically. Each member still connects and authorizes Writesonic individually, signing in through OAuth with their own Writesonic account, before they can query data. ### Claude (Owners & Primary Owners) 1. Open **Settings** and go to **Organization settings** 2. In the left sidebar under **Libraries**, select **Connectors** 3. In the top-right, click the **Add** dropdown and choose **Custom** 4. Enter: * **Name:** `Writesonic` * **Remote MCP server URL:** `https://mcp.writesonic.com/mcp` 5. Leave the **OAuth Client ID** and **OAuth Client Secret** fields (under **Advanced settings**) blank — authorization is handled automatically 6. Click **Add** — Writesonic now appears in your organization's connector list Each member then enables it under **Settings > Connectors** (**Customize > Connectors**) and clicks **Connect** to authenticate with their own account. See Anthropic's [custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) guide for details. Owners can also restrict which **desktop extensions** members may install. If the desktop extension allowlist is enabled and Writesonic hasn't been added, members can't install the connector until an Owner adds it under **Organization settings > Connectors > Desktop** (or enables public desktop extensions). See Anthropic's [desktop extension allowlist guide](https://support.claude.com/en/articles/12592343-enabling-and-using-the-desktop-extension-allowlist). ### ChatGPT (Workspace Owners & Admins) Custom connectors require **Developer Mode**. If it isn't on, ChatGPT prompts you to enable it during this flow. 1. Open the ChatGPT **admin panel** and go to **Apps** 2. Click **Create** (top-right) to open the **New App** dialog 3. Fill in: * **Name:** `Writesonic` * **Description:** `Writesonic MCP` * **Connection:** keep **Server URL** selected and enter `https://mcp.writesonic.com/mcp` * **Authentication:** leave as **OAuth** 4. Read the risk notice and tick **"I understand and want to continue"** 5. Click **Create** — the app is created as a draft (shown with a **DEV** label) 6. On the draft, click **Publish**, work through both risk reviews until they show **Reviewed**, then click **Publish** again 7. Writesonic moves into your **Enabled apps** list Publishing makes Writesonic available to everyone in your workspace, but each user still connects and authorizes it individually via OAuth. ## Authentication The MCP server uses **OAuth 2.0** for authentication. When you first connect: 1. Your client redirects you to the Writesonic login page 2. Sign in with your Writesonic credentials 3. Authorize the MCP integration to access your GEO data 4. You're redirected back — the session is now active Sessions persist across conversations. You won't need to re-authenticate unless your token expires. ## Verifying the Connection After setup, try this prompt: > "List my Writesonic projects" Claude (or ChatGPT) should call the `get_all_projects` tool and return your project list. If this works, you're all set. ## FAQ Yes. The MCP server requires an active Writesonic paid plan and at least one project with tracked prompts in your [dashboard](https://app.writesonic.com). No. Organization or workspace setup only makes Writesonic *available*. Each member still connects and authorizes individually, signing in via OAuth with their own Writesonic account. On Team/Enterprise (Claude) and Business/Enterprise (ChatGPT), only Owners and Admins can add custom connectors. In ChatGPT, make sure **Developer Mode** is enabled. Otherwise ask an organization Owner to add Writesonic — see [Organization Setup](#organization-setup). * Make sure you have an active paid plan * Disconnect and reconnect the connector * Clear browser cookies for writesonic.com and retry * Verify you have at least one project in your [Writesonic dashboard](https://app.writesonic.com) * Ensure the project has tracked prompts configured * In Claude Desktop, restart the app after editing `claude_desktop_config.json` * In Claude Code, run `claude mcp list` to verify the server is registered # Tools Reference Source: https://apidocs.writesonic.com/mcp/tools-reference Complete reference for all 87 tools available in the Writesonic MCP server. All tools require a `project_id`. Always call `get_all_projects` first to get your project ID. Most tools are **read-only** — the [Management Tools](#management-tools) section lists the tools that create, update, or delete data. ## Common Parameters Most tools share these optional parameters: | Parameter | Type | Description | | - | - | - | | `project_id` | string | **Required.** Your project ID from `get_all_projects` | | `filters` | object | Narrow results by topic, market, model, etc. | | `order_by` | array | Sort results, e.g. `[{"field": "visibility_score", "order": "desc"}]` | | `pagination` | object | Limit results, e.g. `{"limit": 10, "offset": 0}` | | `metrics` | array | Request additional computed fields in the response | *** ## Data Fetching Tools These tools return lists of individual records. ### get\_all\_projects List all projects accessible to the authenticated user. **Call this first** — every other tool requires the `project_id` returned here. ### get\_all\_prompts Fetch all tracked search queries (prompts) with visibility scores, mention counts, and performance indicators. Use this to discover which queries are being monitored. ### get\_all\_topics Fetch topic categories that group related prompts. Use topic IDs for filtering in other tools. ### get\_all\_tags Fetch custom tag labels applied to prompts. Use tag IDs for filtering in other tools. ### get\_all\_citations Fetch individual citation URLs where the brand was referenced in AI responses. For aggregated counts, use `query_citation_report` instead. ### get\_all\_websites Fetch all tracked websites (your brand + competitors). Use this for competitive benchmarking and to get website IDs for filtering. ### get\_all\_keywords Fetch keywords found in AI responses related to the brand. Useful for content strategy and understanding brand perception. ### get\_all\_models Fetch all tracked AI platforms (ChatGPT, Perplexity, Claude, Gemini, etc.) with per-platform metrics. ### get\_all\_markets Fetch all geographic markets being tracked. Use market IDs for filtering in report queries. ### get\_all\_domains Fetch citing domains aggregated by domain. Unlike `get_all_citations` which returns individual URLs, this provides a higher-level view. *** ## Report Query Tools These tools return aggregated metrics grouped by dimensions you specify. ### Common Report Parameters | Parameter | Type | Description | | - | - | - | | `project_id` | string | **Required.** | | `dimensions` | array | **Required.** Group by: `topic`, `market`, `model`, `prompt`, `tag`, `date`, `website` | | `date_aggregation_interval` | string | `day`, `week`, or `month` — only applies when `date` is in dimensions | | `website_type` | string | `SELF` (your brand only) or `SELF+COMPETITORS` (all tracked websites) | | `filters` | object | Narrow by topic, market, model, etc. | | `order_by` | array | Sort results | | `pagination` | object | Limit results | ### query\_performance\_report Aggregated performance metrics: **share of voice**, **citation share**, **visibility score**, and **mention counts**. This is the main analytics tool for understanding brand performance. **Example dimension combinations:** * `["date"]` with `month` interval — monthly visibility trend * `["model"]` with `website_type: "SELF"` — per-platform brand performance * `["topic", "date"]` — topic performance over time * `["website", "market"]` — compare brand vs competitors by region ### query\_citation\_report Aggregated citation metrics: **citation counts**, **unique pages**, and **unique domains** grouped by dimensions. **Example dimension combinations:** * `["model"]` with `website_type: "SELF"` — citations by AI platform * `["date"]` with `month` interval — citation trend over time * `["model", "domain"]` — top citing domains per AI model ### query\_sentiment\_report Sentiment analysis metrics: **keyword occurrences** and **positive sentiment scores**. **Example dimension combinations:** * `["model"]` with `website_type: "SELF"` — sentiment by AI platform * `["date"]` with `month` interval — sentiment trend * `["topic"]` — sentiment breakdown by topic *** ## Project Overview Tools High-level dashboards and trends for a whole project. ### get\_kpi\_summary KPI summary card for a project — total visibility, mention count, citations, and sentiment breakdown, plus deltas vs. the previous period. Use this as a single-call dashboard view. ### get\_project\_visibility\_trends Project-wide visibility trends over time, aggregated across all tracked prompts. Requires `graph_type` (`visibility` or `citation_share`); supports `aggregate_level` (`daily`, `weekly`, `monthly`). *** ## Prompt Analytics Tools Leaderboards, rankings, and deep-dive analytics for individual tracked prompts. ### get\_all\_prompts\_with\_metrics Flat list of every tracked prompt with rolled-up metrics — visibility, mention count, citations, last-run date. ### get\_prompts\_leaderboard Ranked leaderboard of tracked prompts, by visibility score by default. Returns prompt text, visibility score, mention count, and search volume. ### get\_prompts\_not\_mentioning\_you High-volume tracked prompts where your brand is **not** appearing in AI answers — the gaps to close. Includes the competitors who do appear. ### get\_top\_prompts\_by\_volume Highest-search-volume tracked prompts in a project. Use this to prioritize the prompts real users ask most. ### get\_top\_prompts\_driving\_visibility Prompts where your brand appears most often in AI answers — the prompts contributing most to your overall AI visibility. ### get\_prompt\_info Static metadata for a single tracked prompt: text, topic, tags, intent, monthly search volume, branded flag, markets, and platforms. The `prompts` filter must resolve to exactly one prompt. ### get\_prompt\_answers The AI-generated answers for a single tracked prompt, grouped and ranked across runs, with platform, mentioned brands, and citations. ### get\_prompt\_citations Pages that AI platforms cite when answering a single tracked prompt — the source URLs the AI grounded its answer in. ### get\_prompt\_snippets Short text excerpts from AI answers for a prompt, focused on the surrounding context where brand mentions occur, with sentiment polarity. ### get\_prompt\_trends Time-series of visibility and mention metrics for one or more tracked prompts. Supports `aggregate_level` (`daily`, `weekly`, `monthly`) and event overlays. ### get\_prompt\_sentiment\_trends Time-series of sentiment polarity (positive / neutral / negative) for AI mentions of brands inside a single tracked prompt. ### get\_prompt\_search\_queries Related search queries surfaced for a tracked prompt — the broader query fan-out the AI considered when generating its answer. ### get\_prompt\_result\_details Full detail snapshot of a single AI-platform run for one prompt: the raw response text, extracted citations, brand mentions, and run metadata. ### get\_prompt\_result\_compare Compare a single prompt result against its baseline (typically the prior run), with citation deltas and mention diffs. ### get\_prompt\_results\_compare Diff two specific AI response runs for the same prompt by `current_result_id` and `previous_result_id` — side-by-side text, citation, and mention changes. *** ## AI Answer Tools Browse and analyze the raw AI answers collected across your project. ### get\_all\_ai\_answers All AI answers across every tracked prompt that mention your brand or competitors. Useful for bulk export or browsing every mention. ### get\_ai\_answer\_counts Aggregate counts of AI answers across the project — total mentions with per-platform and per-mention-type breakdowns. ### get\_ai\_answer\_changes Period-over-period change report: which AI answers appeared or disappeared between two date ranges. Use to detect emerging mentions or sudden loss of visibility. Requires a `period_filter` date-range comparison. *** ## Citation Analytics Tools Citation analytics scoped to your whole domain or to a single page. Webpage-scoped tools require a `cited_page_url` filter. ### get\_domain\_citation\_trends Time-series of how often AI platforms cite your domain across all tracked prompts. Supports `aggregate_level` (`daily`, `weekly`, `monthly`). ### get\_domain\_citation\_platforms Which AI platforms cite your domain most, with citation counts and share per platform. ### get\_domain\_citation\_prompts Which tracked prompts produce the most AI citations to your domain. ### get\_domain\_citation\_topics Topic categories where your domain gets cited most — which themes drive your AI visibility. ### get\_domain\_citation\_answers Sample AI answers that cite your domain, for spot-checking the context AI presents alongside your citations. ### get\_domain\_pages\_cited Your domain's most-cited pages, ranked by how often AI platforms cite each page. ### get\_industry\_cited\_pages Pages AI platforms cite in your industry — including competitors and third-party domains. Shows the overall citation landscape, not just your own pages. ### get\_webpage\_citation\_trends Time-series of how often AI platforms cite a single specific page. Supports `aggregate_level` (`daily`, `weekly`, `monthly`). ### get\_webpage\_citation\_platforms Which AI platforms cite a specific page most often. ### get\_webpage\_citation\_prompts Which tracked prompts drive AI citations to a specific page. ### get\_webpage\_citation\_topics Topic categories driving AI citations to a specific page. ### get\_webpage\_citation\_answers Sample AI answers that cite a specific page. *** ## Action Center Tools Actionable recommendations: gaps to close, content to create, pages to fix. ### get\_actionables\_dashboard One-call summary of all actionable recommendations — broken pages, brand gaps, new-content opportunities, and content-optimization suggestions, with counts and estimated impact per category. ### get\_brand\_gap\_summary Summary of brand-gap opportunities — AI answers where your competitors are mentioned but you are not, grouped by the third-party site where the mention originated. ### get\_all\_brand\_gap\_opportunities Paginated list of brand-gap opportunities. Each entry is a third-party page cited by AI where competitors appear but you don't — a place where outreach or content placement could win the citation. ### get\_brand\_gap\_impact Estimated visibility impact if you claim each third-party brand-gap mention — what closing the gap is worth. ### get\_brand\_gap\_responses Sample AI responses that cite third-party sites in your brand-gap set, so you can see exactly what AI says alongside the competitor citation. ### get\_brand\_gap\_existing\_mentions AI answers that mention your brand via a third-party site citation — wins to reinforce rather than gaps to close. ### get\_all\_new\_content\_opportunities Topics and queries where you should create new content to capture AI visibility — areas where AI is answering but you have no page to be cited. ### get\_new\_content\_impact Estimated visibility gains if each new-content opportunity is published. Use to prioritize which content brief to ship first. ### get\_new\_content\_sample\_answers Sample AI answers from queries that a specific new-content opportunity would address. Requires `content_id`. ### get\_all\_optimization\_opportunities Existing pages on your domain that need optimization — pages AI cites where fixing structural issues would likely lift citation rate or sentiment. ### get\_optimization\_fixes Concrete AI-suggested fixes for the issues detected on an optimization page — rewrites, structural changes, and missing-section recommendations. Requires `editor_history_id`. ### get\_optimization\_page\_answers Sample AI answers that cite a specific page flagged for optimization. Requires `optimization_page_id`. ### get\_all\_broken\_pages Broken pages on your domain that AI platforms are citing — pages returning 4xx/5xx or unreachable. Highest-priority fixes, since AI is sending visitors to dead URLs. ### get\_broken\_pages\_impact Before/after metrics for broken-page fixes — the citation and visibility lift from pages already marked resolved. *** ## Prompt Explorer Tools Investigate prompts that aren't yet tracked in your project. ### get\_prompt\_explorer\_overview Investigate a single prompt: returns the AI platform's response text, the prompt's monthly search-volume estimate, and related prompts. Requires `prompt`; optional `platforms` (default `["chatgpt"]`; supports `perplexity`, `google_ai_overview`, `gemini`, `copilot`). Consumes one Prompt Explorer credit per investigation. ### get\_prompt\_explorer\_search\_history List previously-investigated prompts with pagination. Pass an entry's `history_id` to `get_prompt_explorer_overview` to re-fetch prior results without spending a new credit. *** ## Portfolio Tools Portfolios group tracked pages (URLs) for cross-page analytics. ### get\_all\_portfolios List every portfolio configured for the project. Use this to discover `portfolio_id` values needed by the other portfolio tools. ### get\_portfolio\_info Get the metadata for a single portfolio (id, name, site id). Requires `portfolio_id`. ### create\_portfolio Create a new portfolio. Requires `portfolio_name`. **Write operation.** ### edit\_portfolio Edit a portfolio's properties — rename plus add/remove pages in one call. Requires `portfolio_id`. **Write operation.** ### rename\_portfolio Rename an existing portfolio. Requires `portfolio_id` and `portfolio_name`. **Write operation.** ### add\_pages\_to\_portfolio Add one or more tracked pages (URLs) to an existing portfolio, with per-URL add status. **Write operation.** ### remove\_pages\_from\_portfolio Detach one or more tracked pages from a portfolio. The pages remain tracked at the site level. **Write operation.** ### delete\_portfolio Delete an entire portfolio. Optionally also stop tracking its pages via `should_stop_tracking` (default `false`). **Write operation.** *** ## Brand Radar Tools Brand Radar reports run asynchronous competitor scans across your configured prompts and target domains. ### list\_brand\_radar\_reports List the Brand Radar reports for a project. Use this to discover `report_id` values for the other Brand Radar tools. ### get\_brand\_radar\_report\_filters The filter values available for a specific Brand Radar report — the citing domains, citing pages, and queries that appear in the report's data. Requires `report_id`. ### create\_brand\_radar\_report Kick off a new Brand Radar report run. Reports run asynchronously — poll the read tools to track status. **Write operation.** ### delete\_brand\_radar\_report Soft-delete a single Brand Radar report by `report_id`. **Write operation.** ### bulk\_delete\_brand\_radar\_reports Soft-delete multiple Brand Radar reports in a single call via `report_ids`. **Write operation.** *** ## Management Tools These tools **create, update, or delete** project configuration. Use with care. ### create\_prompt Add a new prompt (tracked AI query) to the project. Requires `name`, `market_id`, and `topic_id`. The prompt runs daily across the configured AI platforms. ### update\_prompt Edit a tracked prompt — change its text, topic, market, tags, or intent. Requires `query_id`. Omitted fields are left unchanged. ### bulk\_delete\_prompts Delete one or more prompts from the project in a single call via `prompt_ids`. ### create\_topic Create a new topic. Topics are categories used to group prompts for slicing reports. Requires `name`. ### update\_topic Rename an existing topic. Requires `topic_id` and `name`. ### delete\_topic Delete a topic from the project. Optionally scope the deletion to a single market via `market_id`. ### create\_tag Create a new tag. Tags are user-defined labels used to group prompts and competitors. Requires `name`. ### update\_tag Rename a tag, change its color, or both. Requires `tag_id` plus at least one of `new_name` or `color`. ### delete\_tag Delete a tag and all its prompt and competitor associations. Requires `tag_id`. ### add\_competitors Add one or more competitor websites to the project so they appear in side-by-side reports. Requires `competitor_market_pairs`. ### bulk\_remove\_competitors Remove one or more tracked competitor websites from the project in a single call. Requires `competitor_market_pairs`. *** ## Planner Tools Meta tools that help orchestrate multi-step queries. ### tools\_info Returns a step-by-step execution plan for a natural-language question — the recommended tool sequence with dimensions, measures, and filters pre-filled. Use this before making tool calls when the right tool isn't obvious or the question needs multiple tools. Requires `question`. ### execute\_plan Run a multi-step plan as one TypeScript program server-side instead of round-tripping on every intermediate result. Provides `tool(name, args)` and `output(value)` in an async sandbox with a 30-second timeout. Use only when a plan needs 3+ chained tool calls with loops, joins, or aggregation — for 1–2 calls, call tools directly. Requires `code`.