# Manage agency clients
Source: https://docs.qwairy.co/agencies/agency-guide

Choose a client isolation, access, branding, and reporting model for multiple Qwairy workspaces

This guide is for agencies and consultancies running GEO monitoring for more than one client brand in Qwairy. It connects the pieces you'll actually reach for: how to isolate each client's account, how much access to give them, how to make the experience look like yours, and how to report back to them.

Before onboarding your first client, make three decisions:

1. **Isolation model**: does each client get their own contained account, or do you manage every brand under one team?
2. **Access model**: does the client just view reports, or do they actively manage their own brand?
3. **Branding**: does the client see Qwairy, or does the experience look like your agency's own product?

The rest of this guide walks through each decision and the setup that follows from it.

***

## Choose an access model

The core decision is how much a client sees and controls. Qwairy gives you two mechanisms, and they serve different situations:

|                | **Virtual Teams (sub-team)**                                              | **Viewer role**                                                   |
| -------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Scope**      | Full sub-team: its own members, workspaces, and credit pool               | Single brand, read-only                                           |
| **Client can** | Actively manage the brand: prompts, competitors, settings                 | View dashboards and reports only                                  |
| **Isolation**  | Separate sub-team; client access does not include the parent organization | Same organization; read-only access is limited to assigned brands |
| **Billing**    | Inherits your organization's plan; sub-team draws from allocated credits  | N/A: no separate credit pool                                      |
| **Best for**   | Clients who need hands-on management of their own brand                   | Stakeholders who just need to check numbers                       |

Use a [Virtual Team](/documentation/team/virtual-teams) when the client needs to manage the brand rather than only read it. Viewer access stays read-only and brand-scoped within your organization, while a sub-team transfer gives management access in a separate team context.

If neither fits: for example, you're a small team managing a handful of client brands yourself, with no client logins at all: you can simply keep everything under one team and control brand access per [team member](/documentation/team/manage-members) instead.

<Note>
  Virtual Teams is available on **Business, Enterprise, and Agency Business
  plans**, or through an explicit feature override.
</Note>

***

## Set up a client

To give a client a fully isolated, self-service account for their brand:

<Steps>
  <Step title="Create a sub-team for the client">
    Go to **Team Management > Virtual Teams** and click **Create**. Name it after the client, and allocate a credit amount and workspace quota from your organization's pool.
  </Step>

  <Step title="Move or create the client's workspace in it">
    Either tick the workspace under **Move existing workspaces** while creating the sub-team, or move it afterwards with **Move workspace**. The workspace's full monitoring history travels with it: nothing resets.
  </Step>

  <Step title="Invite the client's team members">
    Switch to the client's sub-team and go to **Team Management > Members** to invite them. Their client access is limited to workspaces inside that sub-team.
  </Step>
</Steps>

Only Owners and Managers of your parent organization can move workspaces, and they retain access to every sub-team automatically without a separate invitation.

<Tip>
  If you'd rather keep the client's brand inside your own organization and just let a stakeholder check the numbers, skip the sub-team and add them as a [Viewer](/documentation/workspace/viewers) scoped to that one brand instead.
</Tip>

***

## Apply agency branding

Once a client is set up, you can make the whole experience look like your agency's own product instead of Qwairy's:

<CardGroup>
  <Card title="Custom Logo" icon="image" href="/agencies/logo">
    Replace the Qwairy logo across the dashboard, shared reports, and login.
  </Card>

  <Card title="Custom Domain" icon="globe" href="/agencies/custom-domain/overview">
    Serve the dashboard and login from your own subdomain, e.g. `analytics.yourcompany.com`.
  </Card>

  <Card title="Remove Branding" icon="eye-slash" href="/agencies/remove-branding">
    Hide "Powered by Qwairy" across the dashboard, shared links, and exports.
  </Card>
</CardGroup>

White-labeling is an **Enterprise** capability, configured under **Team Management > White Label**. See [Agencies overview](/agencies/introduction) for the full picture, including fully white-labeled authentication via SSO.

***

## Report to clients

Two ways to get results in front of clients, depending on whether they have a Qwairy login:

* **[Pitch Audits](/agencies/pitch-audits)**: create pre-sales audits for prospects before onboarding them into a full workspace, with prompt review, AI answer evidence, detected competitors, cited sources, and shareable reports.
* **[Shared links](/documentation/workspace/shared-links)**: generate a public URL for a dashboard, brand perception snapshot, GEO Matrix, competitor comparison, or prompt signals view. No Qwairy account needed on the client's end, and links can be set to expire or revoked at any time.
* **[Weekly report emails](/agencies/notifications)**: enable the per-workspace weekly report so clients get a recurring summary without checking the dashboard.
* **Outbound webhooks**: if your agency has its own reporting systems, route Qwairy's notification events to your own endpoint as signed JSON instead of Qwairy emails. This is an Enterprise capability; see [Developers > Webhooks](/developers/webhooks) for the payload format and setup, which starts in the same **Team Management > Notifications** screen as the weekly report.

***

## Related pages

* [Pitch Audits](/agencies/pitch-audits): pre-sales audits and shareable sales reports
* [Virtual Teams](/documentation/team/virtual-teams): sub-teams, credit allocation, and workspace transfers
* [Viewers](/documentation/workspace/viewers): read-only, brand-scoped access
* [Shared Links](/documentation/workspace/shared-links): public report links for clients without an account
* [Agencies Overview](/agencies/introduction): white-label capabilities at a glance
* [Custom Domain Overview](/agencies/custom-domain/overview): serve Qwairy from your own subdomain
* [Developers: Webhooks](/developers/webhooks): outbound notification events for your own systems


# DNS Setup
Source: https://docs.qwairy.co/agencies/custom-domain/dns-setup

Add your custom domain in White Label settings and point it to Qwairy with a CNAME record at your DNS provider.

Setting up a custom domain takes two parts: adding the subdomain in Qwairy, then creating a CNAME record at your DNS provider.

## Add your domain in Qwairy

<Steps>
  <Step title="Open White Label settings">
    Go to **Team Management > White Label** in your Qwairy dashboard.
  </Step>

  <Step title="Add your custom domain">
    In the custom domain section, enter the subdomain you want to use (e.g. `analytics.yourcompany.com`) and save.
  </Step>

  <Step title="Copy the CNAME target">
    Qwairy displays the **CNAME target** to point your subdomain to. Keep this value handy for the next step.
  </Step>
</Steps>

<Warning>
  Use a subdomain (e.g. `analytics.yourcompany.com`). Apex (root) domains are not supported.
</Warning>

## Create the CNAME record

In your DNS provider (Cloudflare, Route 53, GoDaddy, etc.), add a new **CNAME** record:

```
Type: CNAME
Name: analytics            (your subdomain)
Value: <the value shown in your White Label settings>
```

* **Name**: the subdomain you added in Qwairy (for `analytics.yourcompany.com`, the name is usually `analytics`)
* **Value**: the CNAME target shown in your White Label settings

<Note>
  DNS providers label these fields differently. **Name** may appear as Host or Record, and **Value** may appear as Target, Points to, or Content. Use the exact target shown in your White Label settings.
</Note>

<Info>
  DNS propagation can take some time: usually minutes, but it can take up to 48 hours depending on your provider.
</Info>

## Next step

Once the record is in place, head to [Verification](/agencies/custom-domain/verification) to confirm your configuration and activate the domain.


# Custom domain
Source: https://docs.qwairy.co/agencies/custom-domain/overview

Serve the Qwairy dashboard and login from a branded subdomain such as analytics.example.com

A custom domain lets you serve the Qwairy dashboard and login from your own subdomain instead of the default Qwairy URL. Your team and clients sign in and work entirely under your brand.

## What a custom domain changes

* **A branded dashboard**: access Qwairy from a subdomain you control, such as `analytics.yourcompany.com`
* **A branded login**: your team signs in on your domain, with your [logo](/agencies/logo) on the sign-in page
* **A consistent experience**: paired with your logo and [removed branding](/agencies/remove-branding), the product looks and feels like your own

<Note>
  The custom domain brands the **sign-in page**, but magic-link emails and the Google consent screen stay Qwairy-branded by default. For fully white-labeled authentication on your domain, connect your own identity provider with [SSO](/documentation/team/sso): your IdP handles login, and with SSO + JIT provisioning, matching users are added to your workspace automatically on first sign-in.
</Note>

## Prerequisites

<Steps>
  <Step title="You control the DNS for a subdomain">
    You'll need access to your DNS provider to add a record for the subdomain you want to use (e.g. `analytics.yourcompany.com`).
  </Step>

  <Step title="Use a subdomain, not a root domain">
    Apex (root) domains such as `yourcompany.com` are not supported. Choose a subdomain like `analytics.yourcompany.com` or `ai.yourcompany.com`.
  </Step>
</Steps>

<Warning>
  Root (apex) domains are not supported. Always use a subdomain.
</Warning>

## How setup works

<CardGroup>
  <Card title="1. DNS Setup" icon="network-wired" href="/agencies/custom-domain/dns-setup">
    Add your domain in White Label settings and create the CNAME record at your DNS provider.
  </Card>

  <Card title="2. Verification" icon="circle-check" href="/agencies/custom-domain/verification">
    Verify your DNS, and the Qwairy team finalizes activation so your team can sign in at your domain.
  </Card>
</CardGroup>


# Verification
Source: https://docs.qwairy.co/agencies/custom-domain/verification

Verify your DNS configuration to activate your custom domain. Provisioning and the HTTPS certificate are handled automatically so your team can sign in at your domain.

Once your CNAME record is in place, verify it in Qwairy to activate your custom domain.

## Verify your DNS

<Steps>
  <Step title="Open White Label settings">
    Go to **Team Management > White Label** in your Qwairy dashboard.
  </Step>

  <Step title="Verify the DNS configuration">
    Next to your custom domain, click **Verify DNS Configuration**. Qwairy checks that your CNAME record points to the correct target.
  </Step>
</Steps>

<Info>
  If verification doesn't pass right away, your DNS record may still be propagating. Wait a little and try again: propagation can take up to 48 hours.
</Info>

## Activation

Once your CNAME record is in place, Qwairy provisions your domain automatically and a secure HTTPS certificate is issued for it. Verification confirms everything is live, and your team can then sign in to Qwairy at your domain.

<Note>
  Provisioning and the certificate are automatic - there is nothing else to configure on your side. If verification does not pass right away, your DNS may still be propagating; wait a little and try again.
</Note>

## Sign in on your domain

A few things to keep in mind once your domain is live:

* **Workspace membership is required**: every user who signs in on your domain must be a member of your workspace.
* **Independent sessions**: sessions on your domain are separate from sessions on [www.qwairy.co](https://www.qwairy.co). Signing in on one does not sign you in on the other.

<Tip>
  Pair your custom domain with a [custom logo](/agencies/logo) and [removed branding](/agencies/remove-branding) for a fully branded sign-in and dashboard experience.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="Verification keeps failing: what should I check?">
    Confirm the CNAME record's **Name** matches the subdomain you added in Qwairy, and its **Value** matches the target shown in your White Label settings exactly. DNS changes can take up to 48 hours to propagate, so it's worth trying again after a short wait.
  </Accordion>

  <Accordion title="Can I use a root domain like yourcompany.com?">
    No. Apex (root) domains are not supported. Use a subdomain such as `analytics.yourcompany.com`.
  </Accordion>

  <Accordion title="Do my users need a Qwairy account on my domain?">
    Yes. Every user who signs in on your domain must be a member of your workspace. You can invite them from **Team Management**.
  </Accordion>

  <Accordion title="Why am I signed out when I switch between my domain and www.qwairy.co?">
    Sessions on your custom domain are independent from sessions on [www.qwairy.co](http://www.qwairy.co). Signing in on one surface does not carry over to the other: this is expected.
  </Accordion>
</AccordionGroup>


# Agency white label
Source: https://docs.qwairy.co/agencies/introduction

Configure a custom logo, dashboard domain, login branding, and removal of Qwairy attribution

White label lets you apply your organization's branding to supported Qwairy surfaces. Upload a logo, serve the dashboard and login from a subdomain, and remove supported "Powered by Qwairy" attribution.

## What's included

<CardGroup>
  <Card title="Custom Logo" icon="image">
    Replace the Qwairy logo with your own across the dashboard, shared reports, and your branded login.
  </Card>

  <Card title="Branded Custom Domain" icon="globe">
    Serve the dashboard and login from your own subdomain (e.g. `analytics.yourcompany.com`).
  </Card>

  <Card title="Remove Qwairy Branding" icon="eye-slash">
    Hide the "Powered by Qwairy" branding across the dashboard, shared links, and exports.
  </Card>
</CardGroup>

## Authentication

On a custom domain, the **sign-in page is branded** with your logo and name. By default, the sign-in methods themselves stay Qwairy-branded: magic-link emails come from Qwairy and the Google consent screen shows "Qwairy".

For **fully white-labeled authentication**: where your users authenticate entirely under your brand and never see Qwairy: connect your own identity provider via [SSO](/documentation/team/sso). Your IdP then handles sign-in, and with enforcement on it becomes the only way your domain's users log in.

## Who it's for

White-Label is designed for teams that share Qwairy with clients, partners, or internal stakeholders under their own brand: agencies, consultancies, and organizations that want a fully branded analytics experience.

## Enable white label

White-Label is an **Enterprise** capability.

<Note>
  White-Label is available on the **Enterprise plan**. To enable it for your team, talk to your account manager, or [book a demo](https://www.qwairy.co/demo).
</Note>

Once it's enabled for your team, you'll find the controls under **Team Management > White Label**.

## Explore

<CardGroup>
  <Card title="Custom Logo" icon="image" href="/agencies/logo">
    Upload your logo and learn where it appears.
  </Card>

  <Card title="Remove Branding" icon="eye-slash" href="/agencies/remove-branding">
    Hide the "Powered by Qwairy" branding.
  </Card>

  <Card title="Custom Domain Overview" icon="globe" href="/agencies/custom-domain/overview">
    Serve Qwairy from your own subdomain.
  </Card>

  <Card title="DNS Setup" icon="network-wired" href="/agencies/custom-domain/dns-setup">
    Add your domain and create the CNAME record.
  </Card>

  <Card title="Verification" icon="circle-check" href="/agencies/custom-domain/verification">
    Verify your DNS and activate your domain.
  </Card>

  <Card title="Notifications" icon="bell" href="/agencies/notifications">
    Control which emails Qwairy sends, or route events to your own webhook.
  </Card>

  <Card title="Pitch Audits" icon="chart-line" href="/agencies/pitch-audits">
    Run pre-sales prospect audits and share reports before client onboarding.
  </Card>

  <Card title="SSO" icon="shield-check" href="/documentation/team/sso">
    Fully white-label authentication with your own identity provider.
  </Card>
</CardGroup>


# Custom Logo
Source: https://docs.qwairy.co/agencies/logo

Upload your own logo to replace Qwairy branding across the dashboard, shared reports, and your branded login.

Uploading a custom logo replaces the Qwairy logo with your own throughout the experience your team and clients see.

## Upload your logo

<Steps>
  <Step title="Open White Label settings">
    Go to **Team Management > White Label** in your Qwairy dashboard.
  </Step>

  <Step title="Upload your logo">
    In the logo section, click **Upload** and select your image file. Your logo is applied right away.
  </Step>
</Steps>

## Accepted formats

| Requirement      | Detail          |
| ---------------- | --------------- |
| **File types**   | PNG, JPEG, WebP |
| **Maximum size** | 5 MB            |

<Warning>
  SVG files are not supported. Upload a PNG, JPEG, or WebP image instead.
</Warning>

<Tip>
  For the sharpest result, use a high-resolution PNG or WebP with a transparent background.
</Tip>

## Where your logo appears

Once uploaded, your logo replaces the Qwairy logo in:

* **The dashboard sidebar**: visible to everyone on your team
* **Shared report pages**: visible to anyone you share a link with
* **Your branded login**: when a [custom domain](/agencies/custom-domain/overview) is set up, your logo appears on the sign-in page

<Note>
  To present a fully branded experience, pair your logo with a [custom domain](/agencies/custom-domain/overview) and [remove the Qwairy branding](/agencies/remove-branding).
</Note>


# Agency notifications
Source: https://docs.qwairy.co/agencies/notifications

Control which email notifications Qwairy sends, including the per-workspace weekly report.

Notifications keep your team informed about changes in AI visibility without checking the dashboard manually. You can control which emails Qwairy sends on a per-workspace basis.

## Weekly report

Each workspace can send a **weekly report** email summarizing its AI visibility. The report is controlled per workspace, so you can enable it where it's useful and turn it off elsewhere.

<Steps>
  <Step title="Open Notifications">
    Go to **Workspace > Notifications** in your Qwairy dashboard.
  </Step>

  <Step title="Toggle the weekly report">
    Turn the **weekly report** on or off for this workspace. Changes take effect immediately.
  </Step>
</Steps>

<Info>
  Notifications are sent to the email address associated with each recipient's Qwairy account.
</Info>

## Outbound webhooks

Instead of receiving Qwairy emails, a white-label team can have notifications POSTed to its own endpoint as signed JSON events: so you deliver them to your users under your own brand, from your own systems.

<Note>
  Outbound webhooks are an **Enterprise** capability, documented in full under [Developers > Webhooks](/developers/webhooks) alongside the payload format, signature verification, and delivery behavior. The setup steps start in the same place as the weekly report: **Team Management > Notifications**.
</Note>


# Pitch Audits
Source: https://docs.qwairy.co/agencies/pitch-audits

Create pre-sales AI visibility audits for prospects before onboarding them into a full workspace.

Pitch Audits are a **pre-sales** workflow for agencies. They help you qualify prospects, prepare sales conversations, and show AI visibility opportunities before creating a full client workspace.

Enter a prospect domain, choose the market and AI engines, review the generated buyer prompts, then launch the audit and share the report.

Use Pitch Audits when you need to:

* show a prospect how AI assistants answer buyer questions in their category
* compare the prospect against competitors detected in those answers
* surface cited sources, content gaps, and available-to-buy opportunities
* share a sales-ready report before a full client onboarding

<Note>
  Pitch Audits are available to agency teams.
</Note>

## Create a pitch audit

<Steps>
  <Step title="Open Pitch Audits">
    In Qwairy, go to **Pitch Audits**.
  </Step>

  <Step title="Enter the prospect domain">
    Add the prospect website and choose the country for the audit. Country selection controls which AI engines are available.
  </Step>

  <Step title="Adjust audit settings">
    Choose from 1 to 100 prompts and select which AI engines to run. The default remains **20 prompts** with **ChatGPT**, **Gemini**, and **Copilot**. Depending on country availability, you can also select **Perplexity**, **AI Mode**, and **Grok**.
  </Step>

  <Step title="Review prompts">
    Qwairy generates buyer prompts for the selected market. Review, edit, add, or remove prompts before launching answer generation.
  </Step>

  <Step title="Launch answer generation">
    Confirm the prompts to spend credits and collect AI answers. You can also enable automatic launch after prompt review when creating the audit.
  </Step>
</Steps>

## Credits

Credits are charged only when AI answers are generated. Prompt preparation and prompt review do not spend response credits.

Pitch Audit and admin audit creation support up to **100 prompts**. The default remains **20**.

For Pitch Audits, each selected AI engine costs **1 credit per prompt**.

```
prompt count x selected engines = required credits
```

For example, a 20-prompt audit across the three default engines costs:

```
20 x 3 = 60 credits
```

## What the report includes

Pitch Audit reports are built for pre-sales conversations. A completed report includes:

* an AI visibility score for the audited brand
* the underlying prompts and answer evidence
* cited source domains and source URLs
* available-to-buy opportunities when sources can be targeted
* Social, Shopping, Local, and Ads/Sponsored insights when detected
* multi-competitor reports when competitors are found
* public sharing options for client-facing delivery

<Info>
  Pitch Audit reports are snapshots. AI assistants can answer differently over time, so create a new audit when you want a fresh market read.
</Info>

## Share the report

Open the completed report and copy its public link to share it with a prospect or client. Public reports include the same report improvements as the dashboard report, including the detected insight sections when available.

If your team uses white-label features, shared reports follow your agency branding settings.

## Read pitch audits through REST API and MCP

Pitch Audit integrations are read-only. They can list audits and read complete reports, but cannot create, confirm, retry, or modify them.

* REST API: `GET /api/v1/pitch-audits` and `GET /api/v1/pitch-audits/{auditId}`
* MCP: `list_pitch_audits` and `get_pitch_audit`

Each detailed report returns `availableSubjects` and `coCompetitors`. To open a co-competitor's derived report, reuse its `subjectId` with the same audit:

```text theme={null}
get_pitch_audit({ auditId: "...", subjectId: "rival.example" })
```

With REST API, use the nested report resource: `/api/v1/pitch-audits/{auditId}/reports/{subjectId}`. Add `includeCoCompetitorScores=true` to retrieve every co-competitor and its score summary in one request. Report summaries omit full answer text by default; pass `includeAnswers=true` only when evidence-level access is required.

See [Pitch Audit API](/developers/endpoints/pitch-audits/list) and [Pitch Audit MCP tools](/mcp/tools/pitch-audits).

## Related

* [Agency Guide](/agencies/agency-guide): set up clients, access, and reporting
* [Shared Links](/documentation/workspace/shared-links): share dashboard views without requiring a login
* [Providers & Credits](/documentation/get-started/credits): credit costs for monitoring and model usage


# Remove Branding
Source: https://docs.qwairy.co/agencies/remove-branding

Hide the "Powered by Qwairy" branding across the dashboard, shared report links, and exports with a single toggle.

Removing the Qwairy branding hides the "Powered by Qwairy" mark so the experience your team and clients see is fully yours.

## Hide the branding

<Steps>
  <Step title="Open White Label settings">
    Go to **Team Management > White Label** in your Qwairy dashboard.
  </Step>

  <Step title="Enable Remove Qwairy branding">
    Turn on the **Remove Qwairy branding** toggle. The change takes effect immediately.
  </Step>
</Steps>

## Where branding is removed

With the toggle enabled, the "Powered by Qwairy" branding is hidden across:

* **The dashboard**: no Qwairy mark in the interface
* **Shared report links**: clean, unbranded pages for the people you share with
* **Exports**: generated files come without Qwairy branding

<Tip>
  Combine this with a [custom logo](/agencies/logo) and a [custom domain](/agencies/custom-domain/overview) for an end-to-end branded experience.
</Tip>


# API tokens
Source: https://docs.qwairy.co/developers/api-keys

Create and manage API keys for programmatic access to your Qwairy data.

API tokens authenticate requests to the Qwairy REST API. Use a separate token for each integration so you can revoke access independently.

Open [Team Management > API Access](https://www.qwairy.co/dashboard/team/api) to manage tokens.

<Info>
  REST API access is available on active **Growth** plans and above.
</Info>

## Create an API token

Click **New API Token**, enter a descriptive name, and confirm. The full token is displayed once. Copy it immediately and store it securely.

<Warning>
  Full API tokens are shown only at creation. If you lose one, revoke it and create a replacement.
</Warning>

## API token table

| Column      | Description                                            |
| ----------- | ------------------------------------------------------ |
| **Name**    | Token label                                            |
| **Token**   | Stored prefix; the full token is never displayed again |
| **Created** | Creation date                                          |
| **Actions** | Revoke button                                          |

## Revoke an API token

Revoke the token and update any integration that uses it.

## Use API tokens

Include the token in the `Authorization` header:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.qwairy.co/api/v1/brands
```

See the [API introduction](/developers/introduction) for endpoint documentation.


# Authentication
Source: https://docs.qwairy.co/developers/authentication

Authenticate Qwairy API requests with a team-scoped Bearer token.

All API requests require a Bearer token in the `Authorization` header. Tokens are scoped to your team and provide access to all brands within your account.

## Get an API token

<Steps>
  <Step title="Open API Access">
    Go to [Team Management > API Access](https://www.qwairy.co/dashboard/team/api).
  </Step>

  <Step title="Create a new token">
    Click **New API Token** and give it a descriptive name, such as `analytics-export`.
  </Step>

  <Step title="Copy and store securely">
    Your token will be shown **only once**. Copy it immediately and store it securely.
  </Step>
</Steps>

<Warning>
  Never commit tokens to version control or expose them in client-side code. Revoke a compromised token from **Team Management > API Access**.
</Warning>

## Use your token

Include the token in the `Authorization` header with the `Bearer` prefix:

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer qw-api-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Token format

All Qwairy API tokens follow this format:

```
qw-api-[32 hexadecimal characters]
```

Example: `qw-api-a1b2c3d4e5f6789012345678abcdef01`

## Authentication errors

Authentication failures return HTTP `401` with a flat body. `error` is a short status label and `message` explains the failure:

| Condition                                                          | `message`                                                                        |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| Missing or malformed `Authorization` header (not `Bearer <token>`) | `Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx` |
| Invalid or revoked token, or plan below Growth                     | `Invalid API token or insufficient subscription plan (Growth+ required)`         |

### Synthetic error response

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx"
}
```

See [Error codes](/developers/errors) for both gateway and resource error shapes.

## Security practices

<CardGroup>
  <Card title="Use environment variables" icon="key">
    Store tokens in environment variables, not in code.

    ```bash theme={null}
    export QWAIRY_API_TOKEN="qw-api-xxx"
    ```
  </Card>

  <Card title="Use descriptive names" icon="tag">
    Name tokens by their purpose for easy management.
  </Card>

  <Card title="Revoke unused tokens" icon="rotate">
    Remove tokens that are no longer attached to an active integration.
  </Card>

  <Card title="Separate integrations" icon="layer-group">
    Create different tokens for different integrations.
  </Card>
</CardGroup>

## Manage tokens

Manage API tokens from [Team Management > API Access](https://www.qwairy.co/dashboard/team/api):

* **View tokens**: See all active tokens with their last usage date
* **Delete tokens**: Revoke access immediately by deleting a token
* **Create new tokens**: Generate new tokens as needed


# List actions
Source: https://docs.qwairy.co/developers/endpoints/actions/list

GET /api/v1/brands/{brandId}/actions
List the Action Center's prioritized recommendation queue.

Returns the current Action Center queue for a brand. Scores, tiers, and quick-win flags are deterministic outputs of the Action Center's current scoring rules; treat them as prioritization inputs, not predicted outcomes.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="string">
  Filter by status: `SUGGESTED` (awaiting triage), `PENDING`, `IN_PROGRESS`,
  `COMPLETED`, `DISMISSED`, `RESOLVED` (signal disappeared, auto-closed).
  Defaults to the live queue: `SUGGESTED` + `PENDING` + `IN_PROGRESS`.
</ParamField>

<ParamField type="string">
  Filter by action type: `CONTENT_GAP`, `CONTENT_OPTIMIZE`, `TECHNICAL_FIX`,
  `SCHEMA_ADD`, `AUTHORITY_BUILD`, `SOURCE_OUTREACH`, `COMPETITOR_ANALYSIS`,
  `PERCEPTION_FIX`, `SEARCH_TARGET`, `SOCIAL_ENGAGE`, `PRODUCT_OPTIMIZE`,
  `LOCAL_OPTIMIZE`
</ParamField>

<ParamField type="string">
  Filter by category: `TECHNICAL`, `CONTENT`, `AEO`, `AUTHORITY`, `VISIBILITY`
</ParamField>

<ParamField type="string">
  Filter by observed provider evidence. Accepts repeated or comma-separated provider IDs.
</ParamField>

<ParamField type="string">
  Filter by topic IDs. Accepts repeated or comma-separated UUIDs.
</ParamField>

<ParamField type="string">
  Filter by tag IDs. Accepts repeated or comma-separated UUIDs.
</ParamField>

<ParamField type="string">
  Combine selected tags with `or` or `and`.
</ParamField>

<ParamField type="string">
  Filter by `TOFU`, `MOFU`, or `BOFU`. Accepts repeated or comma-separated values.
</ParamField>

<ParamField type="string">
  Evidence period: `1`, `7`, `14`, `30`, `90`, `all`, or `custom`.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD` format. Required with `periodEnd` when `period=custom`.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD` format. Required with `periodStart` when `period=custom`.
</ParamField>

<ParamField type="number">
  Maximum number of actions to return (max: 100)
</ParamField>

<ParamField type="number">
  Pagination offset
</ParamField>

## Response

<ResponseField name="data" type="array">
  Actions ordered by priority (highest first), then creation date.

  <Expandable title="Action object">
    <ResponseField name="id" type="string">
      Unique identifier of the action
    </ResponseField>

    <ResponseField name="type" type="string">
      Action type (see the `type` filter for values)
    </ResponseField>

    <ResponseField name="category" type="string">
      Action category
    </ResponseField>

    <ResponseField name="sourceType" type="string">
      Detector family that produced the action (e.g. `PAGE_ISSUE`,
      `QUESTION_GAP`, `SOURCE_OPPORTUNITY`, `SEARCH_QUERY`)
    </ResponseField>

    <ResponseField name="scope" type="string">
      Nature of the work: `ON_SITE`, `OFF_SITE` or `SETUP`
    </ResponseField>

    <ResponseField name="title" type="string">
      Action title
    </ResponseField>

    <ResponseField name="description" type="string">
      What to do and why
    </ResponseField>

    <ResponseField name="sourceUrl" type="string | null">
      External URL backing the action, when applicable
    </ResponseField>

    <ResponseField name="targetProvider" type="string | null">
      AI provider this action is scoped to (null = brand-level)
    </ResponseField>

    <ResponseField name="evidenceProviders" type="array">
      Provider IDs explicitly present in the underlying evidence
    </ResponseField>

    <ResponseField name="evidenceScope" type="string">
      `OBSERVED`, `CURRENT`, or `UNATTRIBUTED`
    </ResponseField>

    <ResponseField name="forceTier" type="string">
      Priority tier: `CRITICAL`, `HIGH` or `STANDARD`
    </ResponseField>

    <ResponseField name="priorityScore" type="number">
      Tier-anchored score from 0 to 100: Critical 70-100, High 40-69, and Standard 10-39. It is derived from tier, demand badge, effort, and provider scope.
    </ResponseField>

    <ResponseField name="demandBadge" type="number">
      Demand signal from 1 to 5
    </ResponseField>

    <ResponseField name="isQuickWin" type="boolean">
      Whether the Action Center heuristic classifies the item as a quick win
    </ResponseField>

    <ResponseField name="effort" type="string">
      Estimated workload: `LOW`, `MEDIUM` or `HIGH`
    </ResponseField>

    <ResponseField name="status" type="string">
      Lifecycle status
    </ResponseField>

    <ResponseField name="signals" type="object | null">
      Raw quantified signals behind the priority (citations, fan-out
      occurrences, impressions, competitive pressure, affected pages...)
    </ResponseField>

    <ResponseField name="impactJustification" type="string | null">
      Stored explanation of the signals used for prioritization
    </ResponseField>

    <ResponseField name="effortJustification" type="string | null">
      Explanation of the estimated effort
    </ResponseField>

    <ResponseField name="baselineMetric" type="number | null">
      Metric value stored when the action was created
    </ResponseField>

    <ResponseField name="targetMetric" type="number | null">
      Target metric value, when applicable
    </ResponseField>

    <ResponseField name="questionId" type="string | null">
      Linked monitored prompt, when applicable
    </ResponseField>

    <ResponseField name="checklist" type="array">
      Generated checklist associated with the action
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation date
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last update date
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  `total`, `limit`, `offset`, `hasMore`
</ResponseField>

## Synthetic request

<RequestExample>
  ```bash cURL theme={null}
  curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/actions?status=SUGGESTED&limit=10" \
    -H "Authorization: Bearer $QWAIRY_API_TOKEN"
  ```
</RequestExample>

## Synthetic response

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "action_01",
        "type": "SOURCE_OUTREACH",
        "category": "AUTHORITY",
        "sourceType": "SOURCE_OPPORTUNITY",
        "scope": "OFF_SITE",
        "title": "Review citation gap for Publisher Example",
        "description": "Stored answers cite this source 16 times without a SELF mention.",
        "sourceUrl": "https://publisher.example",
        "targetProvider": null,
        "evidenceProviders": ["example-provider"],
        "evidenceScope": "OBSERVED",
        "forceTier": "HIGH",
        "priorityScore": 53,
        "demandBadge": 3,
        "isQuickWin": false,
        "effort": "MEDIUM",
        "status": "SUGGESTED",
        "signals": {
          "citations": 16,
          "sourceCategory": "MEDIA",
          "competitivePressure": 2
        },
        "impactJustification": "Source cited 16x by AI answers without mentioning the brand.",
        "effortJustification": "Outreach: research the contact, pitch, and follow up.",
        "baselineMetric": null,
        "targetMetric": null,
        "questionId": null,
        "checklist": [
          "Review what content the source already cites",
          "Compare the cited pages with your existing evidence",
          "Decide whether an outreach hypothesis is worth testing",
          "Record the test and monitor later observations"
        ],
        "createdAt": "2026-06-12T05:00:00.000Z",
        "updatedAt": "2026-06-12T05:00:00.000Z"
      }
    ],
    "pagination": { "total": 42, "limit": 10, "offset": 0, "hasMore": true }
  }
  ```
</ResponseExample>

## Errors

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| `400`  | Invalid enum, taxonomy, provider, or period filter |
| `401`  | Missing or invalid API token                       |
| `404`  | Brand not found or inaccessible                    |
| `429`  | Rate limit exceeded; honor `Retry-After`           |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get answer
Source: https://docs.qwairy.co/developers/endpoints/answers/get

GET /api/v1/brands/{brandId}/answers/{answerId}
Retrieve a single AI response with full text and detailed analysis.

Retrieve one stored answer with its prompt, provider and model labels, detected mentions, citations, query fan-outs, and SELF sentiment.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the answer
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="answer" type="object">
  <Expandable title="Full answer details">
    <ResponseField name="id" type="string">Answer ID</ResponseField>

    <ResponseField name="prompt" type="object">
      Associated prompt info (id, text, topic, type)
    </ResponseField>

    <ResponseField name="provider" type="string">AI provider name</ResponseField>
    <ResponseField name="model" type="string">AI model name</ResponseField>
    <ResponseField name="text" type="string">Full response text</ResponseField>

    <ResponseField name="competitors" type="array">
      List of mentioned competitors with position, relationship, and sentiment
    </ResponseField>

    <ResponseField name="sources" type="array">
      List of cited sources with URL, domain, position, and isSelf flag
    </ResponseField>

    <ResponseField name="queryFanOuts" type="array">
      Recorded search queries with `id`, `query`, raw `model` ID, and `createdAt`
    </ResponseField>

    <ResponseField name="sentiment" type="number | null">Sentiment of the SELF mention on a 0 to 100 scale, or `null`</ResponseField>
    <ResponseField name="createdAt" type="string">Generation timestamp</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/answers/ANSWER_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "answer": {
    "id": "answer_01",
    "prompt": {
      "id": "prompt_01",
      "text": "Which analytics platforms support warehouse exports?",
      "topic": "Data exports",
      "type": "TOFU"
    },
    "provider": "ChatGPT",
    "model": "GPT-5.4",
    "text": "Acme Analytics and Rival Labs both document warehouse export integrations.",
    "competitors": [
      {
        "name": "Acme Analytics",
        "position": 3,
        "relationship": "SELF",
        "sentiment": 85
      },
      {
        "name": "Rival Labs",
        "position": 1,
        "relationship": "DIRECT",
        "sentiment": 80
      }
    ],
    "sources": [
      {
        "url": "https://publisher.example/warehouse-export-comparison",
        "domain": "publisher.example",
        "position": 1,
        "isSelf": false
      },
      {
        "url": "https://acme.example/integrations",
        "domain": "acme.example",
        "position": 2,
        "isSelf": true
      }
    ],
    "queryFanOuts": [
      {
        "id": "search_01",
        "query": "analytics warehouse export integrations",
        "model": "chatgpt-gpt-5-4",
        "createdAt": "2026-07-19T09:59:58.000Z"
      }
    ],
    "sentiment": 82,
    "createdAt": "2026-07-19T10:00:00.000Z"
  }
}
```

## Errors

| Status | Code               | Description                              |
| ------ | ------------------ | ---------------------------------------- |
| 401    | gateway error      | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`  | Brand doesn't exist or not accessible    |
| 404    | `ANSWER_NOT_FOUND` | Answer doesn't exist                     |
| 429    | gateway error      | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List answers
Source: https://docs.qwairy.co/developers/endpoints/answers/list

GET /api/v1/brands/{brandId}/answers
Retrieve AI-generated responses with filters for provider, brand mentions, and sources.

Returns stored answers for monitored prompts. The list contains a text preview and response-level SELF flags; use [Get Answer](/developers/endpoints/answers/get) for full evidence.

<Note>
  See [Entities](/developers/entities#answer) for the complete Answer object structure, including [CompetitorMention](/developers/entities#competitormention) and [SourceCitation](/developers/entities#sourcecitation) details.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

<ParamField type="boolean">
  Filter by presence of brand mention: `true` or `false`
</ParamField>

<ParamField type="boolean">
  Use `true` to require a SELF citation. The current route accepts `false` but does not apply an inverse filter.
</ParamField>

<ParamField type="number">
  Maximum number of answers to return (max: 100)
</ParamField>

<ParamField type="number">
  Pagination offset
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of answers matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of answers in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="answers" type="array">
  <Expandable title="Answer summary">
    <ResponseField name="id" type="string">Answer ID</ResponseField>
    <ResponseField name="promptId" type="string">Associated prompt ID</ResponseField>
    <ResponseField name="promptText" type="string">Associated prompt text</ResponseField>
    <ResponseField name="provider" type="string">AI provider name</ResponseField>
    <ResponseField name="model" type="string">AI model name</ResponseField>
    <ResponseField name="textPreview" type="string">First 200 characters of the response</ResponseField>
    <ResponseField name="hasSelfMention" type="boolean">Whether brand is mentioned</ResponseField>
    <ResponseField name="selfMentionPosition" type="number">Position in mention list (if mentioned)</ResponseField>
    <ResponseField name="hasSelfSource" type="boolean">Whether brand domain is cited</ResponseField>
    <ResponseField name="competitorsCount" type="number">Number of competitors mentioned</ResponseField>
    <ResponseField name="sourcesCount" type="number">Number of sources cited</ResponseField>
    <ResponseField name="sentiment" type="number | null">SELF mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
    <ResponseField name="createdAt" type="string">Generation timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/answers?hasSelfMention=true&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 312,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "answers": [
    {
      "id": "answer_01",
      "promptId": "prompt_01",
      "promptText": "Which analytics platforms support warehouse exports?",
      "provider": "ChatGPT",
      "model": "GPT-5.4",
      "textPreview": "Acme Analytics and Rival Labs both document warehouse export integrations...",
      "hasSelfMention": true,
      "selfMentionPosition": 3,
      "hasSelfSource": false,
      "competitorsCount": 5,
      "sourcesCount": 3,
      "sentiment": 82,
      "createdAt": "2026-07-19T10:00:00.000Z"
    }
  ]
}
```

## Filtering examples

### Find answers with a SELF mention

```bash theme={null}
GET /api/v1/brands/{brandId}/answers?hasSelfMention=true
```

### Find answers with a SELF citation

```bash theme={null}
GET /api/v1/brands/{brandId}/answers?hasSelfSource=true
```

### Combine filters

```bash theme={null}
# Answers with a SELF mention from the ChatGPT provider
GET /api/v1/brands/{brandId}/answers?provider=openai&hasSelfMention=true
```

The endpoint does not currently support an inverse SELF-citation filter. To find answers that mention the brand without a SELF citation, request `hasSelfMention=true` and filter the returned `hasSelfSource` field in your client.

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Invalid query parameter                  |
| `401`  | Missing or invalid API token             |
| `404`  | Brand not found or inaccessible          |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get brand
Source: https://docs.qwairy.co/developers/endpoints/brands/get

GET /api/v1/brands/{brandId}
Retrieve detailed information about a specific brand.

Retrieve one accessible brand and current counts for non-deleted prompts, non-deleted answers, and SELF or DIRECT competitor domains.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique brand identifier
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand details">
    <ResponseField name="id" type="string">
      Opaque brand identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Brand display name
    </ResponseField>

    <ResponseField name="domain" type="string">
      Primary domain for the brand
    </ResponseField>

    <ResponseField name="description" type="string">
      Brand description (can be null)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp
    </ResponseField>

    <ResponseField name="stats" type="object">
      <Expandable title="Brand statistics">
        <ResponseField name="promptsCount" type="number">
          Number of prompts tracked for this brand
        </ResponseField>

        <ResponseField name="answersCount" type="number">
          Number of non-deleted stored answers
        </ResponseField>

        <ResponseField name="competitorsCount" type="number">
          Number of competitors (SELF + DIRECT)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics",
    "domain": "acme.example",
    "description": "Analytics software for operations teams.",
    "createdAt": "2026-07-15T10:30:00.000Z",
    "stats": {
      "promptsCount": 156,
      "answersCount": 312,
      "competitorsCount": 8
    }
  }
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| 401    | gateway error     | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible    |
| 429    | gateway error     | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List brands
Source: https://docs.qwairy.co/developers/endpoints/brands/list

GET /api/v1/brands
Retrieve all brands accessible to your team.

Returns the authenticated team's `LIVE` brands whose transfer status is `NONE`, ordered by name.

<Note>
  See [Entities](/developers/entities#brand) for the complete Brand object structure.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="total" type="number">
  Total number of brands
</ResponseField>

<ResponseField name="brands" type="array">
  <Expandable title="Brand object">
    <ResponseField name="id" type="string">
      Opaque brand identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Brand display name
    </ResponseField>

    <ResponseField name="domain" type="string">
      Primary domain for the brand
    </ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "total": 2,
  "brands": [
    {
      "id": "brand_01",
      "name": "Acme Analytics",
      "domain": "acme.example"
    },
    {
      "id": "brand_02",
      "name": "Northstar Data",
      "domain": "northstar.example"
    }
  ]
}
```

## Next steps

Once you have your brand IDs, you can:

* [Get performance metrics](/developers/endpoints/performance)
* [List competitors](/developers/endpoints/competitors/list)
* [View source domains](/developers/endpoints/source-domains/list)
* [View source URLs](/developers/endpoints/source-urls)
* [Browse prompts](/developers/endpoints/prompts/list)

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Competitor evolution
Source: https://docs.qwairy.co/developers/endpoints/competitors/evolution

GET /api/v1/brands/{brandId}/competitors/{competitorId}/evolution
Track how a competitor's metrics change over time.

Returns daily mention occurrences, SELF-and-DIRECT Share of Voice, average position, and average mention sentiment for one competitor.

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the competitor
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors/COMPETITOR_ID/evolution?period=7" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "competitor": {
    "id": "competitor_01",
    "name": "Rival Labs",
    "relationship": "DIRECT"
  },
  "evolution": [
    {
      "date": "2026-07-01",
      "mentions": 5,
      "shareOfVoice": 7.2,
      "avgPosition": 2.3,
      "avgSentiment": 76.5
    },
    {
      "date": "2026-07-02",
      "mentions": 8,
      "shareOfVoice": 8.5,
      "avgPosition": 2.1,
      "avgSentiment": 78.2
    }
  ]
}
```

## Errors

| Status | Code                   | Description                              |
| ------ | ---------------------- | ---------------------------------------- |
| 401    | gateway error          | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`      | Brand doesn't exist or not accessible    |
| 404    | `COMPETITOR_NOT_FOUND` | Competitor doesn't exist                 |
| 429    | gateway error          | Rate limit exceeded; honor `Retry-After` |

`avgSentiment` uses the 0 to 100 mention-sentiment scale and can be `null`. See [Rate limits](/developers/rate-limits) for retry behavior.


# Get competitor
Source: https://docs.qwairy.co/developers/endpoints/competitors/get

GET /api/v1/brands/{brandId}/competitors/{competitorId}
Retrieve detailed competitor info with breakdowns by provider and topic.

Returns one competitor's metrics for the selected answer scope. Share of Voice divides this competitor's mention occurrences by SELF and DIRECT mention occurrences in that scope.

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the competitor
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors/COMPETITOR_ID?period=30" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "competitor": {
    "id": "competitor_01",
    "name": "Rival Labs",
    "domain": "rival.example",
    "relationship": "DIRECT",
    "totalMentions": 104,
    "shareOfVoice": 8.13,
    "avgPosition": 2.1,
    "avgSentiment": 78.1,
    "byProvider": [
      { "provider": "ChatGPT", "mentions": 62, "avgPosition": 2.0 },
      { "provider": "Perplexity", "mentions": 42, "avgPosition": 2.3 }
    ],
    "byTopic": [
      { "topic": "Product Reviews", "mentions": 45 },
      { "topic": "Comparisons", "mentions": 38 }
    ]
  }
}
```

`avgSentiment` is the average sentiment for this competitor's mentions on a 0 to 100 scale, or `null`. `byProvider` groups stored model IDs under their provider display name.

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `404`  | Brand or competitor not found            |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List competitors
Source: https://docs.qwairy.co/developers/endpoints/competitors/list

GET /api/v1/brands/{brandId}/competitors
Track competitor mentions, share of voice, and positioning.

Lists competitor domains and mention metrics for the selected scope. The default relationship set is `SELF,DIRECT`; include `INDIRECT` explicitly when needed. On this endpoint, Share of Voice uses mention occurrences from the selected relationship set.

<Note>
  See [Entities](/developers/entities#competitor) for the complete Competitor object structure.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

<ParamField type="string">
  Filter by relationship type. Supports comma-separated multi-select: `SELF`, `DIRECT`, `INDIRECT`. Default: `SELF,DIRECT`.
</ParamField>

<ParamField type="number">
  Maximum number of results to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `mentions`, `position`, `sentiment`, `shareOfVoice`, `name`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

Returns competitors from the requested relationship filter. `INDIRECT` is excluded only by the default filter.

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of competitors matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of competitors in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="competitors" type="array">
  <Expandable title="Competitor object">
    <ResponseField name="id" type="string">Competitor ID</ResponseField>
    <ResponseField name="name" type="string">Competitor name</ResponseField>
    <ResponseField name="domain" type="string">Competitor domain</ResponseField>

    <ResponseField name="relationship" type="string">
      `SELF`, `DIRECT`, or `INDIRECT`, subject to the `relationship` filter
    </ResponseField>

    <ResponseField name="totalMentions" type="number">Total mentions count</ResponseField>
    <ResponseField name="shareOfVoice" type="number">This row's mention occurrences divided by all mention occurrences in the selected relationship set</ResponseField>
    <ResponseField name="avgPosition" type="number">Average position in responses</ResponseField>
    <ResponseField name="avgSentiment" type="number | null">Average mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors?limit=10&offset=0" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 10,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "competitors": [
    {
      "id": "competitor_self",
      "name": "Acme Analytics",
      "domain": "acme.example",
      "relationship": "SELF",
      "totalMentions": 104,
      "shareOfVoice": 8.13,
      "avgPosition": 2.1,
      "avgSentiment": 78.1
    },
    {
      "id": "competitor_01",
      "name": "Rival Labs",
      "domain": "rival.example",
      "relationship": "DIRECT",
      "totalMentions": 111,
      "shareOfVoice": 8.73,
      "avgPosition": 1.8,
      "avgSentiment": 75.2
    }
  ]
}
```

## Errors

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `400`  | Invalid query parameter or relationship filter |
| `401`  | Missing or invalid API token                   |
| `404`  | Brand not found or inaccessible                |
| `429`  | Rate limit exceeded; honor `Retry-After`       |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get content
Source: https://docs.qwairy.co/developers/endpoints/content/get

GET /api/v1/brands/{brandId}/content/{articleId}
Retrieve a full Content Studio article including the markdown body.

Returns one Content Studio article with its Markdown `content`, outline, metadata, and sources.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the article
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  `id`, `name`, `domain`
</ResponseField>

<ResponseField name="article" type="object">
  <Expandable title="Article">
    <ResponseField name="id" type="string">Article ID</ResponseField>
    <ResponseField name="title" type="string">Article title</ResponseField>
    <ResponseField name="slug" type="string">URL slug or `null`</ResponseField>
    <ResponseField name="description" type="string">Short description or `null`</ResponseField>
    <ResponseField name="content" type="string">Full article body in **Markdown**</ResponseField>
    <ResponseField name="articleType" type="string">Article type</ResponseField>
    <ResponseField name="status" type="string">`DRAFT`, `GENERATING`, `LIVE` or `ARCHIVED`</ResponseField>
    <ResponseField name="targetLength" type="number">Target word count used for generation</ResponseField>
    <ResponseField name="wordCount" type="number">Actual word count</ResponseField>
    <ResponseField name="guidelines" type="string">Generation guidelines or `null`</ResponseField>
    <ResponseField name="includeTldr" type="boolean">Whether a TL;DR was requested</ResponseField>
    <ResponseField name="includeFaq" type="boolean">Whether an FAQ was requested</ResponseField>
    <ResponseField name="metaData" type="object">SEO/initialization metadata (JSON) or `null`</ResponseField>
    <ResponseField name="outline" type="object">Structured outline with `sections` or `null`</ResponseField>
    <ResponseField name="finalUrl" type="string">Published URL (if set by you) or `null`</ResponseField>
    <ResponseField name="publishedAt" type="string">Publish timestamp (ISO 8601) or `null`</ResponseField>
    <ResponseField name="generatedAt" type="string">Content generation timestamp (ISO 8601) or `null`</ResponseField>
    <ResponseField name="createdAt" type="string">Creation timestamp (ISO 8601)</ResponseField>
    <ResponseField name="updatedAt" type="string">Last update timestamp (ISO 8601)</ResponseField>

    <ResponseField name="sources" type="array">
      Sources used for the article. Each object has `id`, `title`, `url`, `usageType`, `order`.
    </ResponseField>
  </Expandable>
</ResponseField>

A `404 RESOURCE_NOT_FOUND` is returned if the article does not exist or does not belong to the brand.

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/content/ARTICLE_ID" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics",
    "domain": "acme.example"
  },
  "article": {
    "id": "art_abc123",
    "title": "How to choose the right solution in 2026",
    "slug": "how-to-choose-the-right-solution-2026",
    "description": "A practical buyer's guide.",
    "content": "# How to choose the right solution in 2026\n\n## Introduction\n\n...",
    "articleType": "HOW_TO",
    "status": "LIVE",
    "targetLength": 1500,
    "wordCount": 1480,
    "guidelines": null,
    "includeTldr": true,
    "includeFaq": false,
    "metaData": {
      "seo": {
        "metaTitle": "How to choose the right solution (2026 guide)",
        "metaDescription": "A practical buyer's guide for 2026."
      }
    },
    "outline": {
      "sections": [
        { "id": "s1", "level": 2, "title": "Introduction", "order": 0 }
      ],
      "generatedAt": "2026-05-08T14:20:00.000Z"
    },
    "finalUrl": "https://acme.example/blog/how-to-choose",
    "publishedAt": "2026-05-10T09:00:00.000Z",
    "generatedAt": "2026-05-08T14:22:00.000Z",
    "createdAt": "2026-05-08T13:50:00.000Z",
    "updatedAt": "2026-05-10T09:00:00.000Z",
    "sources": [
      {
        "id": "src_1",
        "title": "Industry benchmark report",
        "url": "https://research.example/benchmark",
        "usageType": "AUTO",
        "order": 0
      }
    ]
  }
}
```

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `404`  | Brand or article not found               |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List content
Source: https://docs.qwairy.co/developers/endpoints/content/list

GET /api/v1/brands/{brandId}/content
List Content Studio articles for syndication to an external CMS.

Lists Content Studio article metadata for read-only integrations. Fetch [article detail](/developers/endpoints/content/get) to retrieve the Markdown body.

<Note>
  The route defaults to `status=LIVE`. Pass `status` explicitly to list another lifecycle state.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="string">
  Filter by status: `DRAFT`, `GENERATING`, `LIVE`, `ARCHIVED`
</ParamField>

<ParamField type="string">
  Filter by type: `INFORMATIONAL`, `COMPARISON`, `HOW_TO`, `LISTICLE`, `REVIEW`, `CASE_STUDY`, `NEWS`, `OPINION`, `OTHER`
</ParamField>

<ParamField type="number">
  Maximum number of articles to return (max: 100)
</ParamField>

<ParamField type="number">
  Pagination offset
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`, `updatedAt`, `publishedAt`, `title`, `wordCount`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of articles matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of articles in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="articles" type="array">
  <Expandable title="Article object">
    <ResponseField name="id" type="string">Article ID (use with the detail endpoint)</ResponseField>
    <ResponseField name="title" type="string">Article title</ResponseField>
    <ResponseField name="slug" type="string">URL slug or `null`</ResponseField>
    <ResponseField name="description" type="string">Short description or `null`</ResponseField>
    <ResponseField name="articleType" type="string">Article type</ResponseField>
    <ResponseField name="status" type="string">`DRAFT`, `GENERATING`, `LIVE` or `ARCHIVED`</ResponseField>
    <ResponseField name="wordCount" type="number">Word count of the generated content</ResponseField>
    <ResponseField name="finalUrl" type="string">Published URL (if set by you) or `null`</ResponseField>
    <ResponseField name="publishedAt" type="string">Publish timestamp (ISO 8601) or `null`</ResponseField>
    <ResponseField name="generatedAt" type="string">Content generation timestamp (ISO 8601) or `null`</ResponseField>
    <ResponseField name="createdAt" type="string">Creation timestamp (ISO 8601)</ResponseField>
    <ResponseField name="updatedAt" type="string">Last update timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/content?status=LIVE&limit=20" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 12,
    "count": 1,
    "limit": 20,
    "offset": 0
  },
  "articles": [
    {
      "id": "art_abc123",
      "title": "How to choose the right solution in 2026",
      "slug": "how-to-choose-the-right-solution-2026",
      "description": "A practical buyer's guide.",
      "articleType": "HOW_TO",
      "status": "LIVE",
      "wordCount": 1480,
      "finalUrl": "https://acme.example/blog/how-to-choose",
      "publishedAt": "2026-05-10T09:00:00.000Z",
      "generatedAt": "2026-05-08T14:22:00.000Z",
      "createdAt": "2026-05-08T13:50:00.000Z",
      "updatedAt": "2026-05-10T09:00:00.000Z"
    }
  ]
}
```

## Errors

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `400`  | Invalid status, article type, pagination, or sort parameter |
| `401`  | Missing or invalid API token                                |
| `404`  | Brand not found or inaccessible                             |
| `429`  | Rate limit exceeded; honor `Retry-After`                    |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get crawler analytics
Source: https://docs.qwairy.co/developers/endpoints/crawler-analytics

GET /api/v1/brands/{brandId}/crawler-analytics
Retrieve retained AI crawler activity, delivery coverage, and page-level observations for a brand.

Retrieve AI crawler activity observed through the brand's configured log integration. The endpoint returns daily aggregates and page-level observations. It never returns raw log events or human traffic.

All occurrence totals, crawler breakdowns, and page rankings use the public set of supported observable AI-specific User-Agent identities. The ingestion registry can recognize additional identities for classification and compatibility, but the endpoint excludes them from its public analytics output. Classification matches the received User-Agent token; it does not verify source IP or reverse DNS.

<Note>
  This endpoint requires an active Business, Enterprise, or Agency Business plan, or an explicit Crawler Analytics feature override for the team. Results are observational: check `coverage` before interpreting counts or comparing periods.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  Unique identifier of the brand.
</ParamField>

## Query parameters

<ParamField type="string">
  Inclusive analytic-day preset in the integration's IANA time zone: `24h` is the current analytic day, `7d` is that day plus the preceding six, and `30d` is that day plus the preceding 29. `24h` is not a rolling 24-hour window.
</ParamField>

<ParamField type="string">
  Page-state filter: `all`, `new`, `hot`, or `neglected`.
</ParamField>

<ParamField type="number">
  One-based page number. Maximum: `10000`.
</ParamField>

<ParamField type="number">
  Page size. Maximum: `100`.
</ParamField>

## Page-state semantics

* `new`: the first retained page observation falls within the last 7 days, including the boundary (`firstSeenAt >= now - 7 days`).
* `hot`: the page is in the top decile by supported-crawler occurrences over the current 7 analytic days, has activity on at least 2 of those days, and is not neglected.
* `neglected`: the most recent retained page observation is strictly older than the 30-day boundary.

`new` and `hot` can coexist. `neglected` is exclusive. The hot window is independent of the requested `range`.

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the request succeeded.
</ResponseField>

<ResponseField name="brand" type="object">
  Brand `id`, `name`, and `domain`.
</ResponseField>

<ResponseField name="connected" type="boolean">
  Whether the integration is active, not disabled, and has at least one active non-revoked key.
</ResponseField>

<ResponseField name="lifecycle" type="string | null">
  Current integration lifecycle, or `null` when no integration exists.
</ResponseField>

<ResponseField name="health" type="string | null">
  Current integration health, or `null` when no integration exists.
</ResponseField>

<ResponseField name="range" type="object">
  Requested and effective dates, observed and verified bucket counts, truncation state, and the `asOf` timestamp.
</ResponseField>

<ResponseField name="coverage" type="object">
  <Expandable title="Coverage details">
    <ResponseField name="hasObservations" type="boolean">Whether the selected range contains at least one supported public occurrence.</ResponseField>
    <ResponseField name="dataStatus" type="string">`observed` when supported observations exist without a known gap; `not_measured` when none exist and no gap is known; `incomplete_ingestion` for a quota limit or provider gap, with or without observations.</ResponseField>
    <ResponseField name="ingestCoverageFlags" type="number">Bit flags: `1` delivery unverified, `2` quota limited, and `4` provider gap.</ResponseField>
    <ResponseField name="countPrecision" type="string">`exact`; `at_least_once` when repackaged retries can duplicate observations; or `capped` when a count exceeds safe numeric precision.</ResponseField>
    <ResponseField name="deliveryContinuity" type="string">`verified` when every elapsed bucket is verified; `incomplete` for a known gap or profile change; otherwise `unverified`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="totalOccurrences" type="number | null">
  Observed occurrences from the supported public crawler set in the effective range. A number is returned only when at least one supported public rollup has a positive request count; otherwise the value is `null`, not a measured zero. With incomplete ingestion, a numeric value can still be partial.
</ResponseField>

<ResponseField name="identifiedPageOccurrences" type="number">
  Occurrences associated with a retained page identity.
</ResponseField>

<ResponseField name="redirectOccurrences" type="number">
  Requests that returned a redirect.
</ResponseField>

<ResponseField name="notFoundOccurrences" type="number">
  Requests that returned `404`.
</ResponseField>

<ResponseField name="otherErrorOccurrences" type="number">
  Other observed error responses.
</ResponseField>

<ResponseField name="buckets" type="array">
  Daily totals, crawler breakdowns, error totals, and coverage metadata.
</ResponseField>

<ResponseField name="crawlerStats" type="array">
  Totals by crawler in the supported public set, including its display name, bot type, and error breakdown.
</ResponseField>

<ResponseField name="pages" type="array">
  <Expandable title="Page observation">
    <ResponseField name="pathId" type="string">Stable page identity.</ResponseField>
    <ResponseField name="path" type="string">Observed path or an internal pseudonym.</ResponseField>
    <ResponseField name="isPseudonymized" type="boolean">When `true`, do not reconstruct or link to a URL from `path`.</ResponseField>
    <ResponseField name="firstSeenAt" type="string">First observed timestamp.</ResponseField>
    <ResponseField name="lastSeenAt" type="string">Most recent observed timestamp.</ResponseField>
    <ResponseField name="lifetimeCount" type="number">Retained lifetime occurrence count.</ResponseField>
    <ResponseField name="states" type="array">Computed states. `new` and `hot` can coexist; `neglected` is exclusive.</ResponseField>
    <ResponseField name="occurrences" type="number">Occurrences in the selected range.</ResponseField>
    <ResponseField name="crawlerOccurrences" type="object">Occurrence count keyed by crawler name.</ResponseField>
    <ResponseField name="uniqueCrawlers" type="number">Distinct observed crawlers.</ResponseField>
    <ResponseField name="statusGroups" type="object">HTTP status-group totals.</ResponseField>
    <ResponseField name="crawlerTypes" type="object">Live-search, training, and other crawler totals.</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Page-by-crawler daily rollups retain 30 analytic days. Durable page identities preserve first seen, last seen, and lifetime count beyond that window. Query strings and fragments are removed; sensitive-looking or overlong paths can be replaced with an integration-scoped one-way pseudonym.
</Note>

<ResponseField name="pagination" type="object">
  One-based `page`, `limit`, `totalItems`, `totalPages`, and `hasMore`.
</ResponseField>

<ResponseField name="rawEventsAvailable" type="boolean">
  Always `false`. Raw log events are not exposed by this endpoint.
</ResponseField>

<ResponseField name="humanTrafficIncluded" type="boolean">
  Always `false`.
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/crawler-analytics?range=7d&state=hot&limit=25" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Interpret missing or incomplete data

* Treat `totalOccurrences: null` as not measured. Do not convert it to zero.
* Check `coverage.dataStatus`, `countPrecision`, and `deliveryContinuity` before comparing periods.
* Use `range.startDate` and `range.endDate` for the effective comparison window.
* Do not build a public URL from a page where `isPseudonymized` is `true`.

## Errors

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Invalid range, state, or pagination value                                               |
| `401`  | Missing or invalid API token                                                            |
| `403`  | The team has neither an eligible active plan nor an explicit Crawler Analytics override |
| `404`  | Brand not found or not accessible to the token's team                                   |
| `429`  | Rate limit exceeded; honor `Retry-After`                                                |

See [Crawler Analytics](/documentation/measure/crawler-analytics) for setup and the product interface, and [Rate limits](/developers/rate-limits) for retry behavior.


# Topic evolution
Source: https://docs.qwairy.co/developers/endpoints/keywords/evolution

GET /api/v1/brands/{brandId}/keywords/{keywordId}/evolution
Daily time-series metrics for a specific topic.

Returns daily response-level metrics for one topic. Mention Rate and Source Rate use eligible SELF-or-DIRECT answer denominators; Share of Voice uses mention occurrences.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the topic
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="keyword" type="object">
  <Expandable title="Topic info">
    <ResponseField name="id" type="string">Topic ID</ResponseField>
    <ResponseField name="text" type="string">Topic text</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="evolution" type="array">
  <Expandable title="Daily metrics">
    <ResponseField name="date" type="string">Date (YYYY-MM-DD format)</ResponseField>
    <ResponseField name="answers" type="number">Stored answers on this date</ResponseField>
    <ResponseField name="mentionRate" type="number">Answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>
    <ResponseField name="shareOfVoice" type="number">SELF mention occurrences divided by SELF and DIRECT mention occurrences</ResponseField>
    <ResponseField name="avgSentiment" type="number | null">Average SELF mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
    <ResponseField name="sourceRate" type="number">Answers with a SELF citation divided by answers with a SELF or DIRECT citation</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/keywords/TOPIC_ID/evolution?period=30" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "keyword": {
    "id": "topic_01",
    "text": "data exports"
  },
  "evolution": [
    {
      "date": "2026-02-15",
      "answers": 42,
      "mentionRate": 65.2,
      "shareOfVoice": 48.3,
      "avgSentiment": 72.1,
      "sourceRate": 55.0
    },
    {
      "date": "2026-02-16",
      "answers": 38,
      "mentionRate": 60.5,
      "shareOfVoice": 45.1,
      "avgSentiment": 74.2,
      "sourceRate": 52.6
    }
  ]
}
```

## Errors

| Status | Code                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| 401    | gateway error       | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible    |
| 404    | `KEYWORD_NOT_FOUND` | Topic doesn't exist or not accessible    |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List topics
Source: https://docs.qwairy.co/developers/endpoints/keywords/list

GET /api/v1/brands/{brandId}/keywords
Analyze performance by topic (keyword).

Lists topics with answer counts and response-level SELF metrics for the selected scope. The API route retains `keywords` and `keyword` field names for compatibility.

<Note>
  See [Entities](/developers/entities#keyword) for the complete Topic object structure.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="number">
  Maximum number of topics to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `prompts`, `answers`, `mentionRate`, `shareOfVoice`, `sentiment`, `keyword`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of topics matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of topics in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="keywords" type="array">
  <Expandable title="Topic object">
    <ResponseField name="id" type="string">Topic ID</ResponseField>
    <ResponseField name="keyword" type="string">Topic text</ResponseField>
    <ResponseField name="totalPrompts" type="number">Number of prompts with this topic</ResponseField>
    <ResponseField name="totalAnswers" type="number">Stored answers in the selected scope</ResponseField>
    <ResponseField name="brandMentionRate" type="number">Answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>
    <ResponseField name="shareOfVoice" type="number">SELF mention occurrences divided by SELF and DIRECT mention occurrences</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average SELF mention sentiment on a 0 to 100 scale; `0` is returned when no scored SELF mention exists</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/keywords?limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 25,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "keywords": [
    {
      "id": "topic_01",
      "keyword": "data exports",
      "totalPrompts": 15,
      "totalAnswers": 120,
      "brandMentionRate": 45.5,
      "shareOfVoice": 32.1,
      "avgSentiment": 78.3
    },
    {
      "id": "topic_02",
      "keyword": "analytics integrations",
      "totalPrompts": 8,
      "totalAnswers": 64,
      "brandMentionRate": 28.1,
      "shareOfVoice": 18.5,
      "avgSentiment": 72.0
    }
  ]
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| 401    | gateway error     | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible    |
| 429    | gateway error     | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List local business insights
Source: https://docs.qwairy.co/developers/endpoints/local

GET /api/v1/brands/{brandId}/local
List local business observations extracted from stored answers.

Returns local business observations extracted from stored answers. Each record is an observation, not a verified recommendation or current business listing.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/local
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by one or more provider aliases or model IDs, separated by commas.
</ParamField>

<ParamField type="string">
  Filter by business category (case-insensitive partial match)
</ParamField>

<ParamField type="number">
  Maximum number of businesses to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`, `rating`, `reviewCount`, `position`, `businessName`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of businesses matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of businesses in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="local" type="array">
  <Expandable title="Local business object">
    <ResponseField name="id" type="string">Local insight ID</ResponseField>
    <ResponseField name="businessName" type="string">Business name</ResponseField>
    <ResponseField name="category" type="string">Business category</ResponseField>
    <ResponseField name="address" type="string">Business address</ResponseField>
    <ResponseField name="websiteUrl" type="string">Business website URL</ResponseField>
    <ResponseField name="position" type="number">Position in the list (1 = top result)</ResponseField>
    <ResponseField name="rating" type="number">Business rating (0-5)</ResponseField>
    <ResponseField name="reviewCount" type="number">Number of reviews</ResponseField>
    <ResponseField name="prompt" type="string">Prompt associated with the stored observation</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/local?category=restaurant&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 42,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "local": [
    {
      "id": "loc1",
      "businessName": "Northstar Café",
      "category": "Café",
      "address": "10 Example Street, Paris",
      "websiteUrl": "https://cafe.northstar.example",
      "position": 1,
      "rating": 4.8,
      "reviewCount": 2500,
      "prompt": "Which cafés are mentioned near the example district?",
      "createdAt": "2026-07-15T10:30:00Z"
    },
    {
      "id": "loc2",
      "businessName": "Orbit Bistro",
      "category": "Restaurant",
      "address": "20 Example Avenue, Paris",
      "websiteUrl": "https://bistro.orbit.example",
      "position": 2,
      "rating": 4.5,
      "reviewCount": 1800,
      "prompt": "Which cafés are mentioned near the example district?",
      "createdAt": "2026-07-15T10:30:00Z"
    }
  ]
}
```

## Errors

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid filter, pagination, or sort value |
| 401    | gateway error       | Authentication failed                     |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`  |


# Get GEO matrix
Source: https://docs.qwairy.co/developers/endpoints/matrix

GET /api/v1/brands/{brandId}/matrix
Get the GEO visibility matrix for your brand across providers and dimensions.

Returns rows grouped by topic, tag, prompt, or funnel stage and columns grouped by provider. Each cell contains the current Matrix scoring output for its answer scope.

<Note>
  This endpoint returns a cross-tabulation of your brand's visibility. See [Performance](/developers/endpoints/performance) for aggregated metrics and [Competitor](/developers/entities#competitor) for entity structures used in `topCompetitors`.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/matrix
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="string">
  Group rows by: `topics` (default), `tags`, `prompts`, or `funnel`
</ParamField>

<ParamField type="number">
  Number of days to include. Default: 30
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="number">
  Max rows to return. Default: 50, max: 100
</ParamField>

### Granularity options

| Value     | Groups rows by                 |
| --------- | ------------------------------ |
| `topics`  | Keywords/topics (default)      |
| `tags`    | Tags applied to prompts        |
| `prompts` | Individual monitored questions |
| `funnel`  | Funnel stages (TOFU/MOFU/BOFU) |

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand info">
    <ResponseField name="id" type="string">Brand ID</ResponseField>
    <ResponseField name="name" type="string">Brand name</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="granularity" type="string">
  The granularity used for this matrix (`topics`, `tags`, `prompts`, or `funnel`)
</ResponseField>

<ResponseField name="providers" type="array">
  List of AI providers used as columns. Each entry is an object with an `id` and a `name`.

  <Expandable title="Provider object">
    <ResponseField name="id" type="string">Provider ID (e.g., `chatgpt`, `perplexity`, `claude`)</ResponseField>
    <ResponseField name="name" type="string">Display name of the provider</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rows" type="array">
  Matrix rows, one per topic/tag/prompt/funnel stage

  <Expandable title="Row structure">
    <ResponseField name="id" type="string">Row identifier (topic ID, tag ID, prompt ID, or funnel stage)</ResponseField>
    <ResponseField name="name" type="string">Display name of the row</ResponseField>
    <ResponseField name="promptCount" type="number">Number of distinct prompts in this row</ResponseField>
    <ResponseField name="mentionRate" type="number">Pooled row-level Mention Rate: answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>

    <ResponseField name="coverage" type="object">
      Provider-column coverage for this row. A provider counts when its cell has a non-zero SELF Mention Rate or SELF Citation Rate. This is not response-level or prompt-level Coverage.

      <Expandable title="Coverage object">
        <ResponseField name="count" type="number">Provider cells with a non-zero SELF Mention Rate or Citation Rate</ResponseField>
        <ResponseField name="total" type="number">Provider columns in the selected matrix</ResponseField>
        <ResponseField name="percentage" type="number">`count / total × 100`, rounded to an integer</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="overall" type="object">
      Pooled `score`, `subScores`, `answerCount`, and brand `ranking` across every selected provider in the row
    </ResponseField>

    <ResponseField name="cells" type="array">
      One cell per provider

      <Expandable title="Cell structure">
        <ResponseField name="provider" type="string">Provider ID</ResponseField>
        <ResponseField name="score" type="number">Composite GEO score (0-100)</ResponseField>

        <ResponseField name="subScores" type="object">
          <Expandable title="Sub-scores breakdown">
            <ResponseField name="mentionRate" type="number">Brand mention rate (%)</ResponseField>
            <ResponseField name="shareOfVoice" type="number">Share of voice (%)</ResponseField>
            <ResponseField name="citationRate" type="number">Source citation rate (%)</ResponseField>
            <ResponseField name="sentiment" type="number | null">Average SELF mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="ranking" type="object">
          <Expandable title="Ranking per metric">
            <ResponseField name="mentionRate" type="object">Rank and total (e.g., `{"rank": 2, "total": 8}`)</ResponseField>
            <ResponseField name="shareOfVoice" type="object">Rank and total</ResponseField>
            <ResponseField name="citationRate" type="object">Rank and total</ResponseField>
            <ResponseField name="sentiment" type="object">Rank and total</ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="citations" type="number">SELF source-mention occurrences in the cell</ResponseField>
        <ResponseField name="position" type="number">Best (minimum) position your brand reaches across this cell's responses (lower is better; `null` if not mentioned)</ResponseField>
        <ResponseField name="topCompetitor" type="string">Name of the leading competitor in this cell (`null` if none)</ResponseField>
        <ResponseField name="topCompetitors" type="array">Top competitors in this cell, each with `name`, `mentions`, `avgPosition`, and `relationship`</ResponseField>
        <ResponseField name="topSources" type="array">Top cited sources in this cell</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="providerAverages" type="array">
  Per-provider average metrics across all returned rows.

  <Expandable title="Provider average object">
    <ResponseField name="provider" type="string">Provider ID</ResponseField>
    <ResponseField name="score" type="number">Average composite GEO score for this provider (0-100)</ResponseField>
    <ResponseField name="mentionRate" type="number">Average mention rate for this provider (%)</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Average share of voice for this provider (%)</ResponseField>
    <ResponseField name="citationRate" type="number">Average citation rate for this provider (%)</ResponseField>
    <ResponseField name="sentiment" type="number | null">Unweighted average of non-null row sentiment values for this provider, rounded to an integer</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  <Expandable title="Summary statistics">
    <ResponseField name="totalRows" type="number">Total number of rows</ResponseField>
    <ResponseField name="averageMentionRate" type="number">Average of non-zero row Mention Rates, rounded to an integer</ResponseField>
    <ResponseField name="topPerforming" type="object">Highest mention-rate row, or `null`. Shape: `{ rowId, rowName, mentionRate }`.</ResponseField>
    <ResponseField name="needsAttention" type="object">API summary field containing the lowest non-zero row below the built-in 50% rule, or `null`. This rule is not an account benchmark.</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/matrix?granularity=topics&period=30&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics"
  },
  "granularity": "topics",
  "providers": [
    { "id": "openai", "name": "ChatGPT" },
    { "id": "perplexity", "name": "Perplexity" },
    { "id": "anthropic", "name": "Claude" }
  ],
  "rows": [
    {
      "id": "topic_01",
      "name": "Data exports",
      "promptCount": 12,
      "mentionRate": 52.4,
      "coverage": { "count": 3, "total": 3, "percentage": 100 },
      "overall": {
        "score": 60,
        "subScores": {
          "mentionRate": 52.4,
          "shareOfVoice": 13.5,
          "citationRate": 29.1,
          "sentiment": 76.3
        },
        "answerCount": 60,
        "ranking": {
          "mentionRate": { "rank": 2, "total": 8 },
          "shareOfVoice": { "rank": 3, "total": 8 },
          "citationRate": { "rank": 2, "total": 8 },
          "sentiment": { "rank": 1, "total": 8 },
          "score": { "rank": 2, "total": 8 }
        }
      },
      "cells": [
        {
          "provider": "openai",
          "score": 72,
          "subScores": {
            "mentionRate": 65.0,
            "shareOfVoice": 18.5,
            "citationRate": 30.2,
            "sentiment": 81.0
          },
          "ranking": {
            "mentionRate": { "rank": 2, "total": 8 },
            "shareOfVoice": { "rank": 3, "total": 8 },
            "citationRate": { "rank": 1, "total": 8 },
            "sentiment": { "rank": 1, "total": 8 }
          },
          "citations": 12,
          "position": 2,
          "topCompetitor": "Rival Labs",
          "topCompetitors": [
            { "name": "Rival Labs", "mentions": 9, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Northstar Data", "mentions": 6, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "publisher.example", "citations": 8 }
          ]
        },
        {
          "provider": "perplexity",
          "score": 58,
          "subScores": {
            "mentionRate": 50.0,
            "shareOfVoice": 12.3,
            "citationRate": 42.1,
            "sentiment": 76.0
          },
          "ranking": {
            "mentionRate": { "rank": 3, "total": 7 },
            "shareOfVoice": { "rank": 4, "total": 7 },
            "citationRate": { "rank": 2, "total": 7 },
            "sentiment": { "rank": 2, "total": 7 }
          },
          "citations": 18,
          "position": 3,
          "topCompetitor": "Northstar Data",
          "topCompetitors": [
            { "name": "Northstar Data", "mentions": 11, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Rival Labs", "mentions": 7, "avgPosition": 4, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "reviews.example", "citations": 14 }
          ]
        },
        {
          "provider": "anthropic",
          "score": 45,
          "subScores": {
            "mentionRate": 35.0,
            "shareOfVoice": 9.8,
            "citationRate": 15.0,
            "sentiment": 72.0
          },
          "ranking": {
            "mentionRate": { "rank": 5, "total": 6 },
            "shareOfVoice": { "rank": 4, "total": 6 },
            "citationRate": { "rank": 3, "total": 6 },
            "sentiment": { "rank": 3, "total": 6 }
          },
          "citations": 4,
          "position": 4,
          "topCompetitor": "Rival Labs",
          "topCompetitors": [
            { "name": "Rival Labs", "mentions": 5, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "acme.example", "citations": 3 }
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    { "provider": "openai", "score": 72, "mentionRate": 65.0, "shareOfVoice": 18.5, "citationRate": 30.2, "sentiment": 81.0 },
    { "provider": "perplexity", "score": 58, "mentionRate": 50.0, "shareOfVoice": 12.3, "citationRate": 42.1, "sentiment": 76.0 },
    { "provider": "anthropic", "score": 45, "mentionRate": 35.0, "shareOfVoice": 9.8, "citationRate": 15.0, "sentiment": 72.0 }
  ],
  "summary": {
    "totalRows": 12,
    "averageMentionRate": 50,
    "topPerforming": {
      "rowId": "topic_01",
      "rowName": "Data exports",
      "mentionRate": 52.4
    },
    "needsAttention": {
      "rowId": "topic7",
      "rowName": "Pricing",
      "mentionRate": 31.0
    }
  }
}
```

## Errors

| Status | Code                | Description                                         |
| ------ | ------------------- | --------------------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid query parameter (e.g., unknown granularity) |
| 401    | gateway error       | Missing or invalid API token                        |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible               |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`            |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get perception snapshot
Source: https://docs.qwairy.co/developers/endpoints/perception/get

GET /api/v1/brands/{brandId}/perception/{snapshotId}
Retrieve one completed perception snapshot with scores, attribute alignment, and SWOT observations.

Returns one completed perception snapshot. Get `snapshotId` from the `history` array returned by [List perception snapshots](/developers/endpoints/perception/list).

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the perception snapshot
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  `id`, `name`, `domain`
</ResponseField>

<ResponseField name="snapshot" type="object">
  <Expandable title="Snapshot">
    <ResponseField name="snapshotId" type="string">Snapshot ID</ResponseField>
    <ResponseField name="month" type="number">Month (1-12)</ResponseField>
    <ResponseField name="year" type="number">Year</ResponseField>
    <ResponseField name="scores" type="object">`sentiment`, `alignment`, `consistency`, `factualAlignment` (0-100 or `null`)</ResponseField>

    <ResponseField name="attributes" type="array">
      Brand attributes evaluated by AI. Each object has `text` (string) and `status` (`aligned`, `partial`, `missing`).
    </ResponseField>

    <ResponseField name="attributeMetrics" type="object">
      Counts: `aligned`, `partial`, `missing`, `total`.
    </ResponseField>

    <ResponseField name="insights" type="object">
      SWOT arrays of strings: `strengths`, `weaknesses`, `opportunities`, `threats`.
    </ResponseField>

    <ResponseField name="providers" type="array">AI providers included in the analysis</ResponseField>
    <ResponseField name="createdAt" type="string">Creation timestamp (ISO 8601)</ResponseField>
    <ResponseField name="completedAt" type="string">Completion timestamp (ISO 8601) or `null`</ResponseField>
  </Expandable>
</ResponseField>

A `404 RESOURCE_NOT_FOUND` is returned if the snapshot does not exist, is not `COMPLETED`, or does not belong to the brand.

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/perception/snap_2026_05" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "Northstar Labs",
    "domain": "northstar.example"
  },
  "snapshot": {
    "snapshotId": "snap_2026_05",
    "month": 5,
    "year": 2026,
    "scores": {
      "sentiment": 78,
      "alignment": 65,
      "consistency": 82,
      "factualAlignment": 71
    },
    "attributes": [
      { "text": "Premium positioning", "status": "aligned" },
      { "text": "Sustainable materials", "status": "partial" },
      { "text": "Made in France", "status": "missing" }
    ],
    "attributeMetrics": {
      "aligned": 1,
      "partial": 1,
      "missing": 1,
      "total": 3
    },
    "insights": {
      "strengths": ["Strong brand recognition in core market"],
      "weaknesses": ["Limited awareness of product range"],
      "opportunities": ["Growing demand in adjacent category"],
      "threats": ["Aggressive competitor messaging"]
    },
    "providers": ["chatgpt", "perplexity"],
    "createdAt": "2026-05-01T03:00:00.000Z",
    "completedAt": "2026-05-03T04:12:00.000Z"
  }
}
```

The SWOT arrays are stored model-generated observations. Treat them as inputs to review, not verified facts or forecasts.

## Errors

| Status | Code                 | Description                                             |
| ------ | -------------------- | ------------------------------------------------------- |
| `401`  | gateway error        | Authentication failed                                   |
| `404`  | `RESOURCE_NOT_FOUND` | Brand or completed snapshot not found or not accessible |
| `429`  | gateway error        | Rate limit exceeded; honor `Retry-After`                |


# List perception snapshots
Source: https://docs.qwairy.co/developers/endpoints/perception/list

GET /api/v1/brands/{brandId}/perception
List completed monthly perception snapshots with scores, trends, averages, and history.

Returns completed perception snapshots stored by month. Each snapshot can contain four `0-100` scores: sentiment, alignment, consistency, and factual alignment. A score can be `null` when it was not calculated.

<Note>
  There is no day-based `period` filter. Use `months` to control the history depth. `nextAnalysisDate` is derived from the latest snapshot month; it is not a delivery guarantee.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of months of history to include (max: 24). Only `COMPLETED` snapshots are returned.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand">
    <ResponseField name="id" type="string">Brand ID</ResponseField>
    <ResponseField name="name" type="string">Brand name</ResponseField>
    <ResponseField name="domain" type="string">Brand domain</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current" type="object">
  Latest completed snapshot, or `null` if none. Contains `snapshotId`, `month`, `year`, `completedAt`, and a `scores` object with `sentiment`, `alignment`, `consistency`, `factualAlignment` (each `0-100` or `null`).
</ResponseField>

<ResponseField name="previous" type="object">
  Previous completed snapshot in the same shape as `current`, or `null`.
</ResponseField>

<ResponseField name="trends" type="object">
  Difference (current − previous) for each score: `sentiment`, `alignment`, `consistency`, `factualAlignment`. A value is `null` when either side is missing.
</ResponseField>

<ResponseField name="averages" type="object">
  Average of each score across the returned history (`null` when no data points).
</ResponseField>

<ResponseField name="history" type="array">
  <Expandable title="History point">
    <ResponseField name="snapshotId" type="string">Snapshot ID (use with the detail endpoint)</ResponseField>
    <ResponseField name="month" type="number">Month (1-12)</ResponseField>
    <ResponseField name="year" type="number">Year</ResponseField>
    <ResponseField name="label" type="string">`MM/YYYY` label</ResponseField>
    <ResponseField name="scores" type="object">`sentiment`, `alignment`, `consistency`, `factualAlignment`</ResponseField>
    <ResponseField name="completedAt" type="string">Completion timestamp (ISO 8601) or `null`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  `months` (requested window) and `dataPoints` (number of snapshots returned).
</ResponseField>

<ResponseField name="nextAnalysisDate" type="string">
  First day of the month after the latest snapshot, or the next calendar month when no snapshot exists. This is a computed ISO 8601 date, not a completion promise.
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/perception?months=6" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "Northstar Labs",
    "domain": "northstar.example"
  },
  "current": {
    "snapshotId": "snap_2026_05",
    "month": 5,
    "year": 2026,
    "scores": {
      "sentiment": 78,
      "alignment": 65,
      "consistency": 82,
      "factualAlignment": 71
    },
    "completedAt": "2026-05-03T04:12:00.000Z"
  },
  "previous": {
    "snapshotId": "snap_2026_04",
    "month": 4,
    "year": 2026,
    "scores": {
      "sentiment": 74,
      "alignment": 61,
      "consistency": 80,
      "factualAlignment": 69
    },
    "completedAt": "2026-04-02T04:09:00.000Z"
  },
  "trends": {
    "sentiment": 4,
    "alignment": 4,
    "consistency": 2,
    "factualAlignment": 2
  },
  "averages": {
    "sentiment": 75.5,
    "alignment": 62.0,
    "consistency": 80.3,
    "factualAlignment": 69.8
  },
  "history": [
    {
      "snapshotId": "snap_2026_04",
      "month": 4,
      "year": 2026,
      "label": "04/2026",
      "scores": {
        "sentiment": 74,
        "alignment": 61,
        "consistency": 80,
        "factualAlignment": 69
      },
      "completedAt": "2026-04-02T04:09:00.000Z"
    },
    {
      "snapshotId": "snap_2026_05",
      "month": 5,
      "year": 2026,
      "label": "05/2026",
      "scores": {
        "sentiment": 78,
        "alignment": 65,
        "consistency": 82,
        "factualAlignment": 71
      },
      "completedAt": "2026-05-03T04:12:00.000Z"
    }
  ],
  "meta": {
    "months": 6,
    "dataPoints": 2
  },
  "nextAnalysisDate": "2026-06-01T00:00:00.000Z"
}
```

## Errors

| Status | Code                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| `400`  | `INVALID_PARAMETER` | Invalid `months` value                   |
| `401`  | gateway error       | Authentication failed                    |
| `404`  | `BRAND_NOT_FOUND`   | Brand not found or not accessible        |
| `429`  | gateway error       | Rate limit exceeded; honor `Retry-After` |


# Get performance snapshot
Source: https://docs.qwairy.co/developers/endpoints/performance

GET /api/v1/brands/{brandId}/performance
Read response-level mention, citation, sentiment, and Share of Voice metrics for a brand.

Returns response-level metrics for the selected answer scope, plus topic, tag, competitor, and source breakdowns.

<Note>
  This endpoint returns aggregated metrics. See [Competitor](/developers/entities#competitor) and [Source](/developers/entities#source) for entity structures used in `topCompetitors` and `topSources`.
</Note>

## Metric formulas

Understanding how metrics are calculated is essential for reproducing results:

| Metric             | Formula                               | Details                                                                                                                                        |
| ------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mention Rate**   | `mentionCount / mentionTotal × 100`   | `mentionCount` is the number of answers with a SELF mention. `mentionTotal` is the number of answers with at least one SELF or DIRECT mention. |
| **Coverage**       | `mentionCount / responsesTotal × 100` | Answer-level coverage: answers with a SELF mention divided by every answer in the selected scope. This is not prompt-level Coverage.           |
| **Source Rate**    | `sourceCount / sourceTotal × 100`     | `sourceCount` is the number of answers with a SELF citation. `sourceTotal` is the number of answers with at least one SELF or DIRECT citation. |
| **Share of Voice** | `sovSelf / sovTotal × 100`            | SELF mention occurrences divided by SELF and DIRECT mention occurrences. INDIRECT mentions are excluded.                                       |

<Warning>
  Mention Rate and Coverage have different denominators. The response exposes `mentionCount`, `mentionTotal`, and `responsesTotal`; it does not expose `sovSelf` or `sovTotal`.
</Warning>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/performance
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include in the snapshot. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<Warning>
  Use one date mode per request. Combining `period` with a complete custom date pair can make the applied filter diverge from the returned `period` metadata.
</Warning>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand info">
    <ResponseField name="id" type="string">Brand ID</ResponseField>
    <ResponseField name="name" type="string">Brand name</ResponseField>
    <ResponseField name="domain" type="string">Primary domain</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="period" type="object">
  <Expandable title="Period info">
    <ResponseField name="start" type="string">Start date (ISO 8601)</ResponseField>
    <ResponseField name="end" type="string">End date (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="methodology" type="object">
  <Expandable title="Methodology details">
    <ResponseField name="promptsCount" type="number">Total prompts analyzed</ResponseField>
    <ResponseField name="providersCount" type="number">Number of AI providers</ResponseField>
    <ResponseField name="providers" type="array">List of provider IDs (e.g., `openai`, `perplexity`)</ResponseField>
    <ResponseField name="responsesTotal" type="number">Stored answers in the selected scope</ResponseField>
    <ResponseField name="responsesWithMentions" type="number">Answers containing at least one SELF or DIRECT mention</ResponseField>
    <ResponseField name="responsesWithSources" type="number">Answers containing at least one SELF or DIRECT citation</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scores" type="object">
  <Expandable title="Performance scores">
    <ResponseField name="mentionRate" type="number">Brand mention rate (%)</ResponseField>
    <ResponseField name="mentionCount" type="number">Number of responses where your brand (SELF) is mentioned</ResponseField>
    <ResponseField name="mentionTotal" type="number">Number of responses containing **at least one SELF or DIRECT competitor mention**. This is the denominator for `mentionRate`: it is NOT the total number of responses. INDIRECT mentions are excluded.</ResponseField>
    <ResponseField name="coverage" type="number">Brand coverage (%). Percentage of all monitored responses where your brand is mentioned. Formula: `mentionCount / responsesTotal × 100`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate (%)</ResponseField>
    <ResponseField name="sourceCount" type="number">Number of distinct answers containing a SELF citation</ResponseField>
    <ResponseField name="sourceTotal" type="number">Number of responses containing **at least one SELF or DIRECT source citation**. This is the denominator for `sourceRate`: it is NOT the total number of responses. INDIRECT sources are excluded.</ResponseField>
    <ResponseField name="sourcePages" type="number">Number of unique URLs from your domain (SELF) cited as sources across all AI responses.</ResponseField>
    <ResponseField name="sentiment" type="number">Average SELF mention sentiment on a 0 to 100 scale; `0` is also returned when no scored SELF mention exists</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice (%). Formula: SELF mentions / (SELF + DIRECT mentions) × 100. INDIRECT mentions are excluded.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topCompetitors" type="array">
  Top competitors by mention count
</ResponseField>

<ResponseField name="topSources" type="array">
  Top sources by citation count
</ResponseField>

<ResponseField name="byTopic" type="array">
  <Expandable title="Topic breakdown object">
    <ResponseField name="id" type="string">Topic ID</ResponseField>
    <ResponseField name="topic" type="string">Topic name</ResponseField>
    <ResponseField name="score" type="number">Composite score (0-100). Formula: `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Mention rate for this topic (%). Formula: `selfMentionAnswers / responsesWithMentions × 100` where `responsesWithMentions` counts answers in this topic with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level `scores.mentionRate`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate for this topic (%). Formula: `selfSourceAnswers / responsesWithSources × 100` where `responsesWithSources` counts answers in this topic with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level `scores.sourceRate` (INDIRECT excluded).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice for this topic (%). Formula: SELF mentions in topic / (SELF + DIRECT mentions in topic) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average sentiment score for brand mentions in this topic (null if no mentions)</ResponseField>
    <ResponseField name="promptsCount" type="number">Number of distinct prompts in this topic</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="byTag" type="array">
  <Expandable title="Tag breakdown object">
    <ResponseField name="id" type="string">Tag ID</ResponseField>
    <ResponseField name="name" type="string">Tag name</ResponseField>
    <ResponseField name="score" type="number">Composite score (0-100). Formula: `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Mention rate for this tag (%). Formula: `selfMentionAnswers / responsesWithMentions × 100` where `responsesWithMentions` counts answers in this tag with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level `scores.mentionRate`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate for this tag (%). Formula: `selfSourceAnswers / responsesWithSources × 100` where `responsesWithSources` counts answers in this tag with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level `scores.sourceRate` (INDIRECT excluded).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice for this tag (%). Formula: SELF mentions in tag / (SELF + DIRECT mentions in tag) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average sentiment score for brand mentions in this tag (null if no mentions)</ResponseField>
    <ResponseField name="promptsCount" type="number">Number of distinct prompts in this tag</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/performance?period=30" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "brand_01",
    "name": "Acme Analytics",
    "domain": "acme.example"
  },
  "period": {
    "start": "2026-07-01",
    "end": "2026-07-31"
  },
  "methodology": {
    "promptsCount": 156,
    "providersCount": 2,
    "providers": ["openai", "perplexity"],
    "responsesTotal": 312,
    "responsesWithMentions": 230,
    "responsesWithSources": 184
  },
  "scores": {
    "mentionRate": 45.2,
    "mentionCount": 104,
    "mentionTotal": 230,
    "coverage": 33.33,
    "sourceRate": 23.9,
    "sourceCount": 44,
    "sourceTotal": 184,
    "sourcePages": 27,
    "sentiment": 78.1,
    "shareOfVoice": 8.13
  },
  "topCompetitors": [
    {
      "id": "competitor_01",
      "name": "Rival Labs",
      "relationship": "DIRECT",
      "mentions": 111,
      "avgPosition": 2.3,
      "avgSentiment": 75.2
    }
  ],
  "topSources": [
    {
      "id": "source_01",
      "domain": "publisher.example",
      "mentions": 102,
      "avgPosition": 3.1,
      "isSelf": false
    }
  ],
  "byTopic": [
    {
      "id": "topic_01",
      "topic": "Data exports",
      "score": 68,
      "mentionRate": 67.50,
      "sourceRate": 28.00,
      "shareOfVoice": 9.44,
      "avgSentiment": 76.3,
      "promptsCount": 12
    }
  ],
  "byTag": [
    {
      "id": "tag_01",
      "name": "comparison",
      "score": 72,
      "mentionRate": 55.00,
      "sourceRate": 30.00,
      "shareOfVoice": 10.25,
      "avgSentiment": 81.5,
      "promptsCount": 8
    }
  ]
}
```

## Errors

| Status | Code                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid query parameter                  |
| 401    | gateway error       | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible    |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get Pitch Audit
Source: https://docs.qwairy.co/developers/endpoints/pitch-audits/get

GET /api/v1/pitch-audits/{auditId}
Read the original prospect report for a Pitch Audit.

Returns the original prospect's read-only Pitch Audit report: profile, prompts, scores, competitors, sources, insights, recommendations, and co-competitors.

<ParamField type="string">
  Bearer API token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  Pitch Audit ID returned by [List Pitch Audits](/developers/endpoints/pitch-audits/list).
</ParamField>

## Query parameters

<ParamField type="boolean">
  Include full AI answer text. Keep the default for a bounded report payload; request answers explicitly when evidence-level analysis is required.
</ParamField>

<ParamField type="boolean">
  Attach the complete `scores` summary to every `coCompetitors` row. Use this expansion to compare all co-competitors in one request.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  `true` when the report was returned.
</ResponseField>

<ResponseField name="team" type="object">
  Agency workspace ID and name.
</ResponseField>

<ResponseField name="audit" type="object">
  <Expandable title="Pitch Audit report">
    <ResponseField name="reportSubject" type="object">The original prospect or competitor represented by this report.</ResponseField>
    <ResponseField name="availableSubjects" type="array">Every subject that can be requested through `subjectId`.</ResponseField>
    <ResponseField name="summary" type="object">Scores, providers, competitor leaderboard, sources, insights, technical readiness, claims, and recommendations.</ResponseField>
    <ResponseField name="answersIncluded" type="boolean">Whether full answer evidence was requested.</ResponseField>
    <ResponseField name="coCompetitorScoresIncluded" type="boolean">Whether every co-competitor row includes its full score summary.</ResponseField>
    <ResponseField name="answerCount" type="number">Number of answers available in the report.</ResponseField>
    <ResponseField name="answers" type="array">Full AI answer evidence. Present only when `includeAnswers=true`.</ResponseField>
    <ResponseField name="coCompetitors" type="array">Brands appearing in the same answers as the current subject. Every row includes a resolvable `subjectId`, `reportUrl`, co-occurrence metrics, and optionally `scores`.</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request for the original prospect

```bash theme={null}
curl "https://www.qwairy.co/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Follow a co-competitor link

Take `subjectId` and the canonical `reportUrl` directly from a `coCompetitors` row:

```json theme={null}
{
  "id": "orbit.example",
  "subjectId": "orbit.example",
  "name": "Orbit Systems",
  "sharedAnswers": 12,
  "subjectAvgPosition": 2.1,
  "competitorAvgPosition": 1.7,
  "sharedSourcesCount": 9,
  "reportUrl": "/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/orbit.example"
}
```

Follow `reportUrl`, or see [Get Pitch Audit Subject Report](/developers/endpoints/pitch-audits/get-report). A co-competitor is a derived view of the same audit, not a separate audit record.

## Include every co-competitor score

```bash theme={null}
curl "https://www.qwairy.co/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8?includeCoCompetitorScores=true" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

Read `audit.coCompetitors`. Each row includes the relationship metrics plus `scores.geoScore`, `scores.mentionRate`, `scores.avgPosition`, `scores.sentimentScore`, `scores.shareOfVoice`, and citation metrics. Use `subjectId` only when you need the full derived report.

## Errors

| Status | Code                    | Description                                  |
| ------ | ----------------------- | -------------------------------------------- |
| 400    | `INVALID_PARAMETER`     | Invalid query parameter                      |
| 401    | gateway error           | Authentication failed                        |
| 404    | `PITCH_AUDIT_NOT_FOUND` | Audit or requested subject is not accessible |
| 429    | gateway error           | Rate limit exceeded; honor `Retry-After`     |


# Get Pitch Audit subject report
Source: https://docs.qwairy.co/developers/endpoints/pitch-audits/get-report

GET /api/v1/pitch-audits/{auditId}/reports/{subjectId}
Read a competitor or co-competitor view derived from one Pitch Audit.

A subject report pivots the same Pitch Audit evidence around one detected competitor or co-competitor. It does not create a second audit or regenerate any data.

<ParamField type="string">
  Bearer API token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  Parent Pitch Audit ID.
</ParamField>

<ParamField type="string">
  Value returned by `competitors[].subjectId`, `availableSubjects[].id`, or `coCompetitors[].subjectId`.
</ParamField>

## Query parameters

<ParamField type="boolean">
  Include full AI answer text. The bounded report summary is returned by default.
</ParamField>

<ParamField type="boolean">
  Attach full score summaries to all co-competitors of the selected subject.
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/orbit.example" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

To include answer evidence:

```bash theme={null}
curl "https://www.qwairy.co/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/orbit.example?includeAnswers=true" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

The response uses the same report schema as [Get Pitch Audit](/developers/endpoints/pitch-audits/get). Its `reportSubject` identifies the selected competitor, and its `coCompetitors` rows link to other resolvable subjects. Follow the original prospect row's `reportUrl` to return to the base report.

## Errors

| Status | Code                    | Description                                  |
| ------ | ----------------------- | -------------------------------------------- |
| 400    | `INVALID_PARAMETER`     | Invalid query or subject parameter           |
| 401    | gateway error           | Authentication failed                        |
| 404    | `PITCH_AUDIT_NOT_FOUND` | Audit or requested subject is not accessible |
| 429    | gateway error           | Rate limit exceeded; honor `Retry-After`     |


# List Pitch Audits
Source: https://docs.qwairy.co/developers/endpoints/pitch-audits/list

GET /api/v1/pitch-audits
List the read-only Pitch Audit snapshots available to your agency workspace.

Returns Pitch Audits created by the agency workspace attached to the API token. This endpoint is read-only and never starts, retries, or modifies an audit.

<Note>
  Only Pitch Audits owned by an agency workspace associated with the token's team are returned. General API access still follows the plan rules in [Introduction](/developers/introduction).
</Note>

<ParamField type="string">
  Bearer API token. Example: `Bearer qw-api-xxx`
</ParamField>

## Query parameters

<ParamField type="string">
  Filter by `PENDING`, `RUNNING`, `RECOVERING`, `AWAITING_PROMPTS`, `COMPLETED`, or `FAILED`.
</ParamField>

<ParamField type="number">
  Number of audits to return. Maximum: 100.
</ParamField>

<ParamField type="number">
  Number of audits to skip.
</ParamField>

## Response

<ResponseField name="pagination" type="object">
  Total, count, limit, and offset for the current page.
</ResponseField>

<ResponseField name="audits" type="array">
  <Expandable title="Pitch Audit summary">
    <ResponseField name="id" type="string">Pitch Audit ID.</ResponseField>
    <ResponseField name="brandName" type="string">Prospect name.</ResponseField>
    <ResponseField name="domain" type="string">Prospect domain.</ResponseField>
    <ResponseField name="status" type="string">Current audit status.</ResponseField>
    <ResponseField name="scores" type="object">GEO score, mention rate, position, sentiment, share of voice, citations, and totals when available.</ResponseField>
    <ResponseField name="competitors" type="array">Detected competitors. Each row includes a `subjectId` accepted by the detail endpoint.</ResponseField>
    <ResponseField name="reportReady" type="boolean">Whether the completed report is ready to read.</ResponseField>
    <ResponseField name="team" type="object">Agency workspace ID and name.</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/pitch-audits?status=COMPLETED&limit=20" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": { "total": 8, "count": 1, "limit": 20, "offset": 0 },
  "audits": [
    {
      "id": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
      "brandName": "Northstar Labs",
      "domain": "northstar.example",
      "status": "COMPLETED",
      "promptCount": 20,
      "competitorCount": 4,
      "scores": { "geoScore": 71, "mentionRate": 60 },
      "competitors": [
        {
          "subjectId": "orbit.example",
          "name": "Orbit Systems",
          "domain": "orbit.example",
          "score": 64
        }
      ],
      "reportReady": true,
      "team": { "id": "team-123", "name": "Agency workspace" }
    }
  ]
}
```

## Next step

Use the returned audit ID with [Get Pitch Audit](/developers/endpoints/pitch-audits/get). Use a competitor `subjectId` with [Get Pitch Audit Subject Report](/developers/endpoints/pitch-audits/get-report).

## Errors

| Status | Code                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| `400`  | `INVALID_PARAMETER` | Invalid status or pagination value       |
| `401`  | gateway error       | Authentication failed                    |
| `429`  | gateway error       | Rate limit exceeded; honor `Retry-After` |


# Prompt answers
Source: https://docs.qwairy.co/developers/endpoints/prompts/answers

GET /api/v1/brands/{brandId}/prompts/{promptId}/answers
Retrieve all AI-generated responses for a specific prompt.

Returns all stored answers for one prompt, optionally filtered by provider. This endpoint is not paginated.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the prompt
</ParamField>

## Query parameters

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/prompts/PROMPT_ID/answers" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "prompt": {
    "id": "prompt_01",
    "text": "Which analytics platforms support warehouse exports?"
  },
  "total": 2,
  "answers": [
    {
      "id": "answer_01",
      "provider": "ChatGPT",
      "model": "GPT-5.4",
      "text": "Acme Analytics and Rival Labs document warehouse export integrations.",
      "hasSelfMention": true,
      "selfMentionPosition": 3,
      "hasSelfSource": false,
      "competitorsMentioned": ["Acme Analytics", "Rival Labs"],
      "sourcesCited": ["publisher.example", "reviews.example"],
      "sentiment": 82,
      "createdAt": "2026-07-19T10:00:00.000Z"
    },
    {
      "id": "answer_02",
      "provider": "Perplexity",
      "model": "Perplexity Sonar",
      "text": "The cited documentation lists supported export destinations.",
      "hasSelfMention": true,
      "selfMentionPosition": 2,
      "hasSelfSource": true,
      "competitorsMentioned": ["Acme Analytics", "Northstar Data"],
      "sourcesCited": ["acme.example", "docs.example"],
      "sentiment": 78,
      "createdAt": "2026-07-19T10:05:00.000Z"
    }
  ]
}
```

`sentiment` is the SELF mention sentiment on a 0 to 100 scale, or `null`.

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `404`  | Brand or prompt not found                |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Prompt evolution
Source: https://docs.qwairy.co/developers/endpoints/prompts/evolution

GET /api/v1/brands/{brandId}/prompts/{promptId}/evolution
Track how a prompt's metrics change over time.

Returns daily response-level metrics for one prompt. Mention Rate and Source Rate use eligible SELF-or-DIRECT answer denominators.

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the prompt
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/prompts/PROMPT_ID/evolution?period=7" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "prompt": {
    "id": "prompt_01",
    "text": "Which analytics platforms support warehouse exports?"
  },
  "evolution": [
    {
      "date": "2026-07-01",
      "answers": 5,
      "mentionRate": 80.0,
      "sourceRate": 60.0,
      "avgSentiment": 78.5
    },
    {
      "date": "2026-07-02",
      "answers": 8,
      "mentionRate": 75.0,
      "sourceRate": 62.5,
      "avgSentiment": 80.1
    }
  ]
}
```

## Errors

| Status | Code                | Description                              |
| ------ | ------------------- | ---------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid query parameter                  |
| 401    | gateway error       | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible    |
| 404    | `PROMPT_NOT_FOUND`  | Prompt doesn't exist                     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After` |

`mentionRate` is answers with a SELF mention divided by answers with a SELF or DIRECT mention. `sourceRate` applies the same response-level denominator rule to citations. `avgSentiment` is on the 0 to 100 scale and can be `null`. See [Rate limits](/developers/rate-limits) for retry behavior.


# Get prompt
Source: https://docs.qwairy.co/developers/endpoints/prompts/get

GET /api/v1/brands/{brandId}/prompts/{promptId}
Retrieve detailed information about a specific prompt.

Returns one prompt with response-level metrics and up to 100 aggregated query fan-outs. Use `include=details` for mention and citation aggregates.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the prompt
</ParamField>

## Query parameters

<ParamField type="string">
  Set to `details` to enrich the prompt with aggregated competitors, sources, brand mentions, and source stability metrics. When omitted, returns the base fields only.
</ParamField>

## Response

The base object includes `answersCount`, Mention Rate, Source Rate, SELF `avgSentiment`, and these query-fan-out fields:

* `queryFanOutsTotal`: total distinct normalized queries
* `queryFanOutsLimit`: maximum rows returned, currently `100`
* `queryFanOuts`: `query`, `occurrences`, `uniqueAnswers`, raw `models`, `firstSeen`, and `lastSeen`

Mention Rate divides answers with a SELF mention by answers with a SELF or DIRECT mention. Source Rate applies the equivalent answer-level formula to citations.

## Synthetic response

```json theme={null}
{
  "success": true,
  "prompt": {
    "id": "prompt_01",
    "text": "Which analytics platforms support warehouse exports?",
    "topic": {
      "id": "topic_01",
      "name": "Data exports"
    },
    "type": "TOFU",
    "tags": [
      { "id": "tag1", "name": "reviews" },
      { "id": "tag2", "name": "comparison" }
    ],
    "answersCount": 2,
    "mentionRate": 50.0,
    "sourceRate": 25.0,
    "avgSentiment": 78.5,
    "queryFanOutsTotal": 1,
    "queryFanOutsLimit": 100,
    "queryFanOuts": [
      {
        "query": "analytics warehouse export integrations",
        "occurrences": 2,
        "uniqueAnswers": 2,
        "models": ["openai-gpt-5.4"],
        "firstSeen": "2026-07-18T10:00:00.000Z",
        "lastSeen": "2026-07-19T10:00:00.000Z"
      }
    ],
    "createdAt": "2026-07-01T10:00:00.000Z",
    "lastGeneratedAt": "2026-07-19T10:00:00.000Z"
  }
}
```

## Synthetic response with `include=details`

```json theme={null}
{
  "success": true,
  "prompt": {
    "id": "prompt_01",
    "text": "Which analytics platforms support warehouse exports?",
    "topic": {
      "id": "topic_01",
      "name": "Data exports"
    },
    "type": "TOFU",
    "tags": [
      { "id": "tag1", "name": "reviews" },
      { "id": "tag2", "name": "comparison" }
    ],
    "answersCount": 2,
    "mentionRate": 50.0,
    "sourceRate": 25.0,
    "avgSentiment": 78.5,
    "queryFanOutsTotal": 1,
    "queryFanOutsLimit": 100,
    "queryFanOuts": [],
    "createdAt": "2026-07-01T10:00:00.000Z",
    "lastGeneratedAt": "2026-07-19T10:00:00.000Z",
    "competitors": [
      { "name": "Acme Analytics", "mentions": 3, "relationship": "SELF" },
      { "name": "Rival Labs", "mentions": 8, "relationship": "DIRECT" }
    ],
    "competitorsCount": 2,
    "competitorMentionsTotal": 11,
    "brandMentioned": true,
    "brandMentionCount": 3,
    "sources": [
      { "domain": "acme.example", "citations": 2, "isSelf": true },
      { "domain": "reviews.example", "citations": 4, "isSelf": false }
    ],
    "sourcesCount": 2,
    "sourceCitationsTotal": 6,
    "sourceStability": 50.0
  }
}
```

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `404`  | Brand or prompt not found                |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List prompts
Source: https://docs.qwairy.co/developers/endpoints/prompts/list

GET /api/v1/brands/{brandId}/prompts
Get paginated prompts with search and filtering options.

Lists monitored prompts with answer counts and response-level SELF metrics. A prompt can have a funnel stage, topic, and tags.

<Note>
  See [Entities](/developers/entities#prompt) for the complete Prompt object structure, and [Topic](/developers/entities#topic) / [Tag](/developers/entities#tag) for classification objects.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. Returns prompts that received at least one answer within the window. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD` (for example, `2026-03-05`). Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD` (for example, `2026-03-31`). Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<Note>
  When a date range is provided, both the prompt list and the per-prompt `include=details` aggregations (`answersCount`, `competitors[].mentions`, `brandMentionCount`, `sources[].citations`) are scoped to that window. Prompts that ran multiple times still appear if at least one of their runs falls inside the range.
</Note>

<ParamField type="string">
  Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

<ParamField type="number">
  Maximum number of prompts to return (max: 100)
</ParamField>

<ParamField type="number">
  Pagination offset
</ParamField>

<ParamField type="string">
  Field to sort by: `lastGeneratedAt`, `answersCount`, `text`, `createdAt`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

<ParamField type="string">
  Set to `details` to enrich each prompt with aggregated competitors, sources, brand mentions, and source stability metrics. When omitted, the response includes only the base fields listed below.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of prompts matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of prompts in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="prompts" type="array">
  <Expandable title="Prompt object">
    <ResponseField name="id" type="string">Prompt ID</ResponseField>
    <ResponseField name="text" type="string">Prompt text</ResponseField>
    <ResponseField name="topic" type="string">Associated topic name</ResponseField>
    <ResponseField name="type" type="string">Prompt type (TOFU/MOFU/BOFU)</ResponseField>
    <ResponseField name="tags" type="array">List of tag names</ResponseField>
    <ResponseField name="answersCount" type="number">Number of generated answers</ResponseField>
    <ResponseField name="mentionRate" type="number">Answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>
    <ResponseField name="sourceRate" type="number">Answers with a SELF citation divided by answers with a SELF or DIRECT citation</ResponseField>
    <ResponseField name="lastGeneratedAt" type="string">Last generation timestamp (ISO 8601)</ResponseField>
  </Expandable>

  <Expandable title="Additional fields when include=details">
    <ResponseField name="competitors" type="array">
      List of competitors mentioned across all answers for this prompt.
      Each object contains `name` (string), `mentions` (number), and `relationship` (`SELF`, `DIRECT`, `INDIRECT`).
    </ResponseField>

    <ResponseField name="competitorsCount" type="number">Number of unique competitors mentioned</ResponseField>
    <ResponseField name="competitorMentionsTotal" type="number">Total competitor mentions across all answers</ResponseField>
    <ResponseField name="brandMentioned" type="boolean">Whether your brand was mentioned in any answer</ResponseField>
    <ResponseField name="brandMentionCount" type="number">Number of times your brand was mentioned</ResponseField>

    <ResponseField name="sources" type="array">
      List of source domains cited across all answers for this prompt.
      Each object contains `domain` (string), `citations` (number), and `isSelf` (boolean).
    </ResponseField>

    <ResponseField name="sourcesCount" type="number">Number of unique source domains cited</ResponseField>
    <ResponseField name="sourceCitationsTotal" type="number">Total source citations across all answers</ResponseField>
    <ResponseField name="sourceStability" type="number">Percentage of distinct source domains present in every scoped answer when there is more than one answer; otherwise `0`</ResponseField>
    <ResponseField name="createdAt" type="string">Prompt creation timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/prompts?type=TOFU&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "prompt_01",
      "text": "Which analytics platforms support warehouse exports?",
      "topic": "Data exports",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2026-07-19T10:00:00.000Z"
    }
  ]
}
```

## Synthetic response with `include=details`

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/prompts?include=details&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "prompt_01",
      "text": "Which analytics platforms support warehouse exports?",
      "topic": "Data exports",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2024-12-19T10:00:00.000Z",
      "competitors": [
        { "name": "Acme Analytics", "mentions": 3, "relationship": "SELF" },
        { "name": "Rival Labs", "mentions": 8, "relationship": "DIRECT" },
        { "name": "Northstar Data", "mentions": 5, "relationship": "DIRECT" }
      ],
      "competitorsCount": 3,
      "competitorMentionsTotal": 16,
      "brandMentioned": true,
      "brandMentionCount": 3,
      "sources": [
        { "domain": "acme.example", "citations": 2, "isSelf": true },
        { "domain": "reviews.example", "citations": 4, "isSelf": false },
        { "domain": "publisher.example", "citations": 3, "isSelf": false }
      ],
      "sourcesCount": 3,
      "sourceCitationsTotal": 9,
      "sourceStability": 33.33,
      "createdAt": "2026-07-01T10:00:00.000Z"
    }
  ]
}
```

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Invalid query parameter                  |
| `401`  | Missing or invalid API token             |
| `404`  | Brand not found or inaccessible          |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List query fan-out records
Source: https://docs.qwairy.co/developers/endpoints/search

GET /api/v1/brands/{brandId}/search
List aggregated web-search queries recorded while providers generated answers.

Returns retained web-search queries associated with stored answers. Results are grouped by normalized query text and include presence counts plus an API-defined priority label.

<Note>
  Results are aggregated by query (case-insensitive, trimmed). Each row represents a unique search query across all responses and providers.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/search
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by one or more provider aliases or model IDs, separated by commas.
</ParamField>

<ParamField type="number">
  Maximum number of queries to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `occurrences`, `priority`, `brandPresence`, `query`, `createdAt`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of unique queries matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of queries in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="searches" type="array">
  <Expandable title="Search insight object">
    <ResponseField name="query" type="string">The search query used by the AI</ResponseField>
    <ResponseField name="occurrences" type="number">Number of times this query appeared across all responses</ResponseField>
    <ResponseField name="priority" type="string">Priority level: `very-high` (competitors present, brand absent), `high` (both present), `medium` (brand only), `low` (neither)</ResponseField>
    <ResponseField name="brandPresence" type="number">Number of responses where the brand's domain was cited as source</ResponseField>
    <ResponseField name="competitorPresence" type="number">Number of responses where direct competitors were mentioned</ResponseField>
    <ResponseField name="competitors" type="array">Distinct direct competitor names</ResponseField>
    <ResponseField name="uniquePrompts" type="number">Number of distinct prompts associated with this query</ResponseField>
    <ResponseField name="prompts" type="array">Associated prompt objects with `id` and `text`</ResponseField>
    <ResponseField name="uniqueAnswers" type="number">Number of distinct AI responses containing this query</ResponseField>
    <ResponseField name="uniqueModels" type="number">Number of distinct AI models that generated this query</ResponseField>
    <ResponseField name="models" type="array">Model IDs associated with the query</ResponseField>
    <ResponseField name="topics" type="array">Associated topic names</ResponseField>
    <ResponseField name="tags" type="array">Associated tag names</ResponseField>
    <ResponseField name="firstSeen" type="string">First occurrence (ISO 8601 timestamp)</ResponseField>
    <ResponseField name="lastSeen" type="string">Most recent occurrence (ISO 8601 timestamp)</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/search?limit=10&sort=priority" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 142,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "searches": [
    {
      "query": "enterprise analytics platforms comparison",
      "occurrences": 12,
      "priority": "very-high",
      "brandPresence": 0,
      "competitorPresence": 8,
      "competitors": ["Orbit Systems"],
      "uniquePrompts": 5,
      "prompts": [{ "id": "prompt_analytics", "text": "Which analytics platforms are commonly compared?" }],
      "uniqueAnswers": 12,
      "uniqueModels": 3,
      "models": ["openai-gpt-5.4", "anthropic-claude-4.6-sonnet", "google-gemini-3-pro"],
      "topics": ["Analytics"],
      "tags": ["Comparison"],
      "firstSeen": "2026-07-01T10:30:00.000Z",
      "lastSeen": "2026-07-15T10:30:00.000Z"
    },
    {
      "query": "northstar analytics pricing",
      "occurrences": 5,
      "priority": "medium",
      "brandPresence": 3,
      "competitorPresence": 0,
      "competitors": [],
      "uniquePrompts": 2,
      "prompts": [{ "id": "prompt_pricing", "text": "What pricing information is available?" }],
      "uniqueAnswers": 5,
      "uniqueModels": 2,
      "models": ["openai-gpt-5.4", "google-gemini-3-pro"],
      "topics": ["Pricing"],
      "tags": [],
      "firstSeen": "2026-07-05T09:15:00.000Z",
      "lastSeen": "2026-07-14T09:15:00.000Z"
    }
  ]
}
```

<Note>
  `priority` is a deterministic classification from `brandPresence` and `competitorPresence`. Treat it as a triage input, not as a business-impact forecast.
</Note>

## Errors

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid filter, pagination, or sort value |
| 401    | gateway error       | Authentication failed                     |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`  |


# List shopping results
Source: https://docs.qwairy.co/developers/endpoints/shopping

GET /api/v1/brands/{brandId}/shopping
List shopping observations extracted from stored answers.

Returns shopping observations extracted from stored answers. Product details, ratings, reviews, and purchase options can be `null` or empty when they were not captured.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/shopping
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by one or more provider aliases or model IDs, separated by commas.
</ParamField>

<ParamField type="number">
  Maximum number of products to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`, `rating`, `reviews`, `productName`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of products matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of products in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shopping" type="array">
  <Expandable title="Shopping object">
    <ResponseField name="id" type="string">Shopping insight ID</ResponseField>
    <ResponseField name="productName" type="string">Product name</ResponseField>
    <ResponseField name="description" type="string">Product description</ResponseField>
    <ResponseField name="image" type="string">Product image URL</ResponseField>
    <ResponseField name="rating" type="number">Product rating (0-5)</ResponseField>
    <ResponseField name="reviews" type="number">Number of reviews</ResponseField>
    <ResponseField name="options" type="array">Purchasing options with prices and sellers</ResponseField>
    <ResponseField name="prompt" type="string">Prompt associated with the stored observation</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/shopping?limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 85,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "shopping": [
    {
      "id": "shop1",
      "productName": "Northstar Analytics Pro",
      "description": "Synthetic product description",
      "image": "https://assets.northstar.example/product-image.jpg",
      "rating": 4.5,
      "reviews": 1250,
      "options": [
        {
          "price": "$99/month",
          "currency": "USD",
          "websiteName": "Northstar Labs",
          "websiteUrl": "https://northstar.example/pricing"
        }
      ],
      "prompt": "What is the best CRM software for enterprise?",
      "createdAt": "2026-07-15T10:30:00Z"
    },
    {
      "id": "shop2",
      "productName": "Orbit Insights",
      "description": "Synthetic analytics product",
      "image": null,
      "rating": 4.2,
      "reviews": 890,
      "options": [],
      "prompt": "Compare top analytics platforms",
      "createdAt": "2026-07-14T15:45:00Z"
    }
  ]
}
```

## Errors

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid filter, pagination, or sort value |
| 401    | gateway error       | Authentication failed                     |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`  |


# List social signals
Source: https://docs.qwairy.co/developers/endpoints/social

GET /api/v1/brands/{brandId}/social
List citations classified as social-platform sources in stored answers.

Returns citations classified as social or forum sources in stored answers. The stable filter values are `reddit`, `youtube`, `twitter`, `facebook`, `linkedin`, and `other`.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/social
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by one or more provider aliases or model IDs, separated by commas.
</ParamField>

<ParamField type="string">
  Filter by platform: `reddit`, `youtube`, `twitter`, `facebook`, `linkedin`, `other`
</ParamField>

<ParamField type="number">
  Maximum number of citations to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`, `position`, `upvotes`, `comments`, `url`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of citations matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of citations in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="social" type="array">
  <Expandable title="Social citation object">
    <ResponseField name="id" type="string">Social insight ID</ResponseField>
    <ResponseField name="platform" type="string">Platform name (reddit, youtube, twitter, etc.)</ResponseField>
    <ResponseField name="communityId" type="string">Community identifier (subreddit, channel, etc.)</ResponseField>
    <ResponseField name="communityName" type="string">Community display name</ResponseField>
    <ResponseField name="url" type="string">Full URL of the cited content</ResponseField>
    <ResponseField name="title" type="string">Content title (if available)</ResponseField>
    <ResponseField name="domain" type="string">Domain name</ResponseField>
    <ResponseField name="position" type="number">Position in source list</ResponseField>
    <ResponseField name="upvotes" type="number">Upvotes/likes (Reddit, when available)</ResponseField>
    <ResponseField name="commentCount" type="number">Comment count (when available)</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/social?platform=reddit&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "social": [
    {
      "id": "soc1",
      "platform": "reddit",
      "communityId": "SaaS",
      "communityName": "r/SaaS",
      "url": "https://reddit.com/r/SaaS/comments/abc123/best_crm_tools",
      "title": "Analytics tools discussed by a sample community",
      "domain": "reddit.com",
      "position": 2,
      "upvotes": 245,
      "commentCount": 89,
      "createdAt": "2026-07-15T10:30:00Z"
    },
    {
      "id": "soc2",
      "platform": "youtube",
      "communityId": "TechReviewer",
      "communityName": "TechReviewer",
      "url": "https://youtube.com/@TechReviewer/crm-comparison",
      "title": "Synthetic analytics comparison",
      "domain": "youtube.com",
      "position": 3,
      "upvotes": 0,
      "commentCount": 0,
      "createdAt": "2026-07-14T15:45:00Z"
    }
  ]
}
```

<Note>
  Missing engagement metadata is returned as `0`. Do not interpret `0` as a verified platform engagement count without checking the underlying source.
</Note>

## Errors

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid filter, pagination, or sort value |
| 401    | gateway error       | Authentication failed                     |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`  |


# Source domain evolution
Source: https://docs.qwairy.co/developers/endpoints/source-domains/evolution

GET /api/v1/brands/{brandId}/source-domains/{sourceId}/evolution
Track how a source's citation metrics change over time.

Returns daily citation occurrences and average citation position for one source domain.

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the source
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/source-domains/SOURCE_ID/evolution?period=7" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "source": {
    "id": "source_01",
    "domain": "publisher.example",
    "isSelf": false
  },
  "evolution": [
    {
      "date": "2026-07-01",
      "mentions": 5,
      "avgPosition": 3.1
    },
    {
      "date": "2026-07-02",
      "mentions": 8,
      "avgPosition": 2.9
    }
  ]
}
```

## Errors

| Status | Code               | Description                              |
| ------ | ------------------ | ---------------------------------------- |
| 401    | gateway error      | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND`  | Brand doesn't exist or not accessible    |
| 404    | `SOURCE_NOT_FOUND` | Source doesn't exist                     |
| 429    | gateway error      | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get source domain
Source: https://docs.qwairy.co/developers/endpoints/source-domains/get

GET /api/v1/brands/{brandId}/source-domains/{sourceId}
Retrieve detailed source info with breakdowns by provider and topic.

Returns one cited domain with date-scoped metrics, provider and topic breakdowns, and the latest public AI Source Authority score.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/source-domains/SOURCE_ID?period=30" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

<ParamField type="string">
  The unique identifier of the source
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

## Synthetic response

```json theme={null}
{
  "success": true,
  "source": {
    "id": "source_01",
    "domain": "publisher.example",
    "type": "MEDIA",
    "status": "ACTIVE",
    "isSelf": false,
    "totalMentions": 102,
    "rate": 5.10,
    "avgPosition": 3.2,
    "aiSourceAuthorityScore": 61,
    "byProvider": [
      { "provider": "ChatGPT", "mentions": 60, "avgPosition": 3.1 },
      { "provider": "Perplexity", "mentions": 42, "avgPosition": 3.4 }
    ],
    "byTopic": [
      { "topic": "Product Reviews", "mentions": 55, "avgPosition": 2.8 },
      { "topic": "Comparisons", "mentions": 30, "avgPosition": 3.5 }
    ]
  }
}
```

`rate` is this domain's citation occurrences divided by every citation occurrence in the selected date scope. `aiSourceAuthorityScore` can be `null` independently of that date filter because it comes from the latest authority snapshot.

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `401`  | Missing or invalid API token             |
| `404`  | Brand or source domain not found         |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List source domains
Source: https://docs.qwairy.co/developers/endpoints/source-domains/list

GET /api/v1/brands/{brandId}/source-domains
Monitor which domains AI platforms cite.

Lists cited domains and their citation-occurrence share in the selected answer scope.

<Note>
  See [Entities](/developers/entities#source) for the complete Source object structure.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by source type: `INSTITUTIONAL`, `COMMERCIAL`, `MEDIA`, `BLOG`, etc.
</ParamField>

<ParamField type="string">
  Filter by topic ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="number">
  Maximum number of sources to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `mentions`, `position`, `rate`, `domain`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of sources matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of sources in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sources" type="array">
  <Expandable title="Source object">
    <ResponseField name="id" type="string">Source ID</ResponseField>
    <ResponseField name="domain" type="string">Domain name</ResponseField>
    <ResponseField name="type" type="string">Source type</ResponseField>
    <ResponseField name="isSelf" type="boolean">Whether this is your own domain</ResponseField>
    <ResponseField name="totalMentions" type="number">Total citation count</ResponseField>
    <ResponseField name="rate" type="number">This domain's citation occurrences divided by all citation occurrences in the selected scope</ResponseField>
    <ResponseField name="avgPosition" type="number">Average position in source lists</ResponseField>
    <ResponseField name="aiSourceAuthorityScore" type="number | null">Latest public AI Source Authority score, or `null` when evidence is insufficient or no snapshot exists</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/source-domains?limit=10&offset=0" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 45,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sources": [
    {
      "id": "source_01",
      "domain": "publisher.example",
      "type": "MEDIA",
      "isSelf": false,
      "totalMentions": 102,
      "rate": 5.10,
      "avgPosition": 3.2,
      "aiSourceAuthorityScore": 61
    },
    {
      "id": "source_02",
      "domain": "acme.example",
      "type": "INSTITUTIONAL",
      "isSelf": true,
      "totalMentions": 45,
      "rate": 2.25,
      "avgPosition": 2.1,
      "aiSourceAuthorityScore": null
    }
  ]
}
```

## Errors

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Invalid query parameter                  |
| `401`  | Missing or invalid API token             |
| `404`  | Brand not found or inaccessible          |
| `429`  | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List source URLs
Source: https://docs.qwairy.co/developers/endpoints/source-urls

GET /api/v1/brands/{brandId}/source-urls
Track individual page citations.

Lists cited URLs with occurrence counts, average position, taxonomy, and relationship flags for the selected answer scope.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/source-urls
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by specific domain
</ParamField>

<ParamField type="string">
  Filter by self domains: `true` or `false`
</ParamField>

<ParamField type="string">
  Filter by competitor domains: `true` or `false`
</ParamField>

<ParamField type="number">
  Maximum number of URLs to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `mentions`, `position`, `shareOfVoice`, `url`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of URLs matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of URLs in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sourceUrls" type="array">
  <Expandable title="Source URL object">
    <ResponseField name="url" type="string">Full URL of the cited page</ResponseField>
    <ResponseField name="title" type="string">Page title (if available)</ResponseField>
    <ResponseField name="domain" type="string">Domain name</ResponseField>
    <ResponseField name="isSelf" type="boolean">Whether this is your domain</ResponseField>
    <ResponseField name="isCompetitor" type="boolean">Whether this is a direct competitor's domain</ResponseField>
    <ResponseField name="competitors" type="array">Names of direct competitors associated with this URL</ResponseField>
    <ResponseField name="totalMentions" type="number">Total citation count</ResponseField>
    <ResponseField name="avgPosition" type="number">Average position in source lists</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of all citations (0-100)</ResponseField>
    <ResponseField name="topics" type="array">Associated topic objects with `id` and `text`</ResponseField>
    <ResponseField name="tags" type="array">Associated tag objects with `id` and `name`</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/source-urls?isSelf=true&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sourceUrls": [
    {
      "url": "https://acme.example/guides/warehouse-exports",
      "title": "Warehouse export guide",
      "domain": "acme.example",
      "isSelf": true,
      "isCompetitor": false,
      "competitors": [],
      "totalMentions": 45,
      "avgPosition": 2.1,
      "shareOfVoice": 3.5,
      "topics": [{ "id": "topic_01", "text": "Data exports" }],
      "tags": [{ "id": "tag_01", "name": "integrations" }]
    },
    {
      "url": "https://rival.example/docs/export-review",
      "title": "Export integration overview",
      "domain": "rival.example",
      "isSelf": false,
      "isCompetitor": true,
      "competitors": ["Rival Labs"],
      "totalMentions": 32,
      "avgPosition": 3.4,
      "shareOfVoice": 2.1,
      "topics": [{ "id": "topic_01", "text": "Data exports" }],
      "tags": []
    }
  ]
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| 401    | gateway error     | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible    |
| 429    | gateway error     | Rate limit exceeded; honor `Retry-After` |

`shareOfVoice` is the URL's citation occurrences divided by all citation occurrences in the selected scope. See [Rate limits](/developers/rate-limits) for retry behavior.


# List sponsored content
Source: https://docs.qwairy.co/developers/endpoints/sponsored

GET /api/v1/brands/{brandId}/sponsored
List sponsored placements detected in stored answers.

Returns sponsored placements retained from stored answers. A record reflects the captured answer at that time; it does not confirm an active campaign or advertiser relationship.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/sponsored
```

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by one or more provider aliases or model IDs, separated by commas.
</ParamField>

<ParamField type="string">
  Filter by advertiser name (case-insensitive partial match)
</ParamField>

<ParamField type="number">
  Maximum number of results to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `createdAt`, `advertiserName`, `productName`, `position`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of sponsored placements matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of items in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sponsored" type="array">
  <Expandable title="Sponsored content object">
    <ResponseField name="id" type="string">Sponsored content record ID</ResponseField>
    <ResponseField name="advertiserName" type="string">Name of the advertiser</ResponseField>
    <ResponseField name="advertiserLogo" type="string">URL of the advertiser's logo</ResponseField>
    <ResponseField name="productName" type="string">Name of the advertised product</ResponseField>
    <ResponseField name="description" type="string">Product description text</ResponseField>
    <ResponseField name="imageUrl" type="string">Product image URL</ResponseField>
    <ResponseField name="position" type="number">Position of the ad within the response (1 = first)</ResponseField>
    <ResponseField name="provider" type="string">AI provider model ID</ResponseField>
    <ResponseField name="competitorRelationship" type="string">Relationship to your brand if advertiser is a known competitor: `SELF`, `DIRECT`, `INDIRECT`, or `null`</ResponseField>
    <ResponseField name="prompt" type="string">Prompt associated with the stored placement</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/sponsored?period=30&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 24,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sponsored": [
    {
      "id": "sp1",
      "advertiserName": "Orbit Travel",
      "advertiserLogo": "https://assets.orbit.example/logo.png",
      "productName": "Sample flight offer",
      "description": "Synthetic sponsored placement description.",
      "imageUrl": null,
      "position": 1,
      "provider": "openai-gpt-5.4",
      "competitorRelationship": "DIRECT",
      "prompt": "What are the best flight deals from Chicago?",
      "createdAt": "2026-04-10T14:30:00Z"
    },
    {
      "id": "sp2",
      "advertiserName": "Northstar Retail",
      "advertiserLogo": "https://assets.northstar.example/logo.png",
      "productName": "Sample seasonal offer",
      "description": "Synthetic sponsored placement description.",
      "imageUrl": null,
      "position": 1,
      "provider": "openai-gpt-5.4",
      "competitorRelationship": null,
      "prompt": "Best spring fashion deals 2026",
      "createdAt": "2026-04-09T09:15:00Z"
    }
  ]
}
```

## Errors

| Status | Code                | Description                               |
| ------ | ------------------- | ----------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid filter, pagination, or sort value |
| 401    | gateway error       | Authentication failed                     |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible     |
| 429    | gateway error       | Rate limit exceeded; honor `Retry-After`  |


# Tag evolution
Source: https://docs.qwairy.co/developers/endpoints/tags/evolution

GET /api/v1/brands/{brandId}/tags/{tagId}/evolution
Daily time-series metrics for a specific tag.

Returns daily response-level metrics for one tag. Mention Rate and Source Rate use eligible SELF-or-DIRECT answer denominators; Share of Voice uses mention occurrences.

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

<ParamField type="string">
  The unique identifier of the tag
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic (keyword) ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="tag" type="object">
  <Expandable title="Tag info">
    <ResponseField name="id" type="string">Tag ID</ResponseField>
    <ResponseField name="name" type="string">Tag name</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="evolution" type="array">
  <Expandable title="Daily metrics">
    <ResponseField name="date" type="string">Date (YYYY-MM-DD format)</ResponseField>
    <ResponseField name="answers" type="number">Stored answers on this date</ResponseField>
    <ResponseField name="mentionRate" type="number">Answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>
    <ResponseField name="shareOfVoice" type="number">SELF mention occurrences divided by SELF and DIRECT mention occurrences</ResponseField>
    <ResponseField name="avgSentiment" type="number | null">Average SELF mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
    <ResponseField name="sourceRate" type="number">Answers with a SELF citation divided by answers with a SELF or DIRECT citation</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/tags/TAG_ID/evolution?period=30" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "tag": {
    "id": "tag1",
    "name": "Product Comparisons"
  },
  "evolution": [
    {
      "date": "2026-02-15",
      "answers": 42,
      "mentionRate": 65.2,
      "shareOfVoice": 48.3,
      "avgSentiment": 72.1,
      "sourceRate": 55.0
    },
    {
      "date": "2026-02-16",
      "answers": 38,
      "mentionRate": 60.5,
      "shareOfVoice": 45.1,
      "avgSentiment": 74.2,
      "sourceRate": 52.6
    }
  ]
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| 401    | gateway error     | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible    |
| 404    | `TAG_NOT_FOUND`   | Tag doesn't exist or not accessible      |
| 429    | gateway error     | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# List tags
Source: https://docs.qwairy.co/developers/endpoints/tags/list

GET /api/v1/brands/{brandId}/tags
Analyze performance by tag.

Lists tags with answer counts and response-level SELF metrics for the selected scope.

<Note>
  See [Entities](/developers/entities#tag) for the complete Tag object structure.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Query parameters

<ParamField type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField type="string">
  Filter by topic (keyword) ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField type="number">
  Maximum number of tags to return (max: 100)
</ParamField>

<ParamField type="number">
  Number of results to skip for pagination
</ParamField>

<ParamField type="string">
  Field to sort by: `prompts`, `answers`, `mentionRate`, `shareOfVoice`, `sentiment`, `name`
</ParamField>

<ParamField type="string">
  Sort order: `asc` or `desc`
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of tags matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of tags in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tags" type="array">
  <Expandable title="Tag object">
    <ResponseField name="id" type="string">Tag ID</ResponseField>
    <ResponseField name="name" type="string">Tag name</ResponseField>
    <ResponseField name="totalPrompts" type="number">Number of prompts with this tag</ResponseField>
    <ResponseField name="totalAnswers" type="number">Stored answers in the selected scope</ResponseField>
    <ResponseField name="brandMentionRate" type="number">Answers with a SELF mention divided by answers with a SELF or DIRECT mention</ResponseField>
    <ResponseField name="shareOfVoice" type="number">SELF mention occurrences divided by SELF and DIRECT mention occurrences</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average SELF mention sentiment on a 0 to 100 scale; `0` is returned when no scored SELF mention exists</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/tags?limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 12,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "tags": [
    {
      "id": "tag1",
      "name": "Product Comparisons",
      "totalPrompts": 25,
      "totalAnswers": 200,
      "brandMentionRate": 52.0,
      "shareOfVoice": 38.5,
      "avgSentiment": 81.2
    },
    {
      "id": "tag2",
      "name": "Pricing Questions",
      "totalPrompts": 18,
      "totalAnswers": 144,
      "brandMentionRate": 35.4,
      "shareOfVoice": 22.1,
      "avgSentiment": 68.5
    }
  ]
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| 401    | gateway error     | Missing or invalid API token             |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible    |
| 429    | gateway error     | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


# Get Site Readiness analysis
Source: https://docs.qwairy.co/developers/endpoints/technical-analysis

GET /api/v1/brands/{brandId}/technical-analysis
Read the stored Site Readiness analysis for robots.txt, llms.txt, and sitemap.xml.

Returns the latest stored Site Readiness analysis for `robots.txt`, `llms.txt`, and `sitemap.xml`. The response field remains `aiReadiness` for API compatibility. This read-only request does not start a crawl.

<Note>
  When no stored analysis exists, `analyzed` is `false`, `aiReadiness` and the analysis fields are `null`, and the response includes a message explaining how the product initializes the analysis.
</Note>

<ParamField type="string">
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

## Path parameters

<ParamField type="string">
  The unique identifier of the brand
</ParamField>

## Site Readiness Score formula

Out of 100:

* robots.txt present: **+20**
* accessible crawlers: **+round((Allowed or Partial entries / returned crawler entries) × 40)**. No crawler entries means 0 points for this component.
* llms.txt present: **+20**
* sitemap.xml present: **+20**

A missing or invalid robots.txt therefore caps the score at 40.

## Response

<ResponseField name="success" type="boolean">Indicates if the request was successful</ResponseField>

<ResponseField name="brand" type="object">`id`, `name`, `domain`</ResponseField>

<ResponseField name="analyzed" type="boolean">
  `false` when no analysis has been generated yet (all analysis fields are then `null`)
</ResponseField>

<ResponseField name="aiReadiness" type="object">
  <Expandable title="AI Readiness">
    <ResponseField name="score" type="number">Site Readiness Score (`0-100`)</ResponseField>
    <ResponseField name="issuesCount" type="number">Number of detected issues</ResponseField>
    <ResponseField name="optimizationsCount" type="number">Number of suggested optimizations</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="robotsUrl" type="string">URL checked for robots.txt</ResponseField>
<ResponseField name="llmsUrl" type="string">URL checked for llms.txt</ResponseField>
<ResponseField name="sitemapUrl" type="string">URL checked for sitemap.xml</ResponseField>

<ResponseField name="robotsAnalysis" type="object">
  <Expandable title="File analysis">
    <ResponseField name="status" type="string">`present`, `missing`, `error` or `invalid`</ResponseField>
    <ResponseField name="finalUrl" type="string">Final URL after redirects</ResponseField>
    <ResponseField name="error" type="string">Error message when status is `error`</ResponseField>
    <ResponseField name="content" type="string">Fetched file content</ResponseField>
    <ResponseField name="crawlers" type="object">Per-crawler `{ status: "Allowed" | "Disallowed" | "Partial", reason }` map (robots.txt only)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="llmsAnalysis" type="object">Same shape as `robotsAnalysis` (no `crawlers`)</ResponseField>
<ResponseField name="sitemapAnalysis" type="object">Same shape as `robotsAnalysis` (no `crawlers`)</ResponseField>

<ResponseField name="lastAnalyzedAt" type="string">Last analysis timestamp (ISO 8601) or `null`</ResponseField>
<ResponseField name="generatedLlmsTxt" type="string">Generated llms.txt template, or `null` if never generated</ResponseField>

## Synthetic request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/technical-analysis" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "brand": { "id": "cm1234567890abcdef", "name": "Northstar Labs", "domain": "northstar.example" },
  "analyzed": true,
  "aiReadiness": {
    "score": 80,
    "issuesCount": 0,
    "optimizationsCount": 1
  },
  "robotsUrl": "https://northstar.example/robots.txt",
  "llmsUrl": "https://northstar.example/llms.txt",
  "sitemapUrl": "https://northstar.example/sitemap.xml",
  "robotsAnalysis": {
    "status": "present",
    "finalUrl": "https://northstar.example/robots.txt",
    "crawlers": {
      "GPTBot": { "status": "Allowed", "reason": "No matching disallow rule" },
      "ClaudeBot": { "status": "Allowed", "reason": "No matching disallow rule" }
    }
  },
  "llmsAnalysis": { "status": "missing" },
  "sitemapAnalysis": { "status": "present", "finalUrl": "https://northstar.example/sitemap.xml" },
  "lastAnalyzedAt": "2026-05-12T08:30:00.000Z",
  "generatedLlmsTxt": null
}
```

## Errors

| Status | Code              | Description                              |
| ------ | ----------------- | ---------------------------------------- |
| `401`  | gateway error     | Authentication failed                    |
| `404`  | `BRAND_NOT_FOUND` | Brand not found or not accessible        |
| `429`  | gateway error     | Rate limit exceeded; honor `Retry-After` |


# Entities
Source: https://docs.qwairy.co/developers/entities

Reference the shared objects and metric fields returned by API v1.

These shared structures appear across API v1 responses. Endpoint pages remain the source of truth for fields returned by a specific route.

## Pagination

Most list endpoints return a `pagination` object. The brands endpoint returns `total` without pagination.

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 10,
    "limit": 10,
    "offset": 0
  },
  "data": [ ... ]
}
```

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination object">
    <ResponseField name="total" type="number">
      Total number of items matching the query (across all pages)
    </ResponseField>

    <ResponseField name="count" type="number">
      Number of items returned in this response
    </ResponseField>

    <ResponseField name="limit" type="number">
      Maximum items per page (as requested or default)
    </ResponseField>

    <ResponseField name="offset" type="number">
      Number of items skipped (for pagination)
    </ResponseField>
  </Expandable>
</ResponseField>

### Synthetic pagination example

To fetch page 2 with 20 items per page:

```bash theme={null}
GET /api/v1/brands/{brandId}/prompts?limit=20&offset=20
```

Synthetic response:

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 20,
    "limit": 20,
    "offset": 20
  },
  "prompts": [ ... ]
}
```

***

## Brand

A brand represents the company or product monitored by a workspace.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/brands/list">
  List Brands, Get Brand Details
</Card>

Synthetic example:

```json theme={null}
{
  "id": "brand_01",
  "name": "Acme Analytics",
  "domain": "acme.example",
  "description": "Analytics software for operations teams.",
  "createdAt": "2026-07-15T10:30:00.000Z",
  "stats": {
    "promptsCount": 156,
    "answersCount": 312,
    "competitorsCount": 8
  }
}
```

<ResponseField name="id" type="string">
  Opaque brand identifier
</ResponseField>

<ResponseField name="name" type="string">
  Brand display name
</ResponseField>

<ResponseField name="domain" type="string">
  Primary domain associated with the brand
</ResponseField>

<ResponseField name="description" type="string">
  Optional brand description (can be null)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of brand creation
</ResponseField>

<ResponseField name="stats" type="object">
  <Expandable title="Brand statistics">
    <ResponseField name="promptsCount" type="number">
      Total prompts tracked for this brand
    </ResponseField>

    <ResponseField name="answersCount" type="number">
      Total stored answers for this brand
    </ResponseField>

    <ResponseField name="competitorsCount" type="number">
      Number of competitors (SELF + DIRECT)
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Pitch Audit

A Pitch Audit is a read-only report resource generated for an agency prospect. Once completed, its evidence is a snapshot. Competitor and co-competitor reports are subject views derived from the same audit, not separate audit records.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/pitch-audits/list">
  List Pitch Audits, Get Pitch Audit, Get Pitch Audit Subject Report
</Card>

Synthetic example:

```json theme={null}
{
  "id": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
  "status": "COMPLETED",
  "reportSubject": {
    "id": "self",
    "name": "Prospect Brand",
    "isOriginalBrand": true
  },
  "availableSubjects": [
    { "id": "self", "name": "Prospect Brand", "isOriginalBrand": true },
    { "id": "rival.example", "name": "Rival Labs", "isOriginalBrand": false }
  ],
  "answersIncluded": false,
  "answerCount": 24,
  "coCompetitors": [
    {
      "subjectId": "rival.example",
      "name": "Rival Labs",
      "scores": { "geoScore": 64, "mentionRate": 50 },
      "reportUrl": "/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/rival.example"
    }
  ]
}
```

<ResponseField name="reportSubject" type="object">
  Subject represented by the current report. The original prospect uses `self`; derived reports use a stable competitor `subjectId`.
</ResponseField>

<ResponseField name="availableSubjects" type="array">
  All subjects that can be resolved within this audit.
</ResponseField>

<ResponseField name="coCompetitors" type="array">
  Brands that appear in the same answers as the current subject. Use each row's `subjectId` or canonical `reportUrl` to open its derived report. When `includeCoCompetitorScores=true`, each row also includes its full `scores` summary.
</ResponseField>

<ResponseField name="answersIncluded" type="boolean">
  Whether the response contains full AI answer text. Answers are excluded by default.
</ResponseField>

<ResponseField name="answerCount" type="number">
  Number of answers available, whether or not answer text was requested.
</ResponseField>

***

## Competitor

A competitor is a brand or domain detected in stored answers and classified relative to the monitored brand.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/competitors/list">
  List Competitors, Get Competitor Details, Competitor Evolution
</Card>

Synthetic example:

```json theme={null}
{
  "id": "cmp_abc123",
  "name": "Rival Labs",
  "domain": "rival.example",
  "relationship": "DIRECT",
  "totalMentions": 111,
  "shareOfVoice": 8.73,
  "avgPosition": 2.3,
  "avgSentiment": 75.2
}
```

<ResponseField name="id" type="string">
  Unique competitor identifier
</ResponseField>

<ResponseField name="name" type="string">
  Competitor display name
</ResponseField>

<ResponseField name="domain" type="string">
  Competitor's primary domain
</ResponseField>

<ResponseField name="relationship" type="string">
  Relationship type:

  * `SELF`: Your own brand
  * `DIRECT`: Direct competitor (used in Share of Voice calculation)
  * `INDIRECT`: Indirect competitor (mentioned by AI but not a direct rival)

  The list endpoint returns `SELF` and `DIRECT` by default and can include `INDIRECT` through the `relationship` filter. Detail and evolution Share of Voice use SELF and DIRECT mentions. On the list endpoint, Share of Voice uses the relationships selected by the filter.
</ResponseField>

<ResponseField name="totalMentions" type="number">
  Total number of times mentioned in AI responses
</ResponseField>

<ResponseField name="shareOfVoice" type="number">
  Share of Voice (0-100). This entity's share of all brand mentions in AI responses: its mentions divided by the total of all SELF and DIRECT mentions. INDIRECT mentions are excluded.
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position when mentioned in lists (1 = first, lower is better)
</ResponseField>

<ResponseField name="avgSentiment" type="number">
  Average mention sentiment on a 0 to 100 scale, or `null`
</ResponseField>

***

## Source

A source is a domain cited by AI platforms when generating responses. Track which websites influence AI answers in your industry.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/source-domains/list">
  Source Domains, Source URLs, Source Evolution
</Card>

Synthetic example:

```json theme={null}
{
  "id": "src_xyz789",
  "domain": "publisher.example",
  "type": "MEDIA",
  "isSelf": false,
  "totalMentions": 102,
  "rate": 5.10,
  "avgPosition": 3.2,
  "aiSourceAuthorityScore": 61
}
```

<ResponseField name="id" type="string">
  Unique source identifier
</ResponseField>

<ResponseField name="domain" type="string">
  Source domain name
</ResponseField>

<ResponseField name="type" type="string">
  Source category:

  * `INSTITUTIONAL`: Official/government sites
  * `COMMERCIAL`: E-commerce, business sites
  * `MEDIA`: News, magazines, publications
  * `BLOG`: Personal or company blogs
  * `SOCIAL`: Social media platforms
  * `FORUM`: Discussion forums, Q\&A sites
  * `EDUCATIONAL`: Universities, courses
  * `OTHER`: Uncategorized
</ResponseField>

<ResponseField name="isSelf" type="boolean">
  Whether this source belongs to your brand
</ResponseField>

<ResponseField name="totalMentions" type="number">
  Total citations in AI responses
</ResponseField>

<ResponseField name="rate" type="number">
  **Share of Citations** - percentage of all AI citations from this source (0-100). Example: `rate: 5.10` means 5.10% of all citations reference this domain.
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position in source lists (1 = first)
</ResponseField>

<ResponseField name="aiSourceAuthorityScore" type="number | null">
  Latest public AI Source Authority score, or `null` when no sufficient snapshot is available
</ResponseField>

***

## Prompt

A prompt is a question monitored across AI providers. Each prompt can have a funnel stage, topic, and tags.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/prompts/list">
  List Prompts, Get Prompt Details, Prompt Answers
</Card>

Synthetic example:

```json theme={null}
{
  "id": "q_abc123",
  "text": "Which analytics platforms support warehouse exports?",
  "topic": "Data exports",
  "type": "TOFU",
  "tags": ["reviews", "comparison"],
  "answersCount": 2,
  "mentionRate": 50.0,
  "sourceRate": 25.0,
  "lastGeneratedAt": "2026-07-19T10:00:00.000Z"
}
```

<ResponseField name="id" type="string">
  Unique prompt identifier
</ResponseField>

<ResponseField name="text" type="string">
  The prompt/question text
</ResponseField>

<ResponseField name="topic" type="string">
  Associated topic/keyword name (can be null)
</ResponseField>

<ResponseField name="type" type="string">
  Marketing funnel stage:

  * `TOFU`: Top of Funnel (awareness)
  * `MOFU`: Middle of Funnel (consideration)
  * `BOFU`: Bottom of Funnel (decision)
</ResponseField>

<ResponseField name="tags" type="array">
  List of tag names for organization
</ResponseField>

<ResponseField name="answersCount" type="number">
  Number of AI responses generated for this prompt
</ResponseField>

<ResponseField name="mentionRate" type="number">
  Answers with a SELF mention divided by answers with a SELF or DIRECT mention, from 0 to 100
</ResponseField>

<ResponseField name="sourceRate" type="number">
  Answers with a SELF citation divided by answers with a SELF or DIRECT citation, from 0 to 100
</ResponseField>

<ResponseField name="lastGeneratedAt" type="string">
  ISO 8601 timestamp of last answer generation
</ResponseField>

***

## Answer

An answer is stored output from one provider run for a prompt. It contains text, detected mentions, and citations.

<Card title="Related Endpoints" icon="link" href="/developers/endpoints/answers/list">
  List Answers, Get Answer Details
</Card>

Synthetic example:

```json theme={null}
{
  "id": "ans_123abc",
  "promptId": "q_abc123",
  "promptText": "Which analytics platforms support warehouse exports?",
  "provider": "Example provider",
  "model": "example-model",
  "text": "Acme Analytics and Rival Labs both document warehouse exports...",
  "hasSelfMention": true,
  "selfMentionPosition": 3,
  "hasSelfSource": false,
  "competitorsCount": 5,
  "sourcesCount": 3,
  "sentiment": 82,
  "createdAt": "2026-07-19T10:00:00.000Z"
}
```

<ResponseField name="id" type="string">
  Unique answer identifier
</ResponseField>

<ResponseField name="promptId" type="string">
  ID of the associated prompt
</ResponseField>

<ResponseField name="promptText" type="string">
  Text of the associated prompt
</ResponseField>

<ResponseField name="provider" type="string">
  Provider display name
</ResponseField>

<ResponseField name="model" type="string">
  Model display name
</ResponseField>

<ResponseField name="text" type="string">
  Full response text (or preview in list endpoints)
</ResponseField>

<ResponseField name="hasSelfMention" type="boolean">
  Whether your brand is mentioned
</ResponseField>

<ResponseField name="selfMentionPosition" type="number">
  Position in competitor list when mentioned (null if not mentioned)
</ResponseField>

<ResponseField name="hasSelfSource" type="boolean">
  Whether your domain is cited as a source
</ResponseField>

<ResponseField name="competitorsCount" type="number">
  Number of competitors mentioned in this answer
</ResponseField>

<ResponseField name="sourcesCount" type="number">
  Number of sources cited in this answer
</ResponseField>

<ResponseField name="sentiment" type="number">
  Sentiment score for the SELF mention on a 0 to 100 scale, or `null`
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of answer generation
</ResponseField>

***

## Competitor mention

Detailed information about a competitor mention within an answer (returned in answer details).

Synthetic example:

```json theme={null}
{
  "name": "Acme Analytics",
  "position": 3,
  "relationship": "SELF",
  "sentiment": 85
}
```

<ResponseField name="name" type="string">
  Competitor name as mentioned
</ResponseField>

<ResponseField name="position" type="number">
  Position in the response (1 = mentioned first)
</ResponseField>

<ResponseField name="relationship" type="string">
  `SELF`, `DIRECT`, or `INDIRECT`. Answer details return mentions for **all** relationship types. If you're computing Share of Voice, filter to only `SELF` and `DIRECT` mentions.
</ResponseField>

<ResponseField name="sentiment" type="number">
  Sentiment score for this mention on a 0 to 100 scale, or `null`
</ResponseField>

***

## Source citation

Detailed information about a source citation within an answer (returned in answer details).

Synthetic example:

```json theme={null}
{
  "url": "https://publisher.example/article",
  "domain": "publisher.example",
  "position": 1,
  "isSelf": false
}
```

<ResponseField name="url" type="string">
  Full URL cited (can be null)
</ResponseField>

<ResponseField name="domain" type="string">
  Domain name of the source
</ResponseField>

<ResponseField name="position" type="number">
  Position in source list (1 = cited first)
</ResponseField>

<ResponseField name="isSelf" type="boolean">
  Whether this is your own domain
</ResponseField>

***

## Topic

A topic (also called keyword) groups related prompts together.

Synthetic example:

```json theme={null}
{
  "id": "topic_abc123",
  "name": "Product Reviews"
}
```

<ResponseField name="id" type="string">
  Unique topic identifier
</ResponseField>

<ResponseField name="name" type="string">
  Topic display name
</ResponseField>

***

## Tag

Tags allow custom categorization of prompts.

Synthetic example:

```json theme={null}
{
  "id": "tag_xyz789",
  "name": "comparison"
}
```

<ResponseField name="id" type="string">
  Unique tag identifier
</ResponseField>

<ResponseField name="name" type="string">
  Tag display name
</ResponseField>

***

## Evolution data point

Used in evolution endpoints to track metrics over time.

Synthetic example:

```json theme={null}
{
  "date": "2026-07-01",
  "mentions": 5,
  "shareOfVoice": 7.2,
  "avgPosition": 2.3,
  "avgSentiment": 76.5
}
```

<ResponseField name="date" type="string">
  Date in YYYY-MM-DD format
</ResponseField>

<ResponseField name="mentions" type="number">
  Number of mentions on this date
</ResponseField>

<ResponseField name="shareOfVoice" type="number">
  Share of voice percentage on this date
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position on this date
</ResponseField>

<ResponseField name="avgSentiment" type="number">
  Average SELF mention sentiment on this date, or `null`
</ResponseField>


# Error codes
Source: https://docs.qwairy.co/developers/errors

Handle gateway and resource error shapes returned by API v1.

API v1 returns two error shapes depending on where the failure occurs:

* **Resource errors** (validation and not-found errors raised inside an endpoint) return a **nested** object: `{ "error": { "code", "message" } }`. Use the `code` for programmatic handling.
* **Gateway errors** raised before an endpoint runs return a **flat** object: `{ "error", "message" }`. This includes `401`, `429`, and an authentication-layer `500`. Here `error` is a status label, not a machine-readable code.

Always branch on the HTTP status first, then read the body in the shape matching that status.

## HTTP status codes

| Code | Status                | Description                             |
| ---- | --------------------- | --------------------------------------- |
| 200  | OK                    | Request succeeded                       |
| 400  | Bad Request           | Invalid request parameters              |
| 401  | Unauthorized          | Missing or invalid authentication       |
| 403  | Forbidden             | Valid auth but insufficient permissions |
| 404  | Not Found             | Resource doesn't exist                  |
| 429  | Too Many Requests     | Rate limit exceeded                     |
| 500  | Internal Server Error | Server-side error                       |

## Error response formats

### Resource errors (nested)

Validation and not-found errors raised inside an endpoint return a structured `error` object:

```json theme={null}
{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}
```

<ResponseField name="error" type="object">
  <Expandable title="Error object">
    <ResponseField name="code" type="string">
      Machine-readable error code for programmatic handling
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error description
    </ResponseField>
  </Expandable>
</ResponseField>

### Gateway errors (flat)

Gateway responses use a flat shape. `error` is a status label, not a code:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx"
}
```

<ResponseField name="error" type="string">
  Short status label (e.g. `Unauthorized`, `Too Many Requests`).
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable description of the failure.
</ResponseField>

429 responses additionally include `limit` (`"burst"` or `"daily"`) and `retryAfter` (seconds).

## Error code reference

### Authorization

| Code                | HTTP Status | Description                    |
| ------------------- | ----------- | ------------------------------ |
| `INSUFFICIENT_PLAN` | 403         | Growth plan or higher required |
| `FORBIDDEN`         | 403         | Access denied                  |

Authentication `401` responses are flat and do not contain these resource codes.

### Not found

| Code                    | HTTP Status | Description                           |
| ----------------------- | ----------- | ------------------------------------- |
| `BRAND_NOT_FOUND`       | 404         | Brand not found or not accessible     |
| `COMPETITOR_NOT_FOUND`  | 404         | Competitor not found                  |
| `SOURCE_NOT_FOUND`      | 404         | Source not found                      |
| `PROMPT_NOT_FOUND`      | 404         | Prompt not found                      |
| `ANSWER_NOT_FOUND`      | 404         | Answer not found                      |
| `KEYWORD_NOT_FOUND`     | 404         | Topic not found                       |
| `TAG_NOT_FOUND`         | 404         | Tag not found                         |
| `PITCH_AUDIT_NOT_FOUND` | 404         | Pitch Audit not found or inaccessible |
| `RESOURCE_NOT_FOUND`    | 404         | Generic resource not found            |
| `ENDPOINT_NOT_FOUND`    | 404         | API endpoint does not exist           |

### Bad request

| Code                 | HTTP Status | Description                |
| -------------------- | ----------- | -------------------------- |
| `INVALID_REQUEST`    | 400         | Invalid request format     |
| `INVALID_PARAMETER`  | 400         | Invalid parameter value    |
| `MISSING_PARAMETER`  | 400         | Missing required parameter |
| `INVALID_DATE_RANGE` | 400         | Invalid date range         |
| `INVALID_SORT_FIELD` | 400         | Invalid sort field         |

### Rate limiting

Gateway `429` responses are flat. Use the HTTP status, `limit`, `retryAfter`, and `Retry-After` header instead of expecting a nested error code.

### Server errors

| Code             | HTTP Status | Description           |
| ---------------- | ----------- | --------------------- |
| `INTERNAL_ERROR` | 500         | Internal server error |

## Common errors

### Authentication errors (401)

Authentication failures use the **flat** shape:

```json theme={null}
// Missing or malformed Authorization header
{
  "error": "Unauthorized",
  "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx"
}

// Invalid token, revoked token, or plan below Growth
{
  "error": "Unauthorized",
  "message": "Invalid API token or insufficient subscription plan (Growth+ required)"
}
```

Check the `Bearer` prefix, token status, team status, and active plan.

### Permission errors (403)

```json theme={null}
// Team subscription doesn't include API access
{
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "Growth plan or higher required"
  }
}
```

Verify the resource-specific permission or plan requirement.

### Not-found errors (404)

```json theme={null}
// Brand doesn't exist
{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}

// Competitor doesn't exist
{
  "error": {
    "code": "COMPETITOR_NOT_FOUND",
    "message": "Competitor not found"
  }
}
```

Check that the resource ID belongs to the team associated with the token.

### Rate-limit errors (429)

Rate-limit responses use the **flat** shape and add `limit` and `retryAfter`:

```json theme={null}
{
  "error": "Too Many Requests",
  "limit": "burst",
  "message": "Per-minute rate limit exceeded. Please try again in 45 seconds.",
  "retryAfter": 45
}
```

`limit` is `"burst"` (per-minute) or `"daily"`.

Honor the `Retry-After` header before retrying. See [Rate limits](/developers/rate-limits).

### Server errors (500)

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```

Retry transient failures with bounded backoff. If the error persists, contact support with the endpoint and request timestamp.

## Handle errors

### JavaScript/TypeScript example

```typescript theme={null}
async function callQwairyAPI(endpoint: string) {
  const response = await fetch(`https://www.qwairy.co/api/v1${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${process.env.QWAIRY_API_TOKEN}`,
    },
  });

  if (!response.ok) {
    const data = await response.json().catch(() => ({}));

    // Gateway errors use the flat shape: { error, message }
    if (response.status === 401) {
      throw new Error(`Authentication failed: ${data.message ?? data.error}`);
    }
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') ?? data.retryAfter;
      throw new Error(`Rate limited. Retry after ${retryAfter} second(s).`);
    }

    // Resource errors use the nested shape: { error: { code, message } }
    const nestedError = typeof data.error === 'object' ? data.error : null;
    const code = nestedError?.code ?? `HTTP_${response.status}`;
    const message = nestedError?.message ?? data.message ?? data.error ?? `HTTP ${response.status}`;

    switch (code) {
      case 'INSUFFICIENT_PLAN':
      case 'FORBIDDEN':
        throw new Error(`Permission denied: ${message}`);
      case 'BRAND_NOT_FOUND':
      case 'COMPETITOR_NOT_FOUND':
      case 'SOURCE_NOT_FOUND':
      case 'PROMPT_NOT_FOUND':
      case 'ANSWER_NOT_FOUND':
        throw new Error(`Resource not found: ${message}`);
      default:
        throw new Error(`API error [${code}]: ${message}`);
    }
  }

  return response.json();
}
```

### Python example

```python theme={null}
import requests
import os

def call_qwairy_api(endpoint):
    response = requests.get(
        f"https://www.qwairy.co/api/v1{endpoint}",
        headers={"Authorization": f"Bearer {os.environ['QWAIRY_API_TOKEN']}"}
    )

    if not response.ok:
        body = response.json() if response.content else {}

        # Gateway errors use the flat shape: { error, message }
        if response.status_code == 401:
            raise Exception(f"Authentication failed: {body.get('message', body.get('error'))}")
        if response.status_code == 429:
            retry_after = response.headers.get('Retry-After', body.get('retryAfter'))
            raise Exception(f"Rate limited. Retry after {retry_after} second(s).")

        # Resource errors use the nested shape: { error: { code, message } }
        error = body.get('error', {}) if isinstance(body.get('error'), dict) else {}
        code = error.get('code', 'UNKNOWN')
        message = error.get('message', body.get('message', 'Unknown error'))

        if code in ['INSUFFICIENT_PLAN', 'FORBIDDEN']:
            raise Exception(f"Permission denied: {message}")
        elif code.endswith('_NOT_FOUND'):
            raise Exception(f"Not found: {message}")
        else:
            raise Exception(f"API error [{code}]: {message}")

    return response.json()
```

## Get help

If you encounter persistent errors or unexpected behavior, contact us at [team@qwairy.co](mailto:team@qwairy.co) with:

* The endpoint you're calling
* The full error response
* Your request headers (without the token)
* The timestamp of the request


# Competitive analysis
Source: https://docs.qwairy.co/developers/guides/competitive-analysis

Compare SELF and DIRECT observations, then measure one competitor across a consistent API scope.

Use the competitor endpoints to compare observed mentions and Share of Voice within one monitored answer set. This guide uses the reusable client from the [Quick start](/developers/guides/index#api-client).

## Build the comparison

Request SELF and DIRECT relationships for the same period. Do not treat other relationship types as direct competitors unless your analysis explicitly requires them.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function buildCompetitiveLandscape(client, brandId, period = 30) {
    const data = await client.getCompetitors(brandId, {
      period,
      relationship: 'SELF,DIRECT',
      limit: 100,
      sort: 'shareOfVoice',
      order: 'desc',
    });

    const self = data.competitors.find(
      (item) => item.relationship === 'SELF'
    );
    if (!self) throw new Error('SELF brand is absent from the selected scope');

    const competitors = data.competitors
      .filter((item) => item.relationship === 'DIRECT')
      .map((item) => ({
        id: item.id,
        name: item.name,
        mentions: item.totalMentions,
        shareOfVoice: item.shareOfVoice,
        shareOfVoiceGap: Number(
          (item.shareOfVoice - self.shareOfVoice).toFixed(2)
        ),
        averagePosition: item.avgPosition,
        sentiment: item.avgSentiment,
      }));

    return {
      period,
      self: {
        id: self.id,
        name: self.name,
        mentions: self.totalMentions,
        shareOfVoice: self.shareOfVoice,
      },
      competitors,
    };
  }
  ```

  ```python Python theme={null}
  def build_competitive_landscape(client, brand_id: str, period: int = 30) -> dict:
      data = client.get_competitors(
          brand_id, period=period, limit=100,
          sort='shareOfVoice', order='desc',
      )

      self_brand = next(
          (item for item in data['competitors']
           if item['relationship'] == 'SELF'),
          None,
      )
      if self_brand is None:
          raise ValueError('SELF brand is absent from the selected scope')

      competitors = [
          {
              'id': item['id'],
              'name': item['name'],
              'mentions': item['totalMentions'],
              'share_of_voice': item['shareOfVoice'],
              'share_of_voice_gap': round(
                  item['shareOfVoice'] - self_brand['shareOfVoice'], 2
              ),
              'average_position': item['avgPosition'],
              'sentiment': item['avgSentiment'],
          }
          for item in data['competitors']
          if item['relationship'] == 'DIRECT'
      ]

      return {
          'period': period,
          'self': {
              'id': self_brand['id'],
              'name': self_brand['name'],
              'mentions': self_brand['totalMentions'],
              'share_of_voice': self_brand['shareOfVoice'],
          },
          'competitors': competitors,
      }
  ```
</CodeGroup>

The Python wrapper does not expose the `relationship` query parameter. It therefore filters the response after retrieval.

## Track one competitor over time

Report the observed difference without assigning a universal significance threshold. If your organization uses a materiality threshold, pass it as an explicit business rule and document its owner.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function compareCompetitorEndpoints(
    client,
    brandId,
    competitorId,
    period = 30
  ) {
    const result = await client.getCompetitorEvolution(
      brandId,
      competitorId,
      { period }
    );
    const points = result.evolution;

    if (points.length < 2) {
      return { status: 'insufficient_data', points };
    }

    const first = points[0];
    const last = points.at(-1);
    const shareOfVoiceChange = Number(
      (last.shareOfVoice - first.shareOfVoice).toFixed(2)
    );

    return {
      status: 'observed',
      competitor: result.competitor,
      window: { start: first.date, end: last.date },
      shareOfVoice: {
        start: first.shareOfVoice,
        end: last.shareOfVoice,
        changePoints: shareOfVoiceChange,
        direction: shareOfVoiceChange > 0
          ? 'increased'
          : shareOfVoiceChange < 0
            ? 'decreased'
            : 'unchanged',
      },
      mentionChange: last.mentions - first.mentions,
      points,
    };
  }
  ```

  ```python Python theme={null}
  def compare_competitor_endpoints(
      client, brand_id: str, competitor_id: str, period: int = 30
  ) -> dict:
      result = client.get_competitor_evolution(
          brand_id, competitor_id, period=period
      )
      points = result['evolution']
      if len(points) < 2:
          return {'status': 'insufficient_data', 'points': points}

      first = points[0]
      last = points[-1]
      share_of_voice_change = round(
          last['shareOfVoice'] - first['shareOfVoice'], 2
      )
      direction = (
          'increased' if share_of_voice_change > 0
          else 'decreased' if share_of_voice_change < 0
          else 'unchanged'
      )

      return {
          'status': 'observed',
          'competitor': result['competitor'],
          'window': {'start': first['date'], 'end': last['date']},
          'share_of_voice': {
              'start': first['shareOfVoice'],
              'end': last['shareOfVoice'],
              'change_points': share_of_voice_change,
              'direction': direction,
          },
          'mention_change': last['mentions'] - first['mentions'],
          'points': points,
      }
  ```
</CodeGroup>

## Interpret the result

* A positive gap means the competitor has a higher Share of Voice in the selected API scope. It is not market share.
* Mention counts, average position, sentiment, and citations answer different questions. Do not collapse them into a single causal explanation.
* Compare evolution only when prompt, provider, topic, tag, and date scopes are equivalent.
* A launch, campaign, or content change near the same date is a hypothesis to investigate, not a cause established by this endpoint.
* Inspect stored answers and sources before choosing an action.

## Related pages

* [List competitors](/developers/endpoints/competitors/list)
* [Get competitor](/developers/endpoints/competitors/get)
* [Competitor evolution](/developers/endpoints/competitors/evolution)
* [Get performance snapshot](/developers/endpoints/performance)
* [Custom dashboard](/developers/guides/custom-dashboard)


# Custom dashboard
Source: https://docs.qwairy.co/developers/guides/custom-dashboard

Build a dashboard from performance, competitor, source, answer, and query fan-out data.

Build a dashboard that keeps each API surface's metric scope visible. This guide uses the reusable client from the [Quick start](/developers/guides/index#api-client).

## Fetch the overview

Request performance, competitors, and source domains with the same period. Keep the returned methodology with the displayed scores so readers can see the response and provider scope.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchDashboardData(client, brandId, period = 30) {
    const [performance, competitorData, sourceData] = await Promise.all([
      client.getPerformance(brandId, { period }),
      client.getCompetitors(brandId, {
        period,
        relationship: 'SELF,DIRECT',
        limit: 100,
        sort: 'shareOfVoice',
        order: 'desc',
      }),
      client.getSourceDomains(brandId, {
        period,
        limit: 20,
        sort: 'mentions',
        order: 'desc',
      }),
    ]);

    const self = competitorData.competitors.find(
      (item) => item.relationship === 'SELF'
    );
    const direct = competitorData.competitors.filter(
      (item) => item.relationship === 'DIRECT'
    );

    return {
      scores: performance.scores,
      methodology: performance.methodology,
      self: self ?? null,
      competitors: direct.map((item) => ({
        id: item.id,
        name: item.name,
        mentions: item.totalMentions,
        shareOfVoice: item.shareOfVoice,
        shareOfVoiceGap: self
          ? Number((item.shareOfVoice - self.shareOfVoice).toFixed(2))
          : null,
      })),
      sources: sourceData.sources.map((item) => ({
        domain: item.domain,
        citations: item.totalMentions,
        citationShare: item.rate,
        isSelf: item.isSelf,
      })),
    };
  }
  ```

  ```python Python theme={null}
  def fetch_dashboard_data(client, brand_id: str, period: int = 30) -> dict:
      performance = client.get_performance(brand_id, period=period)
      competitor_data = client.get_competitors(
          brand_id, period=period, limit=100,
          sort='shareOfVoice', order='desc',
      )
      source_data = client.get_source_domains(
          brand_id, period=period, limit=20,
          sort='mentions', order='desc',
      )

      self_brand = next(
          (item for item in competitor_data['competitors']
           if item['relationship'] == 'SELF'),
          None,
      )
      direct = [
          item for item in competitor_data['competitors']
          if item['relationship'] == 'DIRECT'
      ]

      return {
          'scores': performance['scores'],
          'methodology': performance['methodology'],
          'self': self_brand,
          'competitors': [
              {
                  'id': item['id'],
                  'name': item['name'],
                  'mentions': item['totalMentions'],
                  'share_of_voice': item['shareOfVoice'],
                  'share_of_voice_gap': round(
                      item['shareOfVoice'] - self_brand['shareOfVoice'], 2
                  ) if self_brand else None,
              }
              for item in direct
          ],
          'sources': [
              {
                  'domain': item['domain'],
                  'citations': item['totalMentions'],
                  'citation_share': item['rate'],
                  'is_self': item['isSelf'],
              }
              for item in source_data['sources']
          ],
      }
  ```
</CodeGroup>

The Python client in the Quick start does not expose the `relationship` argument. Filter the returned list as shown, or extend the wrapper to pass that query parameter.

## Label the metrics by surface

Do not replace these definitions with similarly named dashboard, export, MCP, or Looker Studio formulas.

| Field                 | REST performance scope                                                  |
| --------------------- | ----------------------------------------------------------------------- |
| `scores.mentionRate`  | SELF-mentioned answers divided by answers with a SELF or DIRECT mention |
| `scores.sourceRate`   | SELF-citing answers divided by answers with a SELF or DIRECT citation   |
| `scores.coverage`     | SELF-mentioned answers divided by all answers in the selected API scope |
| `scores.shareOfVoice` | SELF mention occurrences divided by SELF plus DIRECT occurrences        |
| `scores.sentiment`    | Average SELF sentiment on the `0` to `100` scale                        |

Show `methodology.responsesTotal`, `methodology.promptsCount`, and `methodology.providers` near the score cards. A change in those values can make two periods non-comparable.

## Add response diagnostics

The Answers endpoint applies `hasSelfSource=true`, but currently ignores the inverse value `false`. Request SELF-mentioned answers and filter the returned `hasSelfSource` flag in your client.

```javascript JavaScript theme={null}
async function fetchDiagnostics(client, brandId, period = 30) {
  const [answerData, searchData] = await Promise.all([
    client.getAnswers(brandId, {
      period,
      hasSelfMention: true,
      limit: 100,
      sort: 'createdAt',
      order: 'desc',
    }),
    client.getSearch(brandId, {
      period,
      limit: 20,
      sort: 'occurrences',
      order: 'desc',
    }),
  ]);

  return {
    sampledMentionWithoutCitation: answerData.answers
      .filter((answer) => !answer.hasSelfSource)
      .map((answer) => ({
        prompt: answer.promptText,
        provider: answer.provider,
        position: answer.selfMentionPosition,
      })),
    queryFanOut: searchData.searches.map((record) => ({
      query: record.query,
      occurrences: record.occurrences,
      prompts: record.prompts.map((prompt) => prompt.text),
      models: record.models,
    })),
  };
}
```

<Note>
  The answer diagnostic is limited to the requested page. Its length is not the total number of matching answers. Paginate before calculating a complete count.
</Note>

## Verify the dashboard

1. Display the selected period and API methodology.
2. Confirm that SELF and DIRECT relationships are not mixed with other competitor types.
3. Treat a Share of Voice gap as a difference in the selected answer set, not market share.
4. Keep answer citations, query fan-out, and competitor mentions as separate observations.
5. Compare equivalent filters and prompt sets before labeling a trend.

## Related pages

* [Get performance snapshot](/developers/endpoints/performance)
* [List competitors](/developers/endpoints/competitors/list)
* [List source domains](/developers/endpoints/source-domains/list)
* [List answers](/developers/endpoints/answers/list)
* [List query fan-out records](/developers/endpoints/search)


# Data export
Source: https://docs.qwairy.co/developers/guides/data-export

Export GEO data to CSV, JSON, and BI tools like BigQuery or Snowflake.

Export your Qwairy data for analysis in spreadsheets, databases, or BI platforms.

<Note>
  This guide uses the API client from the [Guides index](/developers/guides/index#api-client). Copy it to your project first.
</Note>

## What you'll build

Export pipelines for:

* **CSV files**: For Excel, Google Sheets
* **JSON files**: For data pipelines
* **BigQuery**: For Google Cloud analytics
* **Snowflake**: For enterprise data warehousing

***

## Fetch all data

First, gather data from all endpoints.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchAllData(client, brandId, period = 30) {
    const [performance, competitors, sources] = await Promise.all([
      client.getPerformance(brandId, { period }),
      client.getCompetitors(brandId, { period, limit: 100 }),
      client.getSourceDomains(brandId, { period, limit: 100 }),
    ]);

    return {
      exportedAt: new Date().toISOString(),
      brandId,
      period,
      performance: {
        scores: performance.scores,
        methodology: performance.methodology,
      },
      competitors: competitors.competitors.map(c => ({
        id: c.id,
        name: c.name,
        relationship: c.relationship,
        shareOfVoice: c.shareOfVoice,
        totalMentions: c.totalMentions,
        avgPosition: c.avgPosition,
        avgSentiment: c.avgSentiment,
      })),
      sources: sources.sources.map(s => ({
        id: s.id,
        domain: s.domain,
        type: s.type,
        isSelf: s.isSelf,
        totalMentions: s.totalMentions,
        rate: s.rate,
        avgPosition: s.avgPosition,
      })),
    };
  }
  ```

  ```python Python theme={null}
  def fetch_all_data(client, brand_id: str, period: int = 30) -> dict:
      """Fetch all data for export."""
      from concurrent.futures import ThreadPoolExecutor
      from datetime import datetime

      with ThreadPoolExecutor(max_workers=3) as executor:
          perf_future = executor.submit(client.get_performance, brand_id, period=period)
          comp_future = executor.submit(client.get_competitors, brand_id, period=period, limit=100)
          src_future = executor.submit(client.get_source_domains, brand_id, period=period, limit=100)

          performance = perf_future.result()
          competitors = comp_future.result()
          sources = src_future.result()

      return {
          'exported_at': datetime.now().isoformat(),
          'brand_id': brand_id,
          'period': period,
          'performance': {
              'scores': performance['scores'],
              'methodology': performance['methodology'],
          },
          'competitors': [
              {
                  'id': c['id'],
                  'name': c['name'],
                  'relationship': c['relationship'],
                  'share_of_voice': c['shareOfVoice'],
                  'total_mentions': c['totalMentions'],
                  'avg_position': c['avgPosition'],
                  'avg_sentiment': c['avgSentiment'],
              }
              for c in competitors['competitors']
          ],
          'sources': [
              {
                  'id': s['id'],
                  'domain': s['domain'],
                  'type': s['type'],
                  'is_self': s['isSelf'],
                  'total_mentions': s['totalMentions'],
                  'rate': s['rate'],
                  'avg_position': s['avgPosition'],
              }
              for s in sources['sources']
          ],
      }
  ```
</CodeGroup>

***

## Export to CSV

<CodeGroup>
  ```javascript JavaScript theme={null}
  const fs = require('fs');

  function exportToCSV(data, outputDir = './exports') {
    if (!fs.existsSync(outputDir)) {
      fs.mkdirSync(outputDir, { recursive: true });
    }

    const timestamp = data.exportedAt.split('T')[0];

    // Competitors CSV
    const competitorHeaders = ['id', 'name', 'relationship', 'shareOfVoice', 'totalMentions', 'avgPosition', 'avgSentiment'];
    const competitorRows = data.competitors.map(c => competitorHeaders.map(h => c[h]).join(','));
    fs.writeFileSync(
      `${outputDir}/competitors_${timestamp}.csv`,
      [competitorHeaders.join(','), ...competitorRows].join('\n')
    );

    // Sources CSV
    const sourceHeaders = ['id', 'domain', 'type', 'isSelf', 'totalMentions', 'rate', 'avgPosition'];
    const sourceRows = data.sources.map(s => sourceHeaders.map(h => s[h]).join(','));
    fs.writeFileSync(
      `${outputDir}/sources_${timestamp}.csv`,
      [sourceHeaders.join(','), ...sourceRows].join('\n')
    );

    // Performance CSV (single row)
    const perfHeaders = ['mentionRate', 'sourceRate', 'coverage', 'shareOfVoice', 'sentiment'];
    const perfValues = [
      data.performance.scores.mentionRate,
      data.performance.scores.sourceRate,
      data.performance.scores.coverage,
      data.performance.scores.shareOfVoice,
      data.performance.scores.sentiment,
    ];
    fs.writeFileSync(
      `${outputDir}/performance_${timestamp}.csv`,
      [perfHeaders.join(','), perfValues.join(',')].join('\n')
    );

    return {
      files: [
        `${outputDir}/competitors_${timestamp}.csv`,
        `${outputDir}/sources_${timestamp}.csv`,
        `${outputDir}/performance_${timestamp}.csv`,
      ],
    };
  }
  ```

  ```python Python theme={null}
  import csv
  import os


  def export_to_csv(data: dict, output_dir: str = './exports') -> dict:
      """Export data to CSV files."""
      os.makedirs(output_dir, exist_ok=True)
      timestamp = data['exported_at'].split('T')[0]
      files = []

      # Competitors CSV
      comp_file = f'{output_dir}/competitors_{timestamp}.csv'
      with open(comp_file, 'w', newline='') as f:
          if data['competitors']:
              writer = csv.DictWriter(f, fieldnames=data['competitors'][0].keys())
              writer.writeheader()
              writer.writerows(data['competitors'])
      files.append(comp_file)

      # Sources CSV
      src_file = f'{output_dir}/sources_{timestamp}.csv'
      with open(src_file, 'w', newline='') as f:
          if data['sources']:
              writer = csv.DictWriter(f, fieldnames=data['sources'][0].keys())
              writer.writeheader()
              writer.writerows(data['sources'])
      files.append(src_file)

      # Performance CSV
      perf_file = f'{output_dir}/performance_{timestamp}.csv'
      scores = data['performance']['scores']
      with open(perf_file, 'w', newline='') as f:
          writer = csv.DictWriter(f, fieldnames=['mention_rate', 'source_rate', 'coverage', 'share_of_voice', 'sentiment'])
          writer.writeheader()
          writer.writerow({
              'mention_rate': scores['mentionRate'],
              'source_rate': scores['sourceRate'],
              'coverage': scores['coverage'],
              'share_of_voice': scores['shareOfVoice'],
              'sentiment': scores['sentiment'],
          })
      files.append(perf_file)

      return {'files': files}
  ```
</CodeGroup>

***

## Export to JSON

<CodeGroup>
  ```javascript JavaScript theme={null}
  const fs = require('fs');

  function exportToJSON(data, outputDir = './exports') {
    if (!fs.existsSync(outputDir)) {
      fs.mkdirSync(outputDir, { recursive: true });
    }

    const timestamp = data.exportedAt.split('T')[0];
    const filepath = `${outputDir}/qwairy_export_${timestamp}.json`;

    fs.writeFileSync(filepath, JSON.stringify(data, null, 2));

    return { file: filepath, size: fs.statSync(filepath).size };
  }
  ```

  ```python Python theme={null}
  import json
  import os


  def export_to_json(data: dict, output_dir: str = './exports') -> dict:
      """Export data to JSON file."""
      os.makedirs(output_dir, exist_ok=True)
      timestamp = data['exported_at'].split('T')[0]
      filepath = f'{output_dir}/qwairy_export_{timestamp}.json'

      with open(filepath, 'w') as f:
          json.dump(data, f, indent=2)

      return {'file': filepath, 'size': os.path.getsize(filepath)}
  ```
</CodeGroup>

***

## Database schemas

Create these tables before exporting to BigQuery or Snowflake.

<CodeGroup>
  ```sql BigQuery theme={null}
  -- Create dataset
  CREATE SCHEMA IF NOT EXISTS qwairy;

  -- Competitors table
  CREATE TABLE IF NOT EXISTS qwairy.competitors (
    id STRING NOT NULL,
    name STRING NOT NULL,
    relationship STRING,
    share_of_voice FLOAT64,
    total_mentions INT64,
    avg_position FLOAT64,
    avg_sentiment FLOAT64,
    exported_at TIMESTAMP NOT NULL,
    brand_id STRING NOT NULL
  );

  -- Sources table
  CREATE TABLE IF NOT EXISTS qwairy.sources (
    id STRING NOT NULL,
    domain STRING NOT NULL,
    type STRING,
    is_self BOOL,
    total_mentions INT64,
    rate FLOAT64,
    avg_position FLOAT64,
    exported_at TIMESTAMP NOT NULL,
    brand_id STRING NOT NULL
  );

  -- Performance table
  CREATE TABLE IF NOT EXISTS qwairy.performance (
    mentionRate FLOAT64,
    sourceRate FLOAT64,
    coverage FLOAT64,
    shareOfVoice FLOAT64,
    sentiment FLOAT64,
    methodology STRING,
    exported_at TIMESTAMP NOT NULL,
    brand_id STRING NOT NULL
  );
  ```

  ```sql Snowflake theme={null}
  -- Create schema
  CREATE SCHEMA IF NOT EXISTS QWAIRY;

  -- Competitors table
  CREATE TABLE IF NOT EXISTS QWAIRY.COMPETITORS (
    ID VARCHAR(50) NOT NULL,
    NAME VARCHAR(255) NOT NULL,
    RELATIONSHIP VARCHAR(50),
    SHARE_OF_VOICE FLOAT,
    TOTAL_MENTIONS INTEGER,
    AVG_POSITION FLOAT,
    AVG_SENTIMENT FLOAT,
    EXPORTED_AT TIMESTAMP_NTZ NOT NULL,
    BRAND_ID VARCHAR(50) NOT NULL
  );

  -- Sources table
  CREATE TABLE IF NOT EXISTS QWAIRY.SOURCES (
    ID VARCHAR(50) NOT NULL,
    DOMAIN VARCHAR(255) NOT NULL,
    TYPE VARCHAR(50),
    IS_SELF BOOLEAN,
    TOTAL_MENTIONS INTEGER,
    RATE FLOAT,
    AVG_POSITION FLOAT,
    EXPORTED_AT TIMESTAMP_NTZ NOT NULL,
    BRAND_ID VARCHAR(50) NOT NULL
  );

  -- Performance table
  CREATE TABLE IF NOT EXISTS QWAIRY.PERFORMANCE (
    MENTION_RATE FLOAT,
    SOURCE_RATE FLOAT,
    COVERAGE FLOAT,
    SHARE_OF_VOICE FLOAT,
    SENTIMENT FLOAT,
    METHODOLOGY VARCHAR(5000),
    EXPORTED_AT TIMESTAMP_NTZ NOT NULL,
    BRAND_ID VARCHAR(50) NOT NULL
  );
  ```
</CodeGroup>

***

## Export to BigQuery

<CodeGroup>
  ```javascript JavaScript theme={null}
  const { BigQuery } = require('@google-cloud/bigquery');

  async function exportToBigQuery(data, datasetId = 'qwairy', projectId = process.env.GCP_PROJECT_ID) {
    const bigquery = new BigQuery({ projectId });

    // Create dataset if not exists
    const [datasets] = await bigquery.getDatasets();
    if (!datasets.find(d => d.id === datasetId)) {
      await bigquery.createDataset(datasetId);
    }

    const dataset = bigquery.dataset(datasetId);

    // Insert competitors
    await dataset.table('competitors').insert(
      data.competitors.map(c => ({
        ...c,
        exportedAt: data.exportedAt,
        brandId: data.brandId,
      }))
    );

    // Insert sources
    await dataset.table('sources').insert(
      data.sources.map(s => ({
        ...s,
        exportedAt: data.exportedAt,
        brandId: data.brandId,
      }))
    );

    // Insert performance
    await dataset.table('performance').insert([{
      ...data.performance.scores,
      methodology: JSON.stringify(data.performance.methodology),
      exportedAt: data.exportedAt,
      brandId: data.brandId,
    }]);

    return { dataset: datasetId, tables: ['competitors', 'sources', 'performance'] };
  }
  ```

  ```python Python theme={null}
  from google.cloud import bigquery


  def export_to_bigquery(data: dict, dataset_id: str = 'qwairy', project_id: str = None) -> dict:
      """Export data to BigQuery."""
      import os
      import json

      project_id = project_id or os.environ.get('GCP_PROJECT_ID')
      client = bigquery.Client(project=project_id)

      # Create dataset if not exists
      dataset_ref = client.dataset(dataset_id)
      try:
          client.get_dataset(dataset_ref)
      except Exception:
          client.create_dataset(dataset_ref)

      # Insert competitors
      competitors_table = f'{project_id}.{dataset_id}.competitors'
      rows = [
          {**c, 'exported_at': data['exported_at'], 'brand_id': data['brand_id']}
          for c in data['competitors']
      ]
      if rows:
          client.insert_rows_json(competitors_table, rows)

      # Insert sources
      sources_table = f'{project_id}.{dataset_id}.sources'
      rows = [
          {**s, 'exported_at': data['exported_at'], 'brand_id': data['brand_id']}
          for s in data['sources']
      ]
      if rows:
          client.insert_rows_json(sources_table, rows)

      # Insert performance
      perf_table = f'{project_id}.{dataset_id}.performance'
      perf_row = {
          **data['performance']['scores'],
          'methodology': json.dumps(data['performance']['methodology']),
          'exported_at': data['exported_at'],
          'brand_id': data['brand_id'],
      }
      client.insert_rows_json(perf_table, [perf_row])

      return {'dataset': dataset_id, 'tables': ['competitors', 'sources', 'performance']}
  ```
</CodeGroup>

***

## Export to Snowflake

<CodeGroup>
  ```javascript JavaScript theme={null}
  const snowflake = require('snowflake-sdk');

  async function exportToSnowflake(data, config) {
    const connection = snowflake.createConnection({
      account: config.account,
      username: config.username,
      password: config.password,
      warehouse: config.warehouse,
      database: config.database,
      schema: config.schema || 'QWAIRY',
    });

    await new Promise((resolve, reject) => {
      connection.connect((err) => err ? reject(err) : resolve());
    });

    const execute = (sql, binds = []) => new Promise((resolve, reject) => {
      connection.execute({ sqlText: sql, binds, complete: (err, stmt, rows) => err ? reject(err) : resolve(rows) });
    });

    // Insert competitors
    for (const c of data.competitors) {
      await execute(
        `INSERT INTO competitors (id, name, relationship, share_of_voice, total_mentions, avg_position, avg_sentiment, exported_at, brand_id)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
        [c.id, c.name, c.relationship, c.shareOfVoice, c.totalMentions, c.avgPosition, c.avgSentiment, data.exportedAt, data.brandId]
      );
    }

    // Insert sources
    for (const s of data.sources) {
      await execute(
        `INSERT INTO sources (id, domain, type, is_self, total_mentions, rate, avg_position, exported_at, brand_id)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
        [s.id, s.domain, s.type, s.isSelf, s.totalMentions, s.rate, s.avgPosition, data.exportedAt, data.brandId]
      );
    }

    connection.destroy();
    return { schema: config.schema || 'QWAIRY', tables: ['competitors', 'sources'] };
  }
  ```

  ```python Python theme={null}
  import snowflake.connector


  def export_to_snowflake(data: dict, config: dict) -> dict:
      """Export data to Snowflake."""
      conn = snowflake.connector.connect(
          account=config['account'],
          user=config['username'],
          password=config['password'],
          warehouse=config['warehouse'],
          database=config['database'],
          schema=config.get('schema', 'QWAIRY'),
      )
      cursor = conn.cursor()

      # Insert competitors
      for c in data['competitors']:
          cursor.execute(
              '''INSERT INTO competitors (id, name, relationship, share_of_voice, total_mentions, avg_position, avg_sentiment, exported_at, brand_id)
                 VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)''',
              (c['id'], c['name'], c['relationship'], c['share_of_voice'], c['total_mentions'],
               c['avg_position'], c['avg_sentiment'], data['exported_at'], data['brand_id'])
          )

      # Insert sources
      for s in data['sources']:
          cursor.execute(
              '''INSERT INTO sources (id, domain, type, is_self, total_mentions, rate, avg_position, exported_at, brand_id)
                 VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s)''',
              (s['id'], s['domain'], s['type'], s['is_self'], s['total_mentions'],
               s['rate'], s['avg_position'], data['exported_at'], data['brand_id'])
          )

      conn.commit()
      cursor.close()
      conn.close()

      return {'schema': config.get('schema', 'QWAIRY'), 'tables': ['competitors', 'sources']}
  ```
</CodeGroup>

***

## Usage

<CodeGroup>
  ```javascript JavaScript theme={null}
  const client = new QwairyClient(process.env.QWAIRY_API_TOKEN);

  // Fetch data
  const data = await fetchAllData(client, 'your-brand-id', 30);

  // Export to files
  const csvResult = exportToCSV(data);
  console.log('CSV files:', csvResult.files);

  const jsonResult = exportToJSON(data);
  console.log('JSON file:', jsonResult.file, `(${jsonResult.size} bytes)`);

  // Export to BigQuery (requires @google-cloud/bigquery)
  // const bqResult = await exportToBigQuery(data);
  // console.log('BigQuery tables:', bqResult.tables);
  ```

  ```python Python theme={null}
  client = QwairyClient()

  # Fetch data
  data = fetch_all_data(client, 'your-brand-id', period=30)

  # Export to files
  csv_result = export_to_csv(data)
  print(f"CSV files: {csv_result['files']}")

  json_result = export_to_json(data)
  print(f"JSON file: {json_result['file']} ({json_result['size']} bytes)")

  # Export to BigQuery (requires google-cloud-bigquery)
  # bq_result = export_to_bigquery(data)
  # print(f"BigQuery tables: {bq_result['tables']}")
  ```
</CodeGroup>

***

## Schedule exports

Automate daily or weekly exports:

| Platform           | Configuration                     |
| ------------------ | --------------------------------- |
| **Cron**           | `0 1 * * *` (daily at 1am)        |
| **GitHub Actions** | `schedule: cron: '0 1 * * *'`     |
| **AWS Lambda**     | EventBridge scheduled rule        |
| **Google Cloud**   | Cloud Scheduler + Cloud Functions |

***

## Next steps

* Create a [custom dashboard](/developers/guides/custom-dashboard) for on-demand monitoring
* Set up [weekly reports](/developers/guides/weekly-reports) for stakeholders
* Add [competitive analysis](/developers/guides/competitive-analysis) to your exports


# Quick start
Source: https://docs.qwairy.co/developers/guides/index

Make your first Qwairy API call, then build on the shared client and guides.

Go from an API token to your brand's performance scores in one call, then reuse the shared client and the worked guides for full integrations.

<Note>
  You need an API token (`Bearer qw-api-...`, Growth plan or above) and your brand ID. See [Authentication](/developers/authentication) to create a token and [List Brands](/developers/endpoints/brands/list) to find your brand ID.
</Note>

## Make your first request

Get your brand's performance scores in one command:

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -H "Authorization: Bearer $QWAIRY_API_TOKEN" \
    "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/performance?period=30" \
    | jq '.scores'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/performance?period=30',
    { headers: { 'Authorization': `Bearer ${process.env.QWAIRY_API_TOKEN}` } }
  );
  const { scores } = await response.json();
  console.log(`Mention Rate: ${scores.mentionRate}% | Share of Voice: ${scores.shareOfVoice}%`);
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      'https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/performance?period=30',
      headers={'Authorization': f'Bearer {os.environ["QWAIRY_API_TOKEN"]}'}
  )
  scores = response.json()['scores']
  print(f"Mention Rate: {scores['mentionRate']}% | Share of Voice: {scores['shareOfVoice']}%")
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "mentionRate": 45.2,
  "mentionCount": 104,
  "mentionTotal": 230,
  "coverage": 33.33,
  "sourceRate": 23.9,
  "sourceCount": 44,
  "sourceTotal": 184,
  "sourcePages": 27,
  "sentiment": 78.1,
  "shareOfVoice": 8.13
}
```

***

## Guides

Worked, copy-pasteable integrations built on the shared client below.

<CardGroup>
  <Card title="Custom Dashboard" icon="chart-line" href="/developers/guides/custom-dashboard">
    Build a branded GEO dashboard with KPIs and competitor rankings
  </Card>

  <Card title="Weekly Reports" icon="calendar-week" href="/developers/guides/weekly-reports">
    Automate week-over-week performance reports
  </Card>

  <Card title="Competitive Analysis" icon="ranking-star" href="/developers/guides/competitive-analysis">
    Track your position against competitors
  </Card>

  <Card title="Data Export" icon="database" href="/developers/guides/data-export">
    Export data for BI tools (BigQuery, Snowflake, CSV)
  </Card>
</CardGroup>

***

## API client

Reusable client with error handling for all guides on this site.

<CodeGroup>
  ```javascript JavaScript theme={null}
  // qwairy-client.js
  class QwairyClient {
    constructor(apiToken) {
      this.baseUrl = 'https://www.qwairy.co/api/v1';
      this.headers = {
        'Authorization': `Bearer ${apiToken}`,
        'Content-Type': 'application/json',
      };
    }

    async request(endpoint, params = {}) {
      const url = new URL(`${this.baseUrl}${endpoint}`);
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== null) {
          url.searchParams.append(key, value);
        }
      });

      const response = await fetch(url.toString(), { headers: this.headers });

      if (!response.ok) {
        const body = await response.json().catch(() => ({}));

        if (response.status === 429) {
          const retryAfter = Number(response.headers.get('Retry-After') ?? '60');
          throw new Error(`Rate limited. Retry after ${retryAfter} second(s).`);
        }

        const nested = typeof body.error === 'object' ? body.error : null;
        const code = nested?.code ?? `HTTP_${response.status}`;
        const message = nested?.message ?? body.message ?? body.error ?? `HTTP ${response.status}`;
        throw new Error(`[${code}] ${message}`);
      }

      return response.json();
    }

    async getPerformance(brandId, params = {}) {
      return this.request(`/brands/${brandId}/performance`, params);
    }

    async getCompetitors(brandId, params = {}) {
      return this.request(`/brands/${brandId}/competitors`, params);
    }

    async getSourceDomains(brandId, params = {}) {
      return this.request(`/brands/${brandId}/source-domains`, params);
    }

    async getSourceUrls(brandId, params = {}) {
      return this.request(`/brands/${brandId}/source-urls`, params);
    }

    async getAnswers(brandId, params = {}) {
      return this.request(`/brands/${brandId}/answers`, params);
    }

    async getSearch(brandId, params = {}) {
      return this.request(`/brands/${brandId}/search`, params);
    }

    async getPerception(brandId, params = {}) {
      return this.request(`/brands/${brandId}/perception`, params);
    }

    async getContent(brandId, params = {}) {
      return this.request(`/brands/${brandId}/content`, params);
    }

    async getTechnicalAnalysis(brandId, params = {}) {
      return this.request(`/brands/${brandId}/technical-analysis`, params);
    }

    async getCompetitorEvolution(brandId, competitorId, params = {}) {
      return this.request(`/brands/${brandId}/competitors/${competitorId}/evolution`, params);
    }
  }

  // Usage
  const client = new QwairyClient(process.env.QWAIRY_API_TOKEN);
  ```

  ```python Python theme={null}
  # qwairy_client.py
  import requests
  import os
  from typing import Optional, Dict, Any


  class QwairyError(Exception):
      """Custom exception for Qwairy API errors."""
      def __init__(self, code: str, message: str, status_code: int):
          self.code = code
          self.message = message
          self.status_code = status_code
          super().__init__(f"[{code}] {message}")


  class QwairyClient:
      def __init__(self, api_token: Optional[str] = None):
          self.base_url = 'https://www.qwairy.co/api/v1'
          self.api_token = api_token or os.environ.get('QWAIRY_API_TOKEN')
          if not self.api_token:
              raise ValueError("API token required. Set QWAIRY_API_TOKEN or pass to constructor.")

          self.session = requests.Session()
          self.session.headers.update({
              'Authorization': f'Bearer {self.api_token}',
              'Content-Type': 'application/json',
          })

      def _request(self, endpoint: str, params: Optional[Dict] = None) -> Dict[str, Any]:
          url = f"{self.base_url}{endpoint}"
          clean_params = {k: v for k, v in (params or {}).items() if v is not None}
          response = self.session.get(url, params=clean_params)

          if not response.ok:
              try:
                  error_data = response.json() if response.content else {}
              except ValueError:
                  error_data = {}

              if response.status_code == 429:
                  retry_after = int(response.headers.get('Retry-After', '60'))
                  raise QwairyError(
                      'RATE_LIMITED',
                      f'Retry after {retry_after} second(s).',
                      429,
                  )

              error = error_data.get('error')
              nested = error if isinstance(error, dict) else {}
              code = nested.get('code', f'HTTP_{response.status_code}')
              message = nested.get('message') or error_data.get('message') or (
                  error if isinstance(error, str) else f'HTTP {response.status_code}'
              )
              raise QwairyError(code, message, response.status_code)

          return response.json()

      def get_performance(self, brand_id: str, period: Optional[int] = None,
                          start_date: Optional[str] = None, end_date: Optional[str] = None) -> Dict:
          return self._request(f'/brands/{brand_id}/performance', {
              'period': period, 'startDate': start_date, 'endDate': end_date,
          })

      def get_competitors(self, brand_id: str, period: Optional[int] = None,
                          limit: int = 50, offset: int = 0,
                          sort: str = 'mentions', order: str = 'desc') -> Dict:
          return self._request(f'/brands/{brand_id}/competitors', {
              'period': period, 'limit': limit, 'offset': offset, 'sort': sort, 'order': order,
          })

      def get_source_domains(self, brand_id: str, period: Optional[int] = None,
                             limit: int = 50, offset: int = 0,
                             sort: str = 'mentions', order: str = 'desc') -> Dict:
          return self._request(f'/brands/{brand_id}/source-domains', {
              'period': period, 'limit': limit, 'offset': offset, 'sort': sort, 'order': order,
          })

      def get_source_urls(self, brand_id: str, period: Optional[int] = None,
                          limit: int = 50, offset: int = 0,
                          sort: str = 'mentions', order: str = 'desc') -> Dict:
          return self._request(f'/brands/{brand_id}/source-urls', {
              'period': period, 'limit': limit, 'offset': offset, 'sort': sort, 'order': order,
          })

      def get_answers(self, brand_id: str, period: Optional[int] = None,
                      limit: int = 50, offset: int = 0,
                      provider: Optional[str] = None,
                      has_self_mention: Optional[bool] = None,
                      has_self_source: Optional[bool] = None) -> Dict:
          return self._request(f'/brands/{brand_id}/answers', {
              'period': period, 'limit': limit, 'offset': offset,
              'provider': provider, 'hasSelfMention': has_self_mention, 'hasSelfSource': has_self_source,
          })

      def get_search(self, brand_id: str, period: Optional[int] = None,
                     limit: int = 50, offset: int = 0,
                     provider: Optional[str] = None) -> Dict:
          return self._request(f'/brands/{brand_id}/search', {
              'period': period, 'limit': limit, 'offset': offset, 'provider': provider,
          })

      def get_perception(self, brand_id: str, months: Optional[int] = None) -> Dict:
          return self._request(f'/brands/{brand_id}/perception', {
              'months': months,
          })

      def get_content(self, brand_id: str, status: Optional[str] = None,
                       limit: int = 50, offset: int = 0) -> Dict:
          return self._request(f'/brands/{brand_id}/content', {
              'status': status, 'limit': limit, 'offset': offset,
          })

      def get_technical_analysis(self, brand_id: str) -> Dict:
          return self._request(f'/brands/{brand_id}/technical-analysis', {})

      def get_competitor_evolution(self, brand_id: str, competitor_id: str,
                                    period: Optional[int] = None) -> Dict:
          return self._request(f'/brands/{brand_id}/competitors/{competitor_id}/evolution', {
              'period': period,
          })


  # Usage
  client = QwairyClient()
  ```
</CodeGroup>

<Note>
  All guides on this site use this client. Copy it to your project or adapt it to your needs.
</Note>

***

## TypeScript types

Type definitions for the API client.

```typescript theme={null}
// qwairy-types.ts
interface QwairyScores {
  mentionRate: number;
  mentionCount: number;
  mentionTotal: number;
  coverage: number;
  sourceRate: number;
  sourceCount: number;
  sourceTotal: number;
  sourcePages: number;
  sentiment: number;
  shareOfVoice: number;
}

interface QwairyMethodology {
  promptsCount: number;
  providersCount: number;
  providers: string[];
  responsesTotal: number;
  responsesWithMentions: number;
  responsesWithSources: number;
}

interface QwairyTopicBreakdown {
  id: string;
  topic: string;
  score: number;
  mentionRate: number;
  sourceRate: number;
  shareOfVoice: number;
  avgSentiment: number | null;
  promptsCount: number;
}

interface QwairyTagBreakdown {
  id: string;
  name: string;
  score: number;
  mentionRate: number;
  sourceRate: number;
  shareOfVoice: number;
  avgSentiment: number | null;
  promptsCount: number;
}

interface QwairyPerformance {
  success: boolean;
  brand: { id: string; name: string; domain: string | null };
  period: { start: string | null; end: string | null };
  scores: QwairyScores;
  methodology: QwairyMethodology;
  topCompetitors: QwairyCompetitor[];
  topSources: QwairySource[];
  byTopic?: QwairyTopicBreakdown[];
  byTag?: QwairyTagBreakdown[];
}

interface QwairyCompetitor {
  id: string;
  name: string;
  domain: string | null;
  relationship: 'SELF' | 'DIRECT' | 'INDIRECT';
  totalMentions: number;
  shareOfVoice: number;
  avgPosition: number | null;
  avgSentiment: number | null;
}

interface QwairySource {
  id: string;
  domain: string;
  type: 'INSTITUTIONAL' | 'COMMERCIAL' | 'MEDIA' | 'BLOG' | 'SOCIAL' | 'OTHER';
  isSelf: boolean;
  totalMentions: number;
  rate: number;
  avgPosition: number | null;
  aiSourceAuthorityScore: number | null;
}

interface QwairyPagination {
  total: number;
  count: number;
  limit: number;
  offset: number;
}

interface QwairyCompetitorsResponse {
  success: boolean;
  pagination: QwairyPagination;
  competitors: QwairyCompetitor[];
}

interface QwairySourcesResponse {
  success: boolean;
  pagination: QwairyPagination;
  sources: QwairySource[];
}

interface QwairyAnswer {
  id: string;
  promptId: string;
  promptText: string;
  provider: string;
  model: string;
  textPreview: string;
  hasSelfMention: boolean;
  selfMentionPosition: number | null;
  hasSelfSource: boolean;
  competitorsCount: number;
  sourcesCount: number;
  sentiment: number | null;
  createdAt: string;
}

interface QwairySearchQuery {
  query: string;
  occurrences: number;
  priority: 'very-high' | 'high' | 'medium' | 'low';
  brandPresence: number;
  competitorPresence: number;
  competitors: string[];
  uniquePrompts: number;
  prompts: Array<{ id: string; text: string }>;
  uniqueAnswers: number;
  uniqueModels: number;
  models: string[];
  topics: string[];
  tags: string[];
  firstSeen: string | null;
  lastSeen: string | null;
}

interface QwairyAnswersResponse {
  success: boolean;
  pagination: QwairyPagination;
  answers: QwairyAnswer[];
}

interface QwairySearchResponse {
  success: boolean;
  pagination: QwairyPagination;
  searches: QwairySearchQuery[];
}

interface QwairyPerceptionScores {
  sentiment: number | null;
  alignment: number | null;
  consistency: number | null;
  factualAlignment: number | null;
}

interface QwairyPerceptionResponse {
  success: boolean;
  current: { snapshotId: string; month: number; year: number; scores: QwairyPerceptionScores } | null;
  previous: { snapshotId: string; month: number; year: number; scores: QwairyPerceptionScores } | null;
  trends: QwairyPerceptionScores;
  averages: QwairyPerceptionScores;
}

interface QwairyArticle {
  id: string;
  title: string;
  slug: string | null;
  articleType: string;
  status: 'DRAFT' | 'GENERATING' | 'LIVE' | 'ARCHIVED';
  wordCount: number;
  finalUrl: string | null;
  publishedAt: string | null;
}

interface QwairyContentResponse {
  success: boolean;
  pagination: QwairyPagination;
  articles: QwairyArticle[];
}

interface QwairyTechnicalAnalysisResponse {
  success: boolean;
  analyzed: boolean;
  aiReadiness: { score: number; issuesCount: number; optimizationsCount: number } | null;
  robotsAnalysis: Record<string, unknown> | null;
  llmsAnalysis: Record<string, unknown> | null;
  sitemapAnalysis: Record<string, unknown> | null;
  lastAnalyzedAt: string | null;
}
```

***

## Pagination

Fetch all results when you have more than 100 items.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function fetchAllCompetitors(client, brandId, period = 30) {
    const allCompetitors = [];
    let offset = 0;
    const limit = 100;

    while (true) {
      const response = await client.getCompetitors(brandId, { period, limit, offset });
      allCompetitors.push(...response.competitors);

      if (response.competitors.length < limit || allCompetitors.length >= response.pagination.total) {
        break;
      }
      offset += limit;
    }

    return allCompetitors;
  }

  // Usage
  const allCompetitors = await fetchAllCompetitors(client, 'your-brand-id', 30);
  console.log(`Total competitors: ${allCompetitors.length}`);
  ```

  ```python Python theme={null}
  def fetch_all_competitors(client, brand_id: str, period: int = 30) -> list:
      """Fetch all competitors with pagination."""
      all_competitors = []
      offset = 0
      limit = 100

      while True:
          response = client.get_competitors(brand_id, period=period, limit=limit, offset=offset)
          all_competitors.extend(response['competitors'])

          if len(response['competitors']) < limit or len(all_competitors) >= response['pagination']['total']:
              break
          offset += limit

      return all_competitors

  # Usage
  all_competitors = fetch_all_competitors(client, 'your-brand-id', period=30)
  print(f"Total competitors: {len(all_competitors)}")
  ```
</CodeGroup>

***

## Field reference

Mapping between business metrics and API fields:

| Business metric                 | Endpoint              | Field                              | Description                                                                             |
| ------------------------------- | --------------------- | ---------------------------------- | --------------------------------------------------------------------------------------- |
| Mention Rate                    | `/performance`        | `scores.mentionRate`               | Responses with a SELF mention divided by responses with a SELF or DIRECT mention        |
| Citation Rate                   | `/performance`        | `scores.sourceRate`                | Responses with a SELF citation divided by responses with a SELF or DIRECT citation      |
| Coverage                        | `/performance`        | `scores.coverage`                  | Responses with a SELF mention divided by all responses in the selected scope            |
| Share of Voice                  | `/performance`        | `scores.shareOfVoice`              | SELF mention occurrences divided by SELF and DIRECT occurrences                         |
| Share of Voice (per competitor) | `/competitors`        | `shareOfVoice`                     | Competitor occurrence share in the endpoint's selected relationship set                 |
| Share of Citations              | `/source-domains`     | `rate`                             | Domain citation occurrences divided by all citation occurrences                         |
| Sentiment                       | `/performance`        | `scores.sentiment`                 | Average SELF sentiment score on the `0` to `100` scale                                  |
| Average Position                | `/competitors`        | `avgPosition`                      | Average rank in AI responses (1 = first)                                                |
| Mentioned but not cited         | `/answers`            | `hasSelfMention` + `hasSelfSource` | Request `hasSelfMention=true`, then client-filter rows where `hasSelfSource` is `false` |
| Query fan-out                   | `/search`             | `query`                            | Retained web queries associated with stored answers                                     |
| Perception scores               | `/perception`         | `current.scores`                   | Sentiment, alignment, consistency, factual alignment (0-100)                            |
| Content articles                | `/content`            | `articles`                         | Content Studio articles (Markdown via `/content/{id}`)                                  |
| Site Readiness Score            | `/technical-analysis` | `aiReadiness.score`                | Stored robots.txt, llms.txt, and sitemap.xml readiness (`0-100`)                        |

<Tip>
  Use `/performance` for aggregated KPIs. Use `/competitors` and `/source-domains` for detailed breakdowns. Use `/answers` and `/search` for LLM-level diagnostics. Use `/perception`, `/content` and `/technical-analysis` for reputation, content and technical readiness.
</Tip>


# Weekly reports
Source: https://docs.qwairy.co/developers/guides/weekly-reports

Compare two complete, non-overlapping seven-day API windows with explicit methodology.

Build a repeatable week-over-week report from two complete date windows that this guide defines in UTC. This guide uses the reusable client from the [Quick start](/developers/guides/index#api-client).

## Define comparable windows

For this report, construct inclusive UTC calendar-day windows. End the current window yesterday, then subtract six days. End the previous window one day before the current window begins.

<CodeGroup>
  ```javascript JavaScript theme={null}
  const DAY_MS = 24 * 60 * 60 * 1000;

  function isoDate(timestamp) {
    return new Date(timestamp).toISOString().slice(0, 10);
  }

  function completeSevenDayWindows(now = new Date()) {
    const todayUtc = Date.UTC(
      now.getUTCFullYear(),
      now.getUTCMonth(),
      now.getUTCDate()
    );
    const currentEnd = todayUtc - DAY_MS;
    const currentStart = currentEnd - 6 * DAY_MS;
    const previousEnd = currentStart - DAY_MS;
    const previousStart = previousEnd - 6 * DAY_MS;

    return {
      current: { startDate: isoDate(currentStart), endDate: isoDate(currentEnd) },
      previous: { startDate: isoDate(previousStart), endDate: isoDate(previousEnd) },
    };
  }
  ```

  ```python Python theme={null}
  from datetime import datetime, timedelta, timezone


  def complete_seven_day_windows() -> dict:
      today_utc = datetime.now(timezone.utc).date()
      current_end = today_utc - timedelta(days=1)
      current_start = current_end - timedelta(days=6)
      previous_end = current_start - timedelta(days=1)
      previous_start = previous_end - timedelta(days=6)

      return {
          'current': {
              'start_date': current_start.isoformat(),
              'end_date': current_end.isoformat(),
          },
          'previous': {
              'start_date': previous_start.isoformat(),
              'end_date': previous_end.isoformat(),
          },
      }
  ```
</CodeGroup>

This avoids a one-day overlap and excludes the partial current UTC day.

## Compare score points

Mention Rate, Source Rate, Coverage, and Share of Voice are percentage values. Sentiment is a score from `0` to `100`. Report an absolute point difference for all five rather than a relative percentage change, which becomes misleading near zero and is not meaningful for sentiment.

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function generateWeeklyReport(client, brandId, now = new Date()) {
    const windows = completeSevenDayWindows(now);
    const [current, previous] = await Promise.all([
      client.getPerformance(brandId, windows.current),
      client.getPerformance(brandId, windows.previous),
    ]);

    const metricKeys = [
      ['Mention Rate', 'mentionRate'],
      ['Source Rate', 'sourceRate'],
      ['Coverage', 'coverage'],
      ['Share of Voice', 'shareOfVoice'],
      ['Sentiment', 'sentiment'],
    ];

    const metrics = metricKeys.map(([name, key]) => {
      const currentValue = current.scores[key];
      const previousValue = previous.scores[key];
      const changePoints = Number((currentValue - previousValue).toFixed(2));
      return {
        name,
        current: currentValue,
        previous: previousValue,
        changePoints,
        direction: changePoints > 0
          ? 'increased'
          : changePoints < 0
            ? 'decreased'
            : 'unchanged',
      };
    });

    return {
      generatedAt: now.toISOString(),
      windows,
      metrics,
      methodology: {
        current: current.methodology,
        previous: previous.methodology,
      },
    };
  }
  ```

  ```python Python theme={null}
  def generate_weekly_report(client, brand_id: str) -> dict:
      windows = complete_seven_day_windows()
      current = client.get_performance(
          brand_id,
          start_date=windows['current']['start_date'],
          end_date=windows['current']['end_date'],
      )
      previous = client.get_performance(
          brand_id,
          start_date=windows['previous']['start_date'],
          end_date=windows['previous']['end_date'],
      )

      metric_keys = [
          ('Mention Rate', 'mentionRate'),
          ('Source Rate', 'sourceRate'),
          ('Coverage', 'coverage'),
          ('Share of Voice', 'shareOfVoice'),
          ('Sentiment', 'sentiment'),
      ]

      metrics = []
      for name, key in metric_keys:
          change_points = round(
              current['scores'][key] - previous['scores'][key], 2
          )
          direction = (
              'increased' if change_points > 0
              else 'decreased' if change_points < 0
              else 'unchanged'
          )
          metrics.append({
              'name': name,
              'current': current['scores'][key],
              'previous': previous['scores'][key],
              'change_points': change_points,
              'direction': direction,
          })

      return {
          'generated_at': datetime.now(timezone.utc).isoformat(),
          'windows': windows,
          'metrics': metrics,
          'methodology': {
              'current': current['methodology'],
              'previous': previous['methodology'],
          },
      }
  ```
</CodeGroup>

## Synthetic output

```json theme={null}
{
  "windows": {
    "current": { "startDate": "2026-07-14", "endDate": "2026-07-20" },
    "previous": { "startDate": "2026-07-07", "endDate": "2026-07-13" }
  },
  "metrics": [
    {
      "name": "Mention Rate",
      "current": 45.2,
      "previous": 42.1,
      "changePoints": 3.1,
      "direction": "increased"
    },
    {
      "name": "Sentiment",
      "current": 12.4,
      "previous": 10.1,
      "changePoints": 2.3,
      "direction": "increased"
    }
  ]
}
```

These labels describe the selected API windows only. They do not establish business impact or cause.

## Add diagnostics carefully

* Use [List answers](/developers/endpoints/answers/list) to inspect response-level changes. The endpoint does not apply `hasSelfSource=false`; filter the returned flag in your client and paginate before calculating a total.
* Use [List query fan-out records](/developers/endpoints/search) for aggregated query text. Each record exposes `prompts[]` and `models[]`, not singular `prompt` or `provider` fields.
* Keep citation, mention, query fan-out, and competitor movements as separate observations.

## Validate the comparison

1. Confirm the windows contain seven days each and do not overlap.
2. Compare `methodology.promptsCount`, `responsesTotal`, and `providers` between periods.
3. Explain prompt, provider, topic, or tag changes before interpreting a score delta.
4. Label every value with its REST performance formula.
5. Send the report only to destinations approved for the data it contains.

## Related pages

* [Get performance snapshot](/developers/endpoints/performance)
* [Custom dashboard](/developers/guides/custom-dashboard)
* [Competitive analysis](/developers/guides/competitive-analysis)
* [Data export](/developers/guides/data-export)


# Introduction
Source: https://docs.qwairy.co/developers/introduction

Start with Qwairy API v1 authentication, response shapes, pagination, and core endpoints.

Use API v1 to read the monitoring data available to your team, including answers, citations, competitors, and aggregate metrics.

<Note>
  API v1 requires an active **Growth** plan or above. [Review your subscription](https://www.qwairy.co/dashboard/team/billing) if authentication reports an insufficient plan.
</Note>

## Base URL

All API endpoints are relative to:

```
https://www.qwairy.co/api/v1
```

## Available endpoints

The API exposes these monitoring resources:

| Resource                                                    | Description                                                |
| ----------------------------------------------------------- | ---------------------------------------------------------- |
| [Brands](/developers/endpoints/brands/list)                 | List all brands in your account                            |
| [Performance](/developers/endpoints/performance)            | Read response-level visibility metrics                     |
| [Competitors](/developers/endpoints/competitors/list)       | Track competitor mentions and share of voice               |
| [Source Domains](/developers/endpoints/source-domains/list) | Monitor domains cited by AI platforms                      |
| [Source URLs](/developers/endpoints/source-urls)            | Track individual pages cited in AI responses               |
| [Prompts](/developers/endpoints/prompts/list)               | Access monitored prompts                                   |
| [Answers](/developers/endpoints/answers/list)               | Retrieve stored AI answers                                 |
| [Search](/developers/endpoints/search)                      | List retained query fan-out associated with stored answers |

## Quick start

<Steps>
  <Step title="Get your API token">
    Go to **Team Management** → **API Access** and create a new API token.
  </Step>

  <Step title="Make your first request">
    ```bash theme={null}
    curl -X GET "https://www.qwairy.co/api/v1/brands" \
      -H "Authorization: Bearer qw-api-your-token-here"
    ```
  </Step>

  <Step title="Explore your data">
    Use the brand ID to access performance metrics, competitors, sources, and more.
  </Step>
</Steps>

## Response format

Responses are JSON. List endpoints generally return a resource array and a `pagination` object:

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 10,
    "limit": 10,
    "offset": 0
  },
  "prompts": [ ... ]
}
```

Most list endpoints include a `pagination` object with:

* `total`: Total items matching the query
* `count`: Items in this response
* `limit`: Max items per page
* `offset`: Items skipped

The `/brands` endpoint is the exception: it returns the full list with a top-level `total` count and no `pagination` object.

See [Entities](/developers/entities) for detailed data structures.

Validation and resource errors include machine-readable codes:

```json theme={null}
{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}
```

Authentication and rate-limit errors use a flat shape. See [Error codes](/developers/errors) before implementing error handling.

## Get help

* Check the [Authentication](/developers/authentication) guide
* Review [Rate Limits](/developers/rate-limits)
* See [Error codes](/developers/errors)
* Contact us at [team@qwairy.co](mailto:team@qwairy.co)


# Rate limits
Source: https://docs.qwairy.co/developers/rate-limits

Understand team-level API limits, rate-limit headers, and Retry-After handling.

Limits are applied **per team** across all API tokens belonging to that team.

## Current limits

Two windows are enforced simultaneously on every request:

| Window              | Limit                   |
| ------------------- | ----------------------- |
| Per-minute (burst)  | 1,000 requests / minute |
| Per-day (daily cap) | 20,000 requests / day   |

A request is accepted only if **both** windows have budget remaining. If either window is exhausted, the API returns `429 Too Many Requests`.

<Note>
  To discuss a different limit for a planned workload, contact [team@qwairy.co](mailto:team@qwairy.co) with the expected request volume.
</Note>

## Rate-limit headers

After successful authentication, API responses include headers for both windows. A `429` response also includes `Retry-After`.

| Header                        | Description                                                                          |
| ----------------------------- | ------------------------------------------------------------------------------------ |
| `X-RateLimit-Limit`           | Per-minute request cap                                                               |
| `X-RateLimit-Remaining`       | Requests remaining in the current minute window                                      |
| `X-RateLimit-Reset`           | ISO 8601 timestamp when the minute window resets                                     |
| `X-RateLimit-Daily-Limit`     | Per-day request cap                                                                  |
| `X-RateLimit-Daily-Remaining` | Requests remaining in the current day window                                         |
| `X-RateLimit-Daily-Reset`     | ISO 8601 timestamp when the day window resets                                        |
| `Retry-After`                 | Seconds to wait before retrying, based on the limit actually hit (only set on `429`) |

### Synthetic headers

```http theme={null}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset: 2026-04-07T09:13:00.000Z
X-RateLimit-Daily-Limit: 20000
X-RateLimit-Daily-Remaining: 4211
X-RateLimit-Daily-Reset: 2026-04-08T00:00:00.000Z
```

<Warning>
  Check both windows. A request can be rejected when the daily cap is exhausted even if the per-minute budget remains, and vice versa.
</Warning>

## Handle rate limits

When either window is exceeded, the API returns `429 Too Many Requests` with a body indicating which window was hit:

```json theme={null}
{
  "error": "Too Many Requests",
  "limit": "daily",
  "message": "Daily rate limit (20000/day) exceeded. Please try again in 32451 seconds.",
  "retryAfter": 32451
}
```

The `limit` field is either `"burst"` or `"daily"`. Honor `Retry-After`, which is calculated from the window that blocked the request.

### Retry practices

<CardGroup>
  <Card title="Honor Retry-After" icon="clock">
    Use the `Retry-After` header as-is. It already reflects whichever window (minute or day) is the real blocker.
  </Card>

  <Card title="Watch both remaining headers" icon="gauge">
    Monitor `X-RateLimit-Remaining` and `X-RateLimit-Daily-Remaining` to throttle proactively.
  </Card>

  <Card title="Cache responses" icon="database">
    Store and reuse data that doesn't change frequently (brands, competitors, topics).
  </Card>

  <Card title="Batch and filter" icon="layer-group">
    Use query filters (`provider`, `period`, `limit`) to fetch only the data you need.
  </Card>
</CardGroup>

### Retry logic

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 10) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status !== 429) return response;

    // Retry-After points at the blocking window
    // (minute or day window), not just the minute reset.
    const retryAfterSec = Number(response.headers.get('Retry-After') ?? '60');
    const waitMs = Math.max(retryAfterSec * 1000, 1000);

    const body = await response.clone().json().catch(() => ({}));
    console.warn(
      `Rate limited on ${body.limit ?? 'unknown'} window. Retrying in ${waitMs}ms...`
    );

    await new Promise((r) => setTimeout(r, waitMs));
  }

  throw new Error('Max retries exceeded');
}
```

<Tip>
  If you see `"limit": "daily"` on retry, waiting within the same process rarely helps: the daily window can be hours away. Persist the `X-RateLimit-Daily-Reset` timestamp and reschedule the job instead of blocking a worker.
</Tip>

## Reduce API usage

### Use filtering parameters

Instead of fetching all data and filtering client-side, use query parameters:

```bash theme={null}
# Fetch all answers, then filter in code
GET /api/v1/brands/{brandId}/answers

# Filter at the API level
GET /api/v1/brands/{brandId}/answers?provider=chatgpt&hasSelfMention=true&limit=50
```

### Cache stable data

Cache data only for as long as your integration can tolerate staleness:

* **Brands list**: changes when brand access changes
* **Competitors list**: changes with configuration and observed data
* **Topics/Tags**: changes when workspace configuration changes

### Use date ranges

Limit data retrieval to relevant time periods:

```bash theme={null}
# Bound an otherwise unbounded request to the last 7 days
GET /api/v1/brands/{brandId}/performance?period=7
```

## Discuss higher limits

Contact [team@qwairy.co](mailto:team@qwairy.co) with your use case and expected volume. Any change depends on the workload and account configuration.


# Outbound webhooks
Source: https://docs.qwairy.co/developers/webhooks

Receive weekly-report and export-ready events as signed JSON POST requests to your endpoint.

An Enterprise team can send supported notifications to its own endpoint as signed JSON events. When webhook delivery is enabled, Qwairy does not send the matching email.

<Note>
  Outbound webhooks are part of [Agencies](/agencies/introduction), an **Enterprise** capability. The controls are **OWNER**-only.
</Note>

## Events

<CardGroup>
  <Card title="report.weekly" icon="chart-line">
    A workspace's weekly report.
  </Card>

  <Card title="export.ready" icon="file-arrow-down">
    A data export has finished and is ready to download.
  </Card>
</CardGroup>

A `webhook.test` event is also sent by the **Send test event** button so you can validate your endpoint before turning delivery on.

## Configure delivery

<Steps>
  <Step title="Open Notifications">
    Go to **Team Management > Notifications** and find **Outbound webhooks**.
  </Step>

  <Step title="Add your endpoint URL">
    Enter a public `https` URL and save it. Private addresses and `http` URLs are rejected. A **signing secret** is generated and shown once; copy and store it.
  </Step>

  <Step title="Send a test event">
    Click **Send test event** to confirm Qwairy can reach your endpoint and your signature check passes.
  </Step>

  <Step title="Enable delivery">
    Toggle **Deliver via webhook** on. From now on, the events above go to your endpoint instead of being emailed.
  </Step>
</Steps>

You can rotate the secret at any time with **Regenerate secret** (the new value is shown once), and remove the webhook to fall back to email.

## Payload

Every request is a `POST` with a JSON envelope:

```json theme={null}
{
  "event": "export.ready",
  "id": "8b40e94f-79f4-40cc-8d38-bde11ef0d8d9",
  "createdAt": "2026-06-18T09:00:00.000Z",
  "team": { "id": "team_abc123", "name": "Acme" },
  "data": {
    "exportId": "cmg1x0c9r0001l204qk1nv8dz",
    "exportType": "answers",
    "rowCount": 842
  }
}
```

The `data` object is event-specific. Treat it as forward-compatible: new fields may be added, so ignore the ones you don't use rather than rejecting the payload.

## Headers

| Header               | Value                                           |
| -------------------- | ----------------------------------------------- |
| `X-Qwairy-Event`     | Event name, for example `export.ready`          |
| `X-Qwairy-Timestamp` | Unix time (seconds) when the request was signed |
| `X-Qwairy-Signature` | `sha256=<hex>` HMAC of the request              |

## Verify the signature

The signature is an HMAC-SHA256 keyed with your signing secret. Its input is `<timestamp>.<body>` using the raw request bytes before JSON parsing.

```js theme={null}
import crypto from 'crypto';

function isValidQwairyWebhook(req, secret) {
  const signature = req.headers['x-qwairy-signature']; // "sha256=<hex>"
  const timestamp = req.headers['x-qwairy-timestamp'];

  // Reject stale requests to prevent replay (e.g. older than 5 minutes).
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${req.rawBody}`)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

<Warning>
  Verify the signature on every request and reject anything that fails. Use a constant-time comparison, and reject timestamps outside a short window to block replays.
</Warning>

## Delivery behavior

* Qwairy expects a `2xx` response. Non-`2xx`, timeouts, and redirects count as failures.
* A failed weekly-report delivery is retried on the next scheduled run; the matching email is **not** sent in its place.
* The export-ready event is one-shot: if delivery fails, the export still appears in your workspace's **Exports** hub.


# Backlink Opportunities
Source: https://docs.qwairy.co/documentation/act/backlink-opportunities

Investigate cited third-party pages where competitor presence and on-page evidence suggest an outreach opportunity.

Open **Act > Backlink Opportunities** to review external pages found through monitored sources.

Qwairy combines citation activity with on-page analysis to identify pages that may be relevant to outreach. A candidate page is not an endorsement of its quality, authority, or willingness to link.

## How candidates are identified

A candidate can be based on signals such as:

* the page or domain appears in monitored AI answers;
* direct competitors are present on the analyzed page;
* the SELF brand is absent or has limited on-page presence;
* the source is classified as a third party rather than owned or ignored.

Source analysis may fetch the public URL to inspect page content. Access can fail when a site blocks automated requests, requires authentication, or changes after the monitored answer was captured.

## Review before outreach

1. Open the source page and confirm it is current.
2. Check why it appeared in the monitored answer.
3. Verify competitor and source classifications.
4. Assess editorial relevance and contact ownership outside Qwairy.
5. Record outreach and publication status in the system your team uses for delivery.

Do not treat a detected gap as evidence that a backlink will be granted or that it will change search or AI visibility.

## Related pages

* [Source Explorer](/documentation/monitor/content-sources)
* [Content Opportunities](/documentation/act/content-opportunities)


# Content Opportunities
Source: https://docs.qwairy.co/documentation/act/content-opportunities

Review prompts where monitored answers show a content or brand-presence gap, with the evidence used for prioritization.

Open **Act > Content Opportunities** to review prompts that may warrant new or revised content.

An opportunity is derived from the monitored dataset. It is a research lead, not a prediction that publishing content will change a provider's answer.

## What the page combines

The page can bring together:

* the prompt and its topic or funnel stage;
* providers that returned relevant answers;
* SELF and competitor presence;
* cited sources or related evidence;
* a gap or priority value calculated for the current scope.

Open an item to understand which records support it. Confirm that the prompt reflects an audience need before creating work from it.

## Review an opportunity

1. Read the monitored answers for the prompt.
2. Check whether direct competitors are classified correctly.
3. Inspect cited pages in **Source Explorer**.
4. Review existing content on your site for overlap.
5. Decide whether to update an existing page, create a new page, or dismiss the item.

Use filters and sorting to focus on the market, provider, topic, or stage relevant to the current plan.

## Continue in Content Studio

Where the action is available, send an opportunity to [Content Studio](/documentation/act/content-studio) to prepare a brief. Review the generated brief against your editorial standards and source material.

## Related pages

* [Query Fan-Out](/documentation/monitor/insights/query-fan-out)
* [Source Explorer](/documentation/monitor/content-sources)
* [Response Analysis](/documentation/monitor/analyzing-answers)


# Content Studio
Source: https://docs.qwairy.co/documentation/act/content-studio

Create and review content briefs using selected Qwairy insights, brand context, and editorial inputs.

Open **Act > Content Studio** to turn a selected opportunity or topic into a structured content brief.

Content Studio can use context from Qwairy features such as Query Fan-Out, Shopping Results, Content Opportunities, personas, and brand data. Generated material is a draft for human review.

## Start a brief

Choose the available inputs for the assignment, which can include:

* target prompt or topic;
* audience persona;
* language and market;
* supporting insights and sources;
* editorial instructions.

Review the selected inputs before generating. Creating an article or generated brief costs **50 credits**. Duplicating an existing article creates a new article and costs another **50 credits**.

## Review the output

Check the brief for:

* a clear search or audience intent;
* accurate use of brand facts;
* traceable sources for factual claims;
* overlap with existing pages;
* an appropriate structure and call to action;
* unsupported competitor, legal, financial, or performance claims.

Edit the result to match your editorial voice and publishing requirements. Qwairy does not publish the brief to an external content system from this page unless a separate integration explicitly provides that action.

## Use monitoring as evidence

Return to the source prompt and answers when the brief makes an assumption about provider behavior. After publication, compare equivalent monitoring periods without claiming that a single content change caused a metric movement.

## Related pages

* [Content Opportunities](/documentation/act/content-opportunities)
* [Personas](/documentation/workspace/personas)
* [Providers & Credits](/documentation/get-started/credits)


# Perception
Source: https://docs.qwairy.co/documentation/analyze/brand-perception

Compare how selected AI providers describe your brand with the attributes you have configured.

Open **Analyze > Perception** to review generated perception snapshots for the selected brand.

Perception is separate from the sentiment attached to routine monitoring mentions. It runs a dedicated analysis and compares provider answers with your configured brand attributes.

## Prepare the analysis

Review the brand attributes before starting a snapshot. These attributes define the intended positioning used for alignment analysis. Keep them specific and verifiable.

The run uses credits per provider. See [Providers & Credits](/documentation/get-started/credits) for the current cost.

## History and status

The history table records each snapshot and its state, including pending, generating, analyzing, completed, or failed. Open a completed snapshot to inspect its detail.

Do not compare two snapshots without checking their providers, attributes, and time period. A configuration change can affect the result independently of provider output.

## Snapshot detail

The detail view can include:

* sentiment and alignment scores;
* an Overview across providers and tabs for individual providers;
* areas where provider descriptions converge or diverge;
* themes and brand-attribute alignment;
* a SWOT-style summary;
* the prompts, answers, and sources used in the snapshot.

Scores are generated assessments of the selected responses. Read the supporting summaries and answers before using them in an external statement.

## Review workflow

1. Confirm the brand attributes and provider set.
2. Review the aggregate view for recurring themes.
3. Switch to provider tabs to locate disagreement.
4. Open the source answers for context.
5. Record any attribute or provider change before the next comparison.

## Related pages

* [Sentiment](/documentation/analyze/sentiment-analysis)
* [Response Analysis](/documentation/monitor/analyzing-answers)


# Fact Check
Source: https://docs.qwairy.co/documentation/analyze/fact-check

Extract claims from monitored answers, compare them with a source of truth, and record human verification decisions.

<Info>
  Fact Check is in private beta. Access must be granted for the workspace.
</Info>

Open **Analyze > Fact Check** to review factual claims extracted from answers that mention the monitored brand.

Fact Check does not consume customer credits. There is no customer-facing active or paused toggle. Processing is controlled by beta access and the available Fact Check workflows.

## How claims are processed

1. Qwairy selects monitored answers with a SELF brand mention.
2. It extracts factual claims from those answers.
3. It compares claims with entries in the **Source of Truth** where available.
4. Authorized users review claims that need a decision.
5. The audit log records claim and verification activity.

Automated matching helps organize review. It does not replace verification of material facts.

## Tabs

### Overview

The Overview summarizes claim accuracy, status distribution, changes over time, and available category or provider breakdowns.

### Claims

Search, filter, and sort extracted claims. Available statuses include Unverified, Correct, Incorrect, Outdated, Auto-verified, and Ignored.

Open a claim to review its occurrences, providers, category, impact, and relationship to the Source of Truth before assigning a verdict.

### Source of Truth

Maintain the canonical statements used for comparison. A source-of-truth entry should be narrow, current, and supported by an approved internal or public reference.

Access to this tab depends on the user's role.

### Audit log

Review the chronological record of extraction and verification activity. Access depends on the user's role.

## Export

Where available for the user's role, use **Export CSV** to download claims and their current metadata. An export is a point-in-time snapshot; later verdicts are not applied to an existing file.

<Warning>
  A claim marked Correct means it was verified in the configured review context. Confirm legal, financial, security, and other time-sensitive statements with the responsible source before external use.
</Warning>


# Sentiment
Source: https://docs.qwairy.co/documentation/analyze/sentiment-analysis

Review the sentiment assigned to brand mentions across providers, topics, competitors, and time periods.

Open **Analyze > Sentiment** to review how detected brand mentions are described in monitored answers.

Each analyzed mention receives a score on a 0 to 100 scale. Higher values represent more positive language in the analyzed context. The page also groups mentions into positive, neutral, and negative categories.

## Choose the scope

Use the available controls to select:

* the monitored brand or a competitor;
* provider;
* topic;
* time range;
* result order.

Global filters can further affect the dataset. Confirm the selected brand before comparing sentiment with another page.

## Review individual mentions

The mention list connects each score to its context, including the provider, topic, prompt, and generated summary where available.

Read the full answer when wording is ambiguous. A score summarizes detected tone; it does not establish customer opinion, brand reputation in the wider market, or the intent of the provider.

## Compare periods

Keep the prompt set, providers, market, and brand relationship stable. A change in the mix of prompts can move the average even when similar answers receive similar scores.

## Export

Use the available export control for the current sentiment dataset. Record the filters and date range with any external report.

## Related pages

* [Perception](/documentation/analyze/brand-perception)
* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Core Concepts](/documentation/get-started/core-concepts)


# Supported countries and territories
Source: https://docs.qwairy.co/documentation/availability/countries

Compare market and AI engine availability for continuous workspaces and one-off Pitch Audits.

Country scope works differently for continuous workspaces and one-off Pitch Audits. Use the tab for the surface you are configuring.

| Surface      | Market choices | Scope                                                                        |
| ------------ | -------------: | ---------------------------------------------------------------------------- |
| Workspaces   |            248 | One country or territory per workspace. Available AI engines vary by market. |
| Pitch Audits |            248 | One country per audit. Available AI engines vary by market.                  |

<Note>
  Country availability does not guarantee a particular answer. AI engines can
  return different results by market, prompt, language, and collection time.
</Note>

<Tabs>
  <Tab title="Workspaces">
    A workspace can be configured for any of the 248 markets below. The matrix shows which core AI engines can be selected for that workspace country.

    | Country or territory             | Code | ChatGPT | Gemini | Perplexity | Copilot | Grok | AI Mode | AI Overview |
    | -------------------------------- | ---- | ------- | ------ | ---------- | ------- | ---- | ------- | ----------- |
    | Afghanistan                      | `AF` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Aland Islands                    | `AX` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Albania                          | `AL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Algeria                          | `DZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | American Samoa                   | `AS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Andorra                          | `AD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Angola                           | `AO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Anguilla                         | `AI` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Antarctica                       | `AQ` | No      | No     | No         | No      | No   | No      | Yes         |
    | Antigua and Barbuda              | `AG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Argentina                        | `AR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Armenia                          | `AM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Aruba                            | `AW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Australia                        | `AU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Austria                          | `AT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Azerbaijan                       | `AZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bahamas                          | `BS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bahrain                          | `BH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bailiwick of Jersey              | `JE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bangladesh                       | `BD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Barbados                         | `BB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Belarus                          | `BY` | No      | No     | No         | No      | No   | No      | Yes         |
    | Belgium                          | `BE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Belize                           | `BZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Benin                            | `BJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bermuda                          | `BM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bhutan                           | `BT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bolivia                          | `BO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bonaire (caribbean Netherlands)  | `BQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bosnia and Herzegovina           | `BA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Botswana                         | `BW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bouvet Island                    | `BV` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Brazil                           | `BR` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | British Indian Ocean Territory   | `IO` | No      | Yes    | No         | No      | No   | Yes     | Yes         |
    | Brunei                           | `BN` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Bulgaria                         | `BG` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Burkina Faso                     | `BF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Burundi                          | `BI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cambodia                         | `KH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cameroon                         | `CM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Canada                           | `CA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cape Verde                       | `CV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cayman Islands                   | `KY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Central African Republic         | `CF` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Chad                             | `TD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Chile                            | `CL` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | China                            | `CN` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Christmas Island                 | `CX` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Cocos (keeling) Islands          | `CC` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Colombia                         | `CO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Comoros                          | `KM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Congo                            | `CG` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Cook Islands                     | `CK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Costa Rica                       | `CR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Côte d'Ivoire                    | `CI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Croatia (hrvatska)               | `HR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Curacao                          | `CW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cyprus                           | `CY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Czech Republic                   | `CZ` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Denmark                          | `DK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Djibouti                         | `DJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Dominica                         | `DM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Dominican Republic               | `DO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | DR Congo                         | `CD` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Ecuador                          | `EC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Egypt                            | `EG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | El Salvador                      | `SV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Equatorial Guinea                | `GQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Eritrea                          | `ER` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Estonia                          | `EE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ethiopia                         | `ET` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Falkland Islands                 | `FK` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Faroe Islands                    | `FO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Fiji                             | `FJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Finland                          | `FI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | France                           | `FR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | French Guiana                    | `GF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | French Polynesia                 | `PF` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Gabon                            | `GA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Gambia                           | `GM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Georgia                          | `GE` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Germany                          | `DE` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Ghana                            | `GH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Gibraltar                        | `GI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Greece                           | `GR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Greenland                        | `GL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Grenada                          | `GD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guadeloupe                       | `GP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Guam                             | `GU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guatemala                        | `GT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guernsey                         | `GG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guinea                           | `GN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guinea-Bissau                    | `GW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guyana                           | `GY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Haiti                            | `HT` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Heard & McDonald Islands         | `HM` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Honduras                         | `HN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Hong Kong                        | `HK` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Hungary                          | `HU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Iceland                          | `IS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | India                            | `IN` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Indonesia                        | `ID` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Iran                             | `IR` | No      | No     | No         | No      | No   | No      | No          |
    | Iraq                             | `IQ` | No      | No     | No         | No      | No   | No      | Yes         |
    | Ireland                          | `IE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Isle of Man                      | `IM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Israel                           | `IL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Italy                            | `IT` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Jamaica                          | `JM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Japan                            | `JP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Jordan                           | `JO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kazakhstan                       | `KZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kenya                            | `KE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kiribati                         | `KI` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kosovo                           | `XK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Kuwait                           | `KW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kyrgyzstan                       | `KG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Laos                             | `LA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Latvia                           | `LV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Lebanon                          | `LB` | No      | No     | No         | No      | No   | No      | Yes         |
    | Lesotho                          | `LS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Liberia                          | `LR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Libya                            | `LY` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Liechtenstein                    | `LI` | Yes     | Yes    | Yes        | No      | No   | Yes     | Yes         |
    | Lithuania                        | `LT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Luxembourg                       | `LU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Macau                            | `MO` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Madagascar                       | `MG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malawi                           | `MW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malaysia                         | `MY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Maldives                         | `MV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mali                             | `ML` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malta                            | `MT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Marshall Islands                 | `MH` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Martinique                       | `MQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Mauritania                       | `MR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mauritius                        | `MU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mayotte                          | `YT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Mexico                           | `MX` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Micronesia                       | `FM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Moldova                          | `MD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Monaco                           | `MC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mongolia                         | `MN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Montenegro                       | `ME` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Montserrat                       | `MS` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Morocco                          | `MA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mozambique                       | `MZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Myanmar (burma)                  | `MM` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Namibia                          | `NA` | No      | Yes    | Yes        | No      | No   | Yes     | Yes         |
    | Nauru                            | `NR` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Nepal                            | `NP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Netherlands                      | `NL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | New Caledonia                    | `NC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | New Zealand                      | `NZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Nicaragua                        | `NI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Niger                            | `NE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Nigeria                          | `NG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Niue                             | `NU` | No      | No     | Yes        | Yes     | No   | Yes     | Yes         |
    | Norfolk Island                   | `NF` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | North Korea                      | `KP` | No      | No     | No         | No      | No   | No      | No          |
    | North Macedonia                  | `MK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Northern Mariana Islands         | `MP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Norway                           | `NO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Oman                             | `OM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Pakistan                         | `PK` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Palau                            | `PW` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Palestine                        | `PS` | No      | No     | No         | No      | No   | No      | Yes         |
    | Panama                           | `PA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Papua New Guinea                 | `PG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Paraguay                         | `PY` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Peru                             | `PE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Philippines                      | `PH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Pitcairn Islands                 | `PN` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Poland                           | `PL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Portugal                         | `PT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Puerto Rico                      | `PR` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Qatar                            | `QA` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Réunion                          | `RE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Romania                          | `RO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Russia                           | `RU` | No      | No     | No         | No      | No   | No      | Yes         |
    | Rwanda                           | `RW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saint Barthélemy                 | `BL` | No      | Yes    | Yes        | No      | No   | Yes     | No          |
    | Saint Helena                     | `SH` | No      | Yes    | Yes        | Yes     | No   | Yes     | No          |
    | Saint Kitts and Nevis            | `KN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saint Lucia                      | `LC` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Saint Martin                     | `MF` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | No          |
    | Saint Pierre and Miquelon        | `PM` | No      | Yes    | Yes        | Yes     | No   | Yes     | No          |
    | Saint Vincent and the Grenadines | `VC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | San Marino                       | `SM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | São Tomé and Príncipe            | `ST` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saudi Arabia                     | `SA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Senegal                          | `SN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Serbia                           | `RS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Seychelles                       | `SC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sierra Leone                     | `SL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Singapore                        | `SG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sint Maarten                     | `SX` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Slovak Republic                  | `SK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Slovenia                         | `SI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Solomon Islands                  | `SB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Somalia                          | `SO` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | South Africa                     | `ZA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | South Georgia                    | `GS` | No      | No     | No         | No      | No   | Yes     | No          |
    | South Korea                      | `KR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | South Sudan                      | `SS` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Spain                            | `ES` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sri Lanka                        | `LK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sudan                            | `SD` | No      | No     | No         | No      | No   | No      | Yes         |
    | Suriname                         | `SR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Svalbard & Jan Mayen             | `SJ` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Swaziland                        | `SZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sweden                           | `SE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Switzerland                      | `CH` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Syria                            | `SY` | No      | No     | No         | No      | No   | No      | Yes         |
    | Taiwan                           | `TW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tajikistan                       | `TJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Tanzania                         | `TZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Thailand                         | `TH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Timor-Leste                      | `TL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Togo                             | `TG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tokelau                          | `TK` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Tonga                            | `TO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Trinidad and Tobago              | `TT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tunisia                          | `TN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Turkey                           | `TR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Turkmenistan                     | `TM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Turks and Caicos Islands         | `TC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tuvalu                           | `TV` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Uganda                           | `UG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ukraine                          | `UA` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | United Arab Emirates             | `AE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | United Kingdom                   | `GB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | United States                    | `US` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Uruguay                          | `UY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | US Minor Outlying Islands        | `UM` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Uzbekistan                       | `UZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Vanuatu                          | `VU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Vatican City                     | `VA` | Yes     | No     | Yes        | No      | No   | Yes     | Yes         |
    | Venezuela                        | `VE` | No      | Yes    | Yes        | No      | No   | Yes     | Yes         |
    | Vietnam                          | `VN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Virgin Islands (british)         | `VG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Virgin Islands (us)              | `VI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Wallis and Futuna                | `WF` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | No          |
    | Western Sahara                   | `EH` | No      | No     | No         | No      | No   | Yes     | Yes         |
    | Western Samoa                    | `WS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Yemen                            | `YE` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
    | Zambia                           | `ZM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Zimbabwe                         | `ZW` | Yes     | Yes    | Yes        | Yes     | No   | Yes     | Yes         |
  </Tab>

  <Tab title="Pitch Audits">
    Pitch Audits accept the 248 markets below. Each audit is a one-off snapshot and has its own engine selection.

    | Country or territory             | Code | ChatGPT | Gemini | Perplexity | Copilot | Grok | AI Mode | AI Overview |
    | -------------------------------- | ---- | ------- | ------ | ---------- | ------- | ---- | ------- | ----------- |
    | Afghanistan                      | `AF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Aland Islands                    | `AX` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Albania                          | `AL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Algeria                          | `DZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | American Samoa                   | `AS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Andorra                          | `AD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Angola                           | `AO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Anguilla                         | `AI` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Antarctica                       | `AQ` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Antigua and Barbuda              | `AG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Argentina                        | `AR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Armenia                          | `AM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Aruba                            | `AW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Australia                        | `AU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Austria                          | `AT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Azerbaijan                       | `AZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bahamas                          | `BS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bahrain                          | `BH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bailiwick of Jersey              | `JE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bangladesh                       | `BD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Barbados                         | `BB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Belarus                          | `BY` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Belgium                          | `BE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Belize                           | `BZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Benin                            | `BJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bermuda                          | `BM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bhutan                           | `BT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bolivia                          | `BO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bonaire (caribbean Netherlands)  | `BQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bosnia and Herzegovina           | `BA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Botswana                         | `BW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bouvet Island                    | `BV` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Brazil                           | `BR` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | British Indian Ocean Territory   | `IO` | No      | Yes    | No         | No      | Yes  | Yes     | Yes         |
    | Brunei                           | `BN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Bulgaria                         | `BG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Burkina Faso                     | `BF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Burundi                          | `BI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cambodia                         | `KH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cameroon                         | `CM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Canada                           | `CA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cape Verde                       | `CV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cayman Islands                   | `KY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Central African Republic         | `CF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Chad                             | `TD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Chile                            | `CL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | China                            | `CN` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Christmas Island                 | `CX` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Cocos (keeling) Islands          | `CC` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Colombia                         | `CO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Comoros                          | `KM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Congo                            | `CG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cook Islands                     | `CK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Costa Rica                       | `CR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Côte d'Ivoire                    | `CI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Croatia (hrvatska)               | `HR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Curacao                          | `CW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Cyprus                           | `CY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Czech Republic                   | `CZ` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Denmark                          | `DK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Djibouti                         | `DJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Dominica                         | `DM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Dominican Republic               | `DO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | DR Congo                         | `CD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ecuador                          | `EC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Egypt                            | `EG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | El Salvador                      | `SV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Equatorial Guinea                | `GQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Eritrea                          | `ER` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Estonia                          | `EE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ethiopia                         | `ET` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Falkland Islands                 | `FK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Faroe Islands                    | `FO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Fiji                             | `FJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Finland                          | `FI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | France                           | `FR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | French Guiana                    | `GF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | French Polynesia                 | `PF` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Gabon                            | `GA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Gambia                           | `GM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Georgia                          | `GE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Germany                          | `DE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ghana                            | `GH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Gibraltar                        | `GI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Greece                           | `GR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Greenland                        | `GL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Grenada                          | `GD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guadeloupe                       | `GP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Guam                             | `GU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guatemala                        | `GT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guernsey                         | `GG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guinea                           | `GN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guinea-Bissau                    | `GW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Guyana                           | `GY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Haiti                            | `HT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Heard & McDonald Islands         | `HM` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Honduras                         | `HN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Hong Kong                        | `HK` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Hungary                          | `HU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Iceland                          | `IS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | India                            | `IN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Indonesia                        | `ID` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Iran                             | `IR` | No      | No     | No         | No      | Yes  | No      | No          |
    | Iraq                             | `IQ` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Ireland                          | `IE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Isle of Man                      | `IM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Israel                           | `IL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Italy                            | `IT` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Jamaica                          | `JM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Japan                            | `JP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Jordan                           | `JO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kazakhstan                       | `KZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kenya                            | `KE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kiribati                         | `KI` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kosovo                           | `XK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Kuwait                           | `KW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Kyrgyzstan                       | `KG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Laos                             | `LA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Latvia                           | `LV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Lebanon                          | `LB` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Lesotho                          | `LS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Liberia                          | `LR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Libya                            | `LY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Liechtenstein                    | `LI` | Yes     | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Lithuania                        | `LT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Luxembourg                       | `LU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Macau                            | `MO` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Madagascar                       | `MG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malawi                           | `MW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malaysia                         | `MY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Maldives                         | `MV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mali                             | `ML` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Malta                            | `MT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Marshall Islands                 | `MH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Martinique                       | `MQ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Mauritania                       | `MR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mauritius                        | `MU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mayotte                          | `YT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Mexico                           | `MX` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Micronesia                       | `FM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Moldova                          | `MD` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Monaco                           | `MC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mongolia                         | `MN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Montenegro                       | `ME` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Montserrat                       | `MS` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Morocco                          | `MA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Mozambique                       | `MZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Myanmar (burma)                  | `MM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Namibia                          | `NA` | No      | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Nauru                            | `NR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Nepal                            | `NP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Netherlands                      | `NL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | New Caledonia                    | `NC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | New Zealand                      | `NZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Nicaragua                        | `NI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Niger                            | `NE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Nigeria                          | `NG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Niue                             | `NU` | No      | No     | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Norfolk Island                   | `NF` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | North Korea                      | `KP` | No      | No     | No         | No      | Yes  | No      | No          |
    | North Macedonia                  | `MK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Northern Mariana Islands         | `MP` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Norway                           | `NO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Oman                             | `OM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Pakistan                         | `PK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Palau                            | `PW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Palestine                        | `PS` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Panama                           | `PA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Papua New Guinea                 | `PG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Paraguay                         | `PY` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Peru                             | `PE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Philippines                      | `PH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Pitcairn Islands                 | `PN` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Poland                           | `PL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Portugal                         | `PT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Puerto Rico                      | `PR` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Qatar                            | `QA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Réunion                          | `RE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Romania                          | `RO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Russia                           | `RU` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Rwanda                           | `RW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saint Barthélemy                 | `BL` | No      | Yes    | Yes        | No      | Yes  | Yes     | No          |
    | Saint Helena                     | `SH` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Saint Kitts and Nevis            | `KN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saint Lucia                      | `LC` | Yes     | Yes    | Yes        | Yes     | Yes  | No      | Yes         |
    | Saint Martin                     | `MF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Saint Pierre and Miquelon        | `PM` | No      | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Saint Vincent and the Grenadines | `VC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | San Marino                       | `SM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | São Tomé and Príncipe            | `ST` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Saudi Arabia                     | `SA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Senegal                          | `SN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Serbia                           | `RS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Seychelles                       | `SC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sierra Leone                     | `SL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Singapore                        | `SG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sint Maarten                     | `SX` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Slovak Republic                  | `SK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Slovenia                         | `SI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Solomon Islands                  | `SB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Somalia                          | `SO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | South Africa                     | `ZA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | South Georgia                    | `GS` | No      | No     | No         | No      | Yes  | Yes     | No          |
    | South Korea                      | `KR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | South Sudan                      | `SS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Spain                            | `ES` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sri Lanka                        | `LK` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sudan                            | `SD` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Suriname                         | `SR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Svalbard & Jan Mayen             | `SJ` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Swaziland                        | `SZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Sweden                           | `SE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Switzerland                      | `CH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Syria                            | `SY` | No      | No     | No         | No      | Yes  | No      | Yes         |
    | Taiwan                           | `TW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tajikistan                       | `TJ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Tanzania                         | `TZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Thailand                         | `TH` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Timor-Leste                      | `TL` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Togo                             | `TG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tokelau                          | `TK` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Tonga                            | `TO` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Trinidad and Tobago              | `TT` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tunisia                          | `TN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Turkey                           | `TR` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Turkmenistan                     | `TM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Turks and Caicos Islands         | `TC` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Tuvalu                           | `TV` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Uganda                           | `UG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Ukraine                          | `UA` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | United Arab Emirates             | `AE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | United Kingdom                   | `GB` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | United States                    | `US` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Uruguay                          | `UY` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | US Minor Outlying Islands        | `UM` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Uzbekistan                       | `UZ` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Vanuatu                          | `VU` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Vatican City                     | `VA` | Yes     | No     | Yes        | No      | Yes  | Yes     | Yes         |
    | Venezuela                        | `VE` | No      | Yes    | Yes        | No      | Yes  | Yes     | Yes         |
    | Vietnam                          | `VN` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Virgin Islands (british)         | `VG` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Virgin Islands (us)              | `VI` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Wallis and Futuna                | `WF` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | No          |
    | Western Sahara                   | `EH` | No      | No     | No         | No      | Yes  | Yes     | Yes         |
    | Western Samoa                    | `WS` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Yemen                            | `YE` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Zambia                           | `ZM` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
    | Zimbabwe                         | `ZW` | Yes     | Yes    | Yes        | Yes     | Yes  | Yes     | Yes         |
  </Tab>
</Tabs>

## How to use this registry

* Choose the country or territory that represents the audience you want to observe.
* Compare only answers collected with the same country, language, prompt set, and time window.
* Recheck this page before expanding to a new market because provider availability can change.

This registry reflects the Qwairy product configuration synchronized on September 15, 2026.

## Related pages

* [Supported languages](/documentation/availability/languages)
* [Workspace monitoring](/documentation/workspace/monitoring)
* [Pitch Audits](/agencies/pitch-audits)


# Supported languages
Source: https://docs.qwairy.co/documentation/availability/languages

Compare language configuration for continuous workspaces and one-off Pitch Audits.

Language configuration has a different grain in workspaces and Pitch Audits. Both surfaces select language independently from country, but they expose different language catalogues.

| Surface      |                     Language choices | Selection method                                  |
| ------------ | -----------------------------------: | ------------------------------------------------- |
| Workspaces   | 45 languages, 46 selectable variants | Selected independently from the workspace country |
| Pitch Audits |                          2 languages | Selected independently from the audit country     |

<Tabs>
  <Tab title="Workspaces">
    The following 46 selectable variants represent 45 supported languages. English has separate US and UK variants.

    Qwairy codes are product configuration values. Do not assume that every code is interchangeable with a generic ISO language code.

    | Language     | Qwairy code |
    | ------------ | ----------- |
    | Albanian     | `SQ`        |
    | Arabic       | `AR`        |
    | Armenian     | `HY`        |
    | Azerbaijani  | `AZ`        |
    | Bengali      | `BN`        |
    | Bosnian      | `BS`        |
    | Bulgarian    | `BG`        |
    | Chinese      | `ZH`        |
    | Croatian     | `HR`        |
    | Czech        | `CS`        |
    | Danish       | `DA`        |
    | Dutch        | `NL`        |
    | English (UK) | `EN_GB`     |
    | English (US) | `EN_US`     |
    | Estonian     | `ET`        |
    | Finnish      | `FI`        |
    | French       | `FR`        |
    | German       | `DE`        |
    | Greek        | `EL`        |
    | Hebrew       | `HE`        |
    | Hindi        | `HI`        |
    | Hungarian    | `HU`        |
    | Indonesian   | `ID`        |
    | Italian      | `IT`        |
    | Japanese     | `JA`        |
    | Korean       | `KO`        |
    | Latvian      | `LV`        |
    | Lithuanian   | `LT`        |
    | Macedonian   | `MK`        |
    | Malay        | `MS`        |
    | Norwegian    | `NO`        |
    | Polish       | `PL`        |
    | Portuguese   | `PT`        |
    | Romanian     | `RO`        |
    | Russian      | `RU`        |
    | Serbian      | `SR`        |
    | Slovak       | `SK`        |
    | Slovenian    | `SL`        |
    | Spanish      | `ES`        |
    | Swedish      | `SE`        |
    | Tagalog      | `TL`        |
    | Thai         | `TH`        |
    | Turkish      | `TR`        |
    | Ukrainian    | `UK`        |
    | Urdu         | `UR`        |
    | Vietnamese   | `VI`        |
  </Tab>

  <Tab title="Pitch Audits">
    Pitch Audits support an explicit choice between English and French, independently from the selected country. The selected language is used for generated questions and the report.

    | Language | Code |
    | -------- | ---- |
    | English  | `en` |
    | French   | `fr` |
  </Tab>
</Tabs>

## Country and language are separate dimensions

In a workspace, country controls the market context and AI engine availability. Language controls prompt generation and generated content. Changing either dimension changes the measured scope and can break trend comparability.

This registry reflects the Qwairy product configuration on September 15, 2026.

## Related pages

* [Supported countries and territories](/documentation/availability/countries)
* [Workspace settings](/documentation/workspace/brand-settings)
* [Content Studio](/documentation/act/content-studio)
* [Pitch Audits](/agencies/pitch-audits)


# Action Center
Source: https://docs.qwairy.co/documentation/cockpit/action-center

Review suggestions derived from Qwairy data, organize accepted work, and adjust the strategy used for prioritization.

<Info>
  Action Center is available on paid plans. Viewer access is restricted.
</Info>

Open **Cockpit > Action Center** to review suggested work derived from the current workspace data.

Suggestions are decision support. Validate their evidence, scope, ownership, and expected effort before committing resources.

## Suggestions

The **Suggestions** tab lists detected opportunities and issues. Open a suggestion to review its supporting signals and proposed steps.

You can:

* accept a suggestion and add it to the action plan;
* dismiss a suggestion that is not relevant;
* use the available filters to narrow the queue.

Accepting a suggestion records an intention to work on it. It does not change external content or guarantee a metric change.

## Action plan

The **Action plan** tab tracks accepted work. Switch between the available list and board views to review status and priority.

A separate **Getting started** area may appear for setup tasks. These items help complete the workspace configuration and are distinct from ongoing suggestions.

## History

The **History** tab keeps completed or otherwise resolved items available for review. Use it to understand what the team recorded, not as proof that an external change was published.

## Strategy

The **Strategy** tab lets authorized users adjust the context used to order suggestions. Revisit it when business priorities, market, or reporting scope changes.

## Review workflow

1. Read the supporting evidence.
2. Confirm that the affected prompt, provider, source, or page is still in scope.
3. Assign an owner and status in the action plan.
4. Record the external implementation separately when needed.
5. Compare later monitoring periods using the same scope.


# Compare
Source: https://docs.qwairy.co/documentation/cockpit/compare

Compare the monitored brand with selected competitors across metrics, positioning, overlap, trends, and breakdowns.

Open **Cockpit > Compare** to place the monitored brand and selected competitors in the same analytical scope.

The monitored brand is fixed in the comparison. Add at least one competitor to populate comparative views. Favorited competitors may be preselected when the page opens.

## Comparison views

### Metrics

The metric table presents each selected brand using the product metrics available for the current period. Check the definition of each metric before comparing it with a value from another Qwairy surface.

### Brand Positioning

The positioning view places selected brands on configurable axes. Read the axis labels and metric selectors before interpreting distance or quadrant placement.

### Co-Mention Overlap

The overlap view shows how often brands appear together in the monitored answer set. Co-mention is an observed association in those answers, not evidence of a business relationship or user preference.

### Evolution Over Time

The trend view compares selected brands across the current date range. Keep the prompt set, providers, market, and brand relationships stable when evaluating movement.

### Breakdowns

Use the breakdown tabs to compare results by:

* provider;
* topic;
* tag;
* funnel stage;
* prompt.

## Check an unexpected comparison

1. Confirm that each competitor is classified as DIRECT.
2. Verify the current filters and date range.
3. Check whether every selected provider returned answers.
4. Open **Monitor > Response Analysis** to inspect the underlying text.

See [Core Concepts](/documentation/get-started/core-concepts) for the shared metric definitions.


# GEO Matrix
Source: https://docs.qwairy.co/documentation/cockpit/geo-matrix

Compare one visibility metric across AI providers and topics, tags, funnel stages, or individual prompts.

Open **Cockpit > GEO Matrix** to compare a selected metric across two dimensions.

## Choose the rows

The row selector can group data by:

* **Topics**;
* **Tags**;
* **Funnel**;
* **Prompts**.

Provider columns show the same metric for each AI provider in the current scope. Use the metric selector above the matrix to change what each cell represents.

## Read a cell

A cell combines the selected row group with one provider. Its value and comparative position are calculated only from answers that match that intersection and the active filters.

An empty cell means that the intersection has no usable data for the selected metric. It does not by itself indicate poor performance.

## Inspect details

Select a cell to inspect the records available for that combination. The detail view can show the leading competitors and sources for the selected scope.

Use this sequence when a cell looks unexpected:

1. confirm the metric and row grouping;
2. check the date range and saved list;
3. verify that prompts generated answers for the provider;
4. inspect competitor classifications and cited sources;
5. compare the underlying answers in **Monitor**.

## Export the matrix

Use the image export control to download the current matrix as a PNG. The export reflects the visible configuration, so include the metric, grouping, date range, and filters when sharing it.

## Related pages

* [Overview](/documentation/cockpit/performance-dashboard)
* [Compare](/documentation/cockpit/compare)
* [Prompts](/documentation/workspace/prompts)


# Overview
Source: https://docs.qwairy.co/documentation/cockpit/performance-dashboard

Read the five dashboard metrics, trends, competitors, sources, and breakdowns for the current monitoring scope.

Open **Cockpit > Overview** for a summary of the current brand and filter scope.

## Metric cards

The top row contains five metrics:

| Metric                | What the card calculates                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Mention Rate**      | Distinct answers with a SELF mention divided by distinct answers with at least one SELF or DIRECT mention.   |
| **Citation Rate**     | Distinct answers with a SELF citation divided by distinct answers with at least one SELF or DIRECT citation. |
| **Share of Voice**    | SELF mention occurrences divided by SELF and DIRECT mention occurrences.                                     |
| **Average Sentiment** | Average sentiment for the selected brand's scored mentions.                                                  |
| **Coverage**          | Distinct answered prompts with at least one SELF mention divided by all distinct answered prompts.           |

These definitions are specific to the dashboard. In particular, the REST performance endpoint calculates Coverage at the answer level. See [Core Concepts](/documentation/get-started/core-concepts).

## Filters

Use the available provider, topic, tag, funnel, prompt, list, and date controls to change the scope. A card, chart, and table should be compared only when they use the same filters.

## Dashboard sections

The Overview can include:

* performance evolution over time;
* a provider comparison;
* competitors detected in monitored answers;
* cited source domains and their contribution to the selected scope;
* breakdowns by provider, topic, tag, and funnel stage.

Select a chart element or breakdown row to narrow the view where that interaction is available.

## Investigate a result

1. Confirm the filters and date range.
2. Check the denominator for the metric.
3. Open [Response Analysis](/documentation/monitor/analyzing-answers) to read the underlying answers.
4. Review brand relationships in [Competitor Mentions](/documentation/monitor/competitor-mentions).
5. Review ownership and page detail in [Source Explorer](/documentation/monitor/content-sources).

<Note>
  A percentage can move because answers changed, because the prompt or provider mix changed, or because a brand relationship was reclassified. Record configuration changes when reporting a trend.
</Note>


# Core Concepts
Source: https://docs.qwairy.co/documentation/get-started/core-concepts

Definitions for prompts, topics, providers, answers, mentions, citations, and Qwairy's dashboard metrics.

Use these definitions when reading Qwairy dashboards and this documentation.

## Monitoring vocabulary

* **Prompt**: a natural-language question tracked across one or more AI models.
* **Topic**: a thematic group assigned to a prompt. A prompt can have one topic or be unassigned.
* **Tag**: a reusable label. A prompt can have multiple tags.
* **Funnel stage**: the prompt's position in the buyer journey: TOFU, MOFU, or BOFU.
* **Provider**: the company or product family that serves an AI experience, such as OpenAI or Google.
* **Model**: the specific AI experience or model selected for generation, such as ChatGPT or GPT-5.
* **Answer**: the output captured for one prompt and model generation.
* **Monitoring frequency**: how often a prompt is scheduled. A prompt may inherit the workspace default or override it with Daily, Weekly, Monthly, or No monitoring.
* **Boost**: additional answers generated for a prompt, model, and run. A boost can be set from 2 to 20 answers. The workspace can have a limited number of boosted prompts.
* **Credits**: the unit consumed by answer generation and selected product operations. Creating or importing prompt definitions is free, but automatic answers generated afterward consume the sum of the selected model costs. See [Providers & Credits](/documentation/get-started/credits).

## Brand relationships

Qwairy classifies detected brands by their relationship to the monitored brand:

* **SELF**: the monitored brand.
* **DIRECT**: a direct competitor included in competitive metrics.
* **INDIRECT**: a related brand that is not currently treated as a direct competitor.
* **IGNORED**: a brand excluded from the competitive analysis.

Review these classifications when a metric looks unexpected.

## Mentions and citations

A **mention** is an occurrence of a classified brand in an answer. A **citation** is a detected source associated with an answer. A link in the answer and a citation used for analysis are related signals, but they are not interchangeable on every page.

## Overview metrics

All formulas below use the active date range and filters.

| Metric                | Product definition                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Mention Rate**      | Distinct answers that mention the SELF brand divided by distinct answers that mention at least one SELF or DIRECT brand. |
| **Citation Rate**     | Distinct answers that cite a SELF source divided by distinct answers that cite at least one SELF or DIRECT source.       |
| **Share of Voice**    | SELF mention occurrences divided by SELF and DIRECT mention occurrences.                                                 |
| **Average Sentiment** | Average 0 to 100 sentiment score for mentions of the selected brand in scope.                                            |
| **Coverage**          | Distinct answered prompts with at least one SELF mention divided by all distinct answered prompts in scope.              |

If a denominator is zero, the interface displays the empty or zero state defined by that view.

<Warning>
  The REST performance endpoint has its own Coverage definition: answers with a SELF mention divided by all answers. Do not use that REST formula to reproduce the prompt-level Coverage card on the dashboard.
</Warning>

## Scope and comparability

Metrics change with provider, topic, tag, funnel, prompt, list, and date filters. Compare periods only after checking that the scope, models, market, and prompt set are equivalent.

For the source data behind a metric, use [Response Analysis](/documentation/monitor/analyzing-answers), [Competitor Mentions](/documentation/monitor/competitor-mentions), and [Source Explorer](/documentation/monitor/content-sources).


# Providers & Credits
Source: https://docs.qwairy.co/documentation/get-started/credits

Review the supported AI experiences and models, their collection method, and the credit cost of each operation.

Credit use depends on the operation, the selected model, the number of prompts, and any configured boost.

## Collection methods

Qwairy collects answers through two methods:

* **Core models** use the provider's public AI experience. They cost **1 credit per answer** and support country-level localization where the provider is available.
* **Premium models** use an official provider API for a named model. They cost **2 to 20 credits per answer**, depending on the model. Country hints and native web search or grounding are enabled only where the provider supports them. Mistral and DeepSeek currently run without web search.

Some Premium identifiers are fixed versions, while others follow a moving provider alias. These methods observe different product surfaces. Keep the collection method and model selection stable when comparing periods.

<Note>
  Core-model availability depends on the selected country and the provider's current service status. Unavailable models are excluded from generation.
</Note>

## Core models

| Model                  | Provider      | Credits |
| ---------------------- | ------------- | ------: |
| **ChatGPT**            | OpenAI        |       1 |
| **Perplexity**         | Perplexity AI |       1 |
| **Copilot**            | Microsoft     |       1 |
| **Grok**               | xAI           |       1 |
| **Gemini**             | Google        |       1 |
| **Google AI Overview** | Google        |       1 |
| **Google AI Mode**     | Google        |       1 |

## Premium models

### OpenAI

| Model        | Credits |
| ------------ | ------: |
| GPT-5 mini   |       2 |
| GPT-5        |       4 |
| GPT-5.1      |       4 |
| GPT-5.2      |       5 |
| GPT-5.4 mini |       3 |
| GPT-5.4      |       6 |
| GPT-5.5      |      11 |

### Anthropic (Claude)

| Model             | Credits |
| ----------------- | ------: |
| Claude Haiku 4.5  |       4 |
| Claude Sonnet 4.5 |      12 |
| Claude Sonnet 4.6 |      14 |
| Claude Sonnet 5   |      14 |
| Claude Opus 4.6   |      20 |
| Claude Opus 4.7   |      20 |
| Claude Opus 4.8   |      20 |

### Google Gemini

| Model                  | Credits |
| ---------------------- | ------: |
| Gemini 2.5 Flash-Lite  |       3 |
| Gemini 2.5 Flash       |       4 |
| Gemini 2.5 Pro         |       5 |
| Gemini 3 Flash Preview |       4 |
| Gemini 3.1 Flash-Lite  |       2 |
| Gemini 3.5 Flash       |       3 |
| Gemini 3.1 Pro Preview |       5 |

### Perplexity

| Model                | Credits |
| -------------------- | ------: |
| Perplexity Sonar     |       2 |
| Perplexity Sonar Pro |       3 |
| Sonar Reasoning Pro  |       4 |
| Sonar Deep Research  |       6 |

### xAI (Grok)

| Model    | Credits |
| -------- | ------: |
| Grok 4.3 |       5 |
| Grok 4.5 |       3 |

### Mistral

| Model          | Credits |
| -------------- | ------: |
| Mistral Small  |       3 |
| Mistral Medium |       4 |
| Mistral Large  |       4 |

### DeepSeek

| Model             | Credits |
| ----------------- | ------: |
| DeepSeek V4 Flash |       2 |
| DeepSeek V4 Pro   |       2 |

## Other credit costs

| Operation                                      |                                   Cost | Notes                                                                                                       |
| ---------------------------------------------- | -------------------------------------: | ----------------------------------------------------------------------------------------------------------- |
| **Prompt definition creation or import**       |                              0 credits | Adding prompts is free when no answers run immediately.                                                     |
| **Automatic answers after creation or import** | Sum of selected model costs per prompt | With auto-generate enabled, each new prompt runs against the active and available models.                   |
| **Answer generation**                          |                        1 to 20 credits | One prompt sent to one model. Monitoring and manual runs multiply this cost by prompts, models, and boosts. |
| **Perception analysis**                        |                10 credits per provider | A snapshot can run across up to 6 Core providers.                                                           |
| **Site Diagnostics**                           |     5 credits per completed page audit | Audits and re-audits are billed per page that completes.                                                    |
| **Content Studio article or brief creation**   |                             50 credits | Each new article or generated brief.                                                                        |
| **Content Studio article duplication**         |                             50 credits | Each duplicate creates a new article.                                                                       |
| **Pitch Audit answer generation**              | Sum of selected model costs per prompt | For each prompt, add the credit cost of every selected model.                                               |

Fact Check does not consume customer credits.

## Calculate a run

Multiply each prompt by the credit cost of every selected model, then include the extra answers requested by any boost.

For 10 prompts on ChatGPT Core, GPT-5 mini, and Perplexity Core:

```text theme={null}
10 x (1 + 2 + 1) = 40 credits
```

Creating or importing prompt definitions is free. With auto-generate enabled, 100 prompts using the three default onboarding Core models where all are available cost:

```text theme={null}
100 x (1 + 1 + 1) = 300 credits
```

Ten completed Site Diagnostics page audits cost:

```text theme={null}
10 x 5 = 50 credits
```

Creating one Content Studio article or generated brief costs **50 credits**. Duplicating one existing article costs another **50 credits**.

Automatic-answer cost always uses the sum of the models configured and available for that workspace. It is not a fixed per-prompt amount.

The Monitoring page shows an estimate based on the current prompt frequencies, models, and boosts. Review that estimate before saving a change.

## Check and replenish the balance

Your remaining balance appears in the dashboard sidebar and under **Team Management > Usage**. The Usage page breaks consumption down by category, model, and transaction.

If the balance covers only part of a monitoring or import batch, Qwairy may process an affordable subset of prompts or models. At zero credits, scheduled monitoring pauses and manual generation is unavailable.

Owners of paid parent teams can purchase a credit pack or upgrade under **Team Management > Billing**. Free teams must upgrade first. Sub-team credits are allocated by the parent organization.

## Related pages

* [Monitoring](/documentation/workspace/monitoring)
* [Prompts](/documentation/workspace/prompts)
* [Usage](/documentation/team/usage)
* [Billing](/documentation/team/billing)


# Frequently Asked Questions
Source: https://docs.qwairy.co/documentation/get-started/faq

Answers about monitoring, metrics, topics, prompts, credits, website access, competitors, exports, and integrations.

## Monitoring and data

<Accordion title="What does one monitoring result represent?">
  It represents an answer captured for a specific prompt, model, configuration, and time. Provider output can vary between generations, so one answer is an observation rather than a universal result.
</Accordion>

<Accordion title="Can each prompt use a different frequency?">
  Yes. A prompt can inherit the workspace default or use Daily, Weekly, Monthly, or No monitoring. You can also pause or resume individual prompts from **Workspace > Prompts**.
</Accordion>

<Accordion title="What is a prompt boost?">
  A boost generates multiple answers for the selected prompt, model, and run. You can set 2 to 20 answers. Boosts increase credit use, and the workspace limits how many prompts can be boosted at once.
</Accordion>

<Accordion title="Does Qwairy crawl my website?">
  The answer-monitoring pipeline does not require a crawler or tracking tag on your site. Other workflows may fetch public pages you submit, including onboarding analysis, Site Diagnostics, and source analysis.
</Accordion>

## Metrics

<Accordion title="Why are Mention Rate and Coverage different?">
  They use different units and denominators. Mention Rate is answer-level and considers answers with a SELF or DIRECT brand mention. Dashboard Coverage is prompt-level and considers all distinct answered prompts in scope. See [Core Concepts](/documentation/get-started/core-concepts).
</Accordion>

<Accordion title="Why does the REST Coverage value differ from the dashboard?">
  The REST performance endpoint calculates answers with a SELF mention divided by all answers. The dashboard card calculates distinct answered prompts with a SELF mention divided by all distinct answered prompts. Use the definition for the surface you are reporting.
</Accordion>

<Accordion title="Why did a metric change after I reclassified a competitor?">
  Mention Rate, Citation Rate, and Share of Voice use SELF and DIRECT relationships. Reclassifying a detected brand changes which records enter those calculations for the selected scope.
</Accordion>

## Topics and prompts

<Accordion title="What happens when I delete a topic?">
  Qwairy keeps the prompts and unassigns them from the deleted topic. It also removes the topic from saved taxonomy references and cleans related topic projections. Assign another topic if you need those prompts in topic-level views.
</Accordion>

<Accordion title="Can one prompt have several tags?">
  Yes. A prompt can have multiple tags but at most one topic.
</Accordion>

## Credits and access

<Accordion title="What consumes credits?">
  Answer generation, Perception analysis, completed Site Diagnostics page audits, Content Studio article or brief creation and duplication, and Pitch Audit answer generation consume credits. Creating or importing prompt definitions is free. If automatic answers run afterward, each prompt costs the sum of the configured and available model costs; any boost increases that answer-generation cost. See [Providers & Credits](/documentation/get-started/credits).
</Accordion>

<Accordion title="How is a monitoring run calculated?">
  Multiply the number of prompts by the sum of the selected model costs, then include every additional answer requested by a boost. The interface shows an estimate before you save the configuration.
</Accordion>

<Accordion title="How can I buy more credits?">
  Owners of paid parent teams can buy credit packs under **Team Management > Billing**. Free teams must upgrade first. Sub-teams receive credits allocated by their parent organization.
</Accordion>

<Accordion title="Does Fact Check consume credits?">
  No. Fact Check is a private-beta workflow and does not debit customer credits.
</Accordion>

<Accordion title="How can I share or export data?">
  Use **Workspace > Shared Links** for shareable views and **Workspace > Exports** for generated files. Team integrations include the REST API, MCP Server, and Looker Studio where enabled for the account.
</Accordion>

## Troubleshooting

<Accordion title="Why is a page empty?">
  Check the current brand, date range, saved list, and filters. Confirm that answers exist for the selected prompts and providers. Some insight pages appear only when the corresponding answer metadata was detected.
</Accordion>

<Accordion title="Where do I correct a detected competitor or source?">
  Use **Monitor > Competitor Mentions** to change a brand relationship. Use **Monitor > Source Explorer** to inspect source ownership and type.
</Accordion>


# Interpreting Your First Results
Source: https://docs.qwairy.co/documentation/get-started/first-results

Review the first monitoring snapshot, verify its scope, and trace dashboard metrics back to prompts and answers.

A first monitoring run is a snapshot of the selected prompts and models. Treat it as an initial observation, not as a trend.

## Check the scope first

Before interpreting a percentage, confirm:

* the expected prompts generated answers;
* the intended providers, country, and language were selected;
* topics, tags, and funnel stages are assigned correctly;
* direct competitors are classified as DIRECT rather than INDIRECT or IGNORED;
* the date range includes the run you want to review.

## Read the Overview

Open **Cockpit > Overview**. The five cards summarize different parts of the selected dataset:

* Mention Rate and Citation Rate use only answers with a SELF or DIRECT denominator;
* Share of Voice counts mention occurrences, not distinct answers;
* Average Sentiment summarizes scored mentions;
* Coverage works at the distinct-prompt level.

See [Core Concepts](/documentation/get-started/core-concepts) before comparing these values with an export or API response.

## Inspect the evidence

Open **Monitor > Response Analysis** to read individual answers. Use prompt, answer, funnel, competitor, source, and insight filters to narrow the table.

Then use:

* **Monitor > Competitor Mentions** to verify brand relationships;
* **Monitor > Source Explorer** to inspect cited domains and pages;
* **Cockpit > GEO Matrix** to compare a metric across providers and prompt groupings.

## When data is sparse

An empty chart can mean that no answer matches the current filters, that a provider did not return data, or that the relevant signal was not detected. Widen the date range and clear filters before changing the prompt set.

If answers exist but do not address the intended question, revise ambiguous prompts in **Workspace > Prompts**. Keep the old and new wording separate if you need to preserve historical comparability.

## Build a trend

Use repeated runs with a stable prompt set, provider selection, and market to build a comparable time series. Document configuration changes when interpreting a break in the trend.


# Quickstart
Source: https://docs.qwairy.co/documentation/get-started/quickstart

Set up a brand, review generated topics and prompts, choose monitoring settings, and inspect the first answers.

The onboarding flow creates the first monitoring configuration for a brand. Review each generated field before starting a run.

## Before you begin

Have the following information ready:

* the public website URL for the brand;
* the country or market you want to observe;
* the products, services, and competitors that matter to the analysis.

Qwairy may fetch the submitted website and use public web context during onboarding. The generated description, topics, prompts, and competitors are suggestions that you can edit.

## Complete onboarding

<Steps>
  <Step title="Enter the website">
    Submit the public URL for the brand. Qwairy analyzes the page and proposes a brand profile.
  </Step>

  <Step title="Review the brand profile">
    Check the name, description, domain, language, and market. Correct any incomplete or inaccurate field before continuing.
  </Step>

  <Step title="Review topics and prompts">
    Keep the topics that match your monitoring scope. The onboarding flow can start with up to **5 topics** and **50 prompts**. Edit or remove prompts that are ambiguous, duplicated, or outside the intended market.
  </Step>

  <Step title="Review competitors">
    Confirm that direct competitors are classified correctly. You can add, edit, favorite, ignore, or reclassify competitors later.
  </Step>

  <Step title="Choose monitoring settings">
    Select the AI models and a default frequency. With auto-generate enabled, answers run immediately after setup; otherwise they wait for a manual or scheduled run.

    Credit cost equals the number of prompts multiplied by the sum of the selected model costs, plus any additional answers requested by boosts. The total is displayed before confirmation. See [Providers & Credits](/documentation/get-started/credits).
  </Step>
</Steps>

## After onboarding

Open **Workspace > Prompts** to review the resulting prompt list. Each prompt can inherit the workspace frequency or use its own Daily, Weekly, Monthly, or No monitoring setting. You can also pause a prompt or configure a boost for additional answers per model and run.

Then open **Cockpit > Overview** and **Monitor > Response Analysis**. The first view summarizes the selected dataset; the second lets you inspect the answers behind it.

<Note>
  Deleting a topic does not delete its prompts. Qwairy unassigns those prompts, removes the topic from saved taxonomy references, and cleans the related topic projections. Reassign the prompts if you still want a topic-level breakdown.
</Note>

## Next steps

* [Configure Monitoring](/documentation/workspace/monitoring)
* [Manage Prompts](/documentation/workspace/prompts)
* [Interpret the First Results](/documentation/get-started/first-results)


# What is Qwairy
Source: https://docs.qwairy.co/documentation/get-started/what-is-qwairy

Learn how Qwairy observes brand visibility in AI answers and turns monitoring data into analysis and actions.

Qwairy is a Generative Engine Optimization (GEO) platform. It monitors how selected AI providers answer the prompts that matter to your brand.

For each monitored answer, Qwairy identifies signals such as brand mentions, cited sources, competitors, and sentiment. The product then groups those observations by provider, prompt, topic, tag, funnel stage, and time period.

## The monitoring loop

1. Define the prompts that represent your audience's questions.
2. Select the AI providers and models to monitor.
3. Generate answers manually or on a schedule.
4. Review visibility metrics and the underlying answers.
5. Use the analysis to prioritize further investigation or work.

Monitoring records what providers returned for a particular prompt, model, location, and time. It does not show every answer that every user may receive.

## What Qwairy measures

The Overview combines five product metrics:

* **Mention Rate**: how often your brand appears among answers that mention your brand or a direct competitor.
* **Citation Rate**: how often your domain is cited among answers that cite your domain or a direct competitor's domain.
* **Share of Voice**: your share of mention occurrences across your brand and direct competitors.
* **Average Sentiment**: the average sentiment score attached to the selected brand's mentions.
* **Coverage**: the share of distinct answered prompts that contain at least one mention of your brand.

See [Core Concepts](/documentation/get-started/core-concepts) for the complete definitions and denominators.

## Website access

The answer-monitoring pipeline sends prompts to selected AI providers and analyzes their answers. It does not require a tracking tag or a crawler installed on your site.

Other Qwairy workflows may fetch public pages you submit. This includes onboarding analysis, Site Diagnostics, and source analysis. Review the relevant workflow before entering a private or restricted URL.

## Where to start

* [Quickstart](/documentation/get-started/quickstart)
* [Interpreting Your First Results](/documentation/get-started/first-results)
* [Providers & Credits](/documentation/get-started/credits)


# AI Revenue
Source: https://docs.qwairy.co/documentation/measure/ai-revenue

Attribute configured business conversions to AI referral or acquisition evidence while keeping measured revenue separate from estimated value.

<Info>
  AI Revenue is available on active paid plans and requires a supported analytics connection. Managers and Owners can connect providers and change tracked outcomes. Until a configuration is saved, Qwairy uses Purchases with provider-native value by default.
</Info>

Open **Measure > AI Revenue** to review purchases, leads, sign-ups, or other configured business conversions that the connected analytics provider associates with AI referral or acquisition evidence.

This is analytics-source attribution. Depending on the selected mode, it uses referral evidence from the converting session, first-acquisition evidence, or a deduplicated combination of both. It does not prove that Qwairy activity or an AI answer caused a conversion.

## Supported connections

| Provider           | Available conversion sources                    |
| ------------------ | ----------------------------------------------- |
| Google Analytics 4 | Purchases and discovered events                 |
| Piwik PRO          | Purchases and discovered events                 |
| Matomo             | Purchases and discovered goals                  |
| Piano Analytics    | Purchases and the supported Transactions metric |
| Adobe Analytics    | Purchases and discovered metrics                |

Amplitude powers Referrer Analytics but not AI Revenue.

Connect or change a provider from [Analytics Integrations](/documentation/measure/integrations/overview). The available actions depend on your team role.

## Configure conversions

Open the **Conversions** selector to choose the outcomes that matter to your business:

1. Select each conversion source you want to measure. Selected definitions contribute to the totals.
2. For discovered lead conversions, leave the optional value empty to use a native value when available or to count without value. Enter a fixed value when you need an estimate.
3. If a conversion is not discovered, a Manager or Owner can add its provider event, goal, or metric identifier manually.
4. Save the configuration.

The default definition is **Purchases** with its provider-native ecommerce value. Other available definitions depend on the connected provider and source. You can track up to 20 selected business outcomes.

<Warning>
  If several definitions contribute to totals, one visitor can complete more than one conversion. The total is the sum of the included definitions and is not necessarily a count of unique people.
</Warning>

## Read the results

| Metric           | Meaning                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| AI Conversions   | Included conversion occurrences associated with recognized AI sources under the selected attribution rules |
| Conversion Rate  | Included AI conversions divided by the AI-associated sessions in the selected attribution scope            |
| Measured Revenue | Provider-native revenue from included definitions configured with native value                             |
| Estimated Value  | Included conversions configured with a fixed value, multiplied by that fixed value                         |

The page also breaks results down by conversion definition, AI source, period, and top converting landing page. The site conversion totals and rate provide a same-provider baseline.

For GA4, the dashboard defaults to **Combined** attribution. A row is credited once: first to an AI session source when present, otherwise to an AI first-user source. Use **Direct session** to restrict attribution to the converting session or **First acquisition** to restrict it to the user's original acquisition source. The MCP `get_ai_revenue` tool currently uses Direct session attribution for GA4.

Measured Revenue and Estimated Value are separate evidence classes. Measured Revenue is provider-native and is not converted by Qwairy. The current response does not identify its currency, so the interface labels the amount as `native`; confirm the property currency in the provider. Estimated Value uses the currency configured in Qwairy. Do not add the two values unless you have confirmed they share a currency, and do not describe an estimate as observed revenue.

## Validate the result

1. Confirm the analytics property, site, or report suite.
2. Check the date range and reporting time zone.
3. Review every selected conversion definition and optional fixed value.
4. Verify that the corresponding purchases, events, goals, or metrics are populated in the source system.
5. Compare the provider total with a matching source-system segment.
6. Review warnings and document attribution, consent, and currency limitations in external reporting.

Data can be missing when referrer information is removed, tracking is blocked, the provider uses a different domain, the selected conversion is not populated, or its instrumentation is incomplete. A connected provider with no conversion data for the selected period is different from a disconnected provider.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [Referrer Analytics](/documentation/measure/referrer-analytics)
* [Page Performance](/documentation/measure/page-performance)
* [MCP Measure tools](/mcp/tools/measure)


# Bing Webmaster Tools
Source: https://docs.qwairy.co/documentation/measure/bing-webmaster

Connect a Bing site, review query and page search data, and export the selected reporting scope.

Open **Measure > Bing Webmaster Tools** to connect a Bing site and inspect its search performance data.

## Connect a site

1. Select **Connect**.
2. Enter a Bing Webmaster Tools API key.
3. Choose the site that matches the monitored brand.
4. Confirm the connection and wait for the available data to load.

Treat the API key as a credential. Use the permissions and rotation process defined by your organization.

## Queries tab

The **Queries** tab shows search queries and the metrics returned for the selected site and date range. Use search, sorting, and filters to locate relevant terms.

Where the Track action is available, review the wording before adding a query to the Qwairy prompt set.

## Pages tab

The **Pages** tab groups the available search metrics by URL. Confirm redirects, canonicalization, and site-property scope when one page appears under several URLs.

## Interpretation

Bing Webmaster Tools data describes Bing Search activity. It can provide context for Microsoft-related discovery, but it does not establish that a page influenced a specific AI answer.

## Export and troubleshooting

Export the current filtered view when needed. If data is missing, check the site selection, API-key access, reporting delay, and date range in both Qwairy and Bing Webmaster Tools.


# Crawler Analytics
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics

Configure a supported server-log collector and analyze retained snapshots of requests classified as AI crawlers.

<Info>
  Crawler Analytics is available on Business, Enterprise, and Agency Business plans, or through an explicit feature override.
</Info>

Open **Measure > Crawler Analytics** to review crawler requests accepted from a connected log source. The setup flow is under **Settings** on that page.

Crawler Analytics stores bounded daily aggregates. It does not retain raw traffic events or human activity, and it does not prove that a requested page was indexed, used for training, or cited.

## Choose one delivery source

The setup page exposes these collectors:

| Source                                                                                         | Method                                           | Requirement              | Ingestion path            |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------ | ------------------------- |
| **[Vercel](/documentation/measure/crawler-analytics/connectors/vercel)**                       | Drains, JSON logs                                | Vercel Pro or Enterprise | `/api/v1/logs/vercel`     |
| **[Cloudflare Logpush](/documentation/measure/crawler-analytics/connectors/cloudflare)**       | Managed HTTP destination                         | Cloudflare Enterprise    | `/api/v1/logs/cloudflare` |
| **[AWS CloudFront](/documentation/measure/crawler-analytics/connectors/aws-cloudfront)**       | Standard Logging v2 through Amazon Data Firehose | CloudFront and Firehose  | `/api/v1/logs/cloudfront` |
| **[Akamai](/documentation/measure/crawler-analytics/connectors/akamai)**                       | DataStream 2                                     | Akamai DataStream 2      | `/api/v1/logs/akamai`     |
| **[Fastly](/documentation/measure/crawler-analytics/connectors/fastly)**                       | HTTPS Logging                                    | Fastly CDN service       | `/api/v1/logs/fastly`     |
| **[Netlify](/documentation/measure/crawler-analytics/connectors/netlify)**                     | General HTTP Log Drain                           | Netlify Enterprise       | `/api/v1/logs/netlify`    |
| **[Generic HTTP API](/documentation/measure/crawler-analytics/connectors/generic-http)**       | Server-side HTTP collector                       | A server runtime         | `/api/v1/logs/ingest`     |
| **[Cloudflare Worker](/documentation/measure/crawler-analytics/connectors/cloudflare-worker)** | Edge collector recipe                            | Cloudflare Workers       | `/api/v1/logs/cloudflare` |
| **[WordPress](/documentation/measure/crawler-analytics/connectors/wordpress)**                 | PHP collector recipe                             | PHP 7.4 or later         | `/api/v1/logs/ingest`     |

AWS CloudFront is an active connector in the current setup flow. It is not a coming-soon integration.

A brand uses one activated delivery source. After activation, changing provider requires an explicit migration. A pending, unactivated connector can be replaced from the setup flow.

## Create and protect a key

Create a dedicated key for the selected source. The plaintext secret is shown once; later the interface shows only its prefix.

You can keep up to **5 active keys** for an integration. To rotate, create the replacement, update the source, confirm delivery, and then delete the old key.

Choose an IANA time zone when creating the first key. It defines daily snapshots and becomes immutable after activation.

## Provider-specific boundaries

### Managed streams

* **Vercel** sends Static and Runtime production logs as JSON. Vercel cannot filter the drain by user agent, so forwarded human rows are discarded by Qwairy but can still count toward Vercel delivery volume. Sampling makes totals partial.
* **Cloudflare Logpush** should send only the fields listed by the setup page and apply its crawler pre-filter. The job must use `max_upload_bytes: 5000000` and `max_upload_records: 10000`.
* **CloudFront** uses the exact Standard Logging v2 field list shown in setup, JSON output, a Firehose HTTP buffer of 1 MiB and 60 seconds, and S3 failure backup. Shorter delivery intervals are unsupported.
* **Akamai** uses the listed DataStream 2 fields, JSON output, Log User-Agent Header, and a push frequency of 60 seconds or longer.
* **Fastly** uses the provided minimal JSON format. Its setup allows up to 10,000 entries and 2,000,000 bytes per request; JSON arrays, NDJSON, and gzip are supported.
* **Netlify** sends its full Traffic Logs stream and has no crawler-only drain filter. User-Agent must remain available for classification. Qwairy ignores the client IP field and does not retain queries, human rows, or raw payloads.

For high-volume sources that cannot filter before delivery, evaluate provider delivery cost and the ingestion ceilings before activation.

### Edge and application collectors

The Generic HTTP API accepts `POST` requests with `Content-Type: application/json` and `X-API-Key`. Each useful record contains method, path, hostname, user agent, timestamp, and optionally status code.

Filter for known AI crawler user agents in your server or edge layer before sending. A generic batch can contain up to **1,000 records** and the normalized batch ceiling is **2,000,000 bytes**.

The Cloudflare Worker and WordPress recipes apply this collector pattern at the edge or application layer. Review generated code before deployment and keep the key in a server-side secret.

## Processing rules

The setup page lets you exclude paths and user agents before aggregation. Patterns are case-insensitive and support wildcards, one per line.

You can configure up to **32 path rules** and **32 user-agent rules**. Each pattern is limited to 256 bytes and each rule set to 4,096 bytes.

## Read the dashboard

The available ranges are Last 24 hours, Last 7 days, and Last 30 days. Crawler Analytics uses analytic days in the integration's configured time zone. **Last 24 hours** means the current analytic day, from its local midnight through the current snapshot; it is not a rolling 24-hour window. The other presets include the current analytic day and the preceding 6 or 29 analytic days.

Dashboard totals, crawler breakdowns, charts, and page tables use the public set of supported observable AI-specific User-Agent identities. The ingestion registry can recognize additional identities for classification and compatibility, but those identities are excluded from the current public totals and tables.

Classification matches a supported token in the HTTP User-Agent. Qwairy does not verify source IP or reverse DNS, so an occurrence is evidence of the received identity string, not proof of the requester's origin. Traditional search crawlers and robots-policy tokens such as `Google-Extended` are excluded from public occurrence totals.

The current public identity set is:

* `Claude-SearchBot`, `MistralAI-Index`, `OAI-SearchBot`, and `PerplexityBot`;
* `ChatGPT-User`, `Google-GeminiNotebook`, `MistralAI-User`, `Perplexity-User`, `Claude-User`, and `Google-CloudVertexBot`;
* `ClaudeBot`, `GPTBot`, and `GrokBot`.

`Google-NotebookLM` is accepted as an HTTP alias of the canonical `Google-GeminiNotebook` identity.

The page shows:

* observed occurrences;
* pages that returned at least one HTTP 2xx to a classified crawler;
* crawler identities observed;
* average frequency across observed daily buckets;
* trends, crawler distribution, page state, status-code groups, and page details.

Page states are computed as follows:

* **New**: the first retained page observation falls within the last 7 days, including the boundary (`firstSeenAt >= now - 7 days`).
* **Hot**: the page is in the top decile by supported-crawler occurrences over the current 7 analytic days, has activity on at least 2 of those days, and is not neglected.
* **Neglected**: the most recent retained page observation is strictly older than the 30-day boundary.

`New` and `Hot` can appear together. `Neglected` is exclusive and cannot appear with either state. The hot calculation always uses the current 7-analytic-day window, independently of the dashboard range selected for displayed occurrences.

Missing delivery is not inferred as zero. The interface distinguishes observed, not measured, and incomplete-ingestion states. Quota or provider gaps produce `incomplete_ingestion`. The `≥` marker is reserved for a count whose numeric precision is capped; at-least-once delivery is reported separately because repackaged retries can duplicate observations.

Page-by-crawler daily rollups are retained for **30 analytic days**. Delivery continuity evidence is retained for **13 months**. Durable page identities keep `firstSeenAt`, `lastSeenAt`, and `lifetimeCount` after the daily rollups expire. A page identity is created only after at least one HTTP 2xx response.

## Path privacy and matching

Before aggregation, Qwairy removes query strings and fragments. Sensitive-looking segments, including long numeric identifiers, email addresses, UUIDs, long hexadecimal values, JWTs, and high-entropy tokens, are replaced with an integration-scoped one-way pseudonym. Paths beyond the supported length are also bounded with a pseudonym.

Occurrence counts and lifecycle timestamps remain real, but a pseudonymized path is not reconstructible or linkable across integrations. Page Performance does not attach a title to it and excludes it from GA4, Search Console, and Bing matching.

Technical ingestion ceilings are **10,000,000 events per integration per day** and **200,000,000 events per billed team per day**. They protect shared infrastructure and do not cap page cardinality.

## Validate the connection

1. Use the endpoint and authentication scheme displayed for the chosen source.
2. Send the provider's test event or a permitted crawler request.
3. Wait for the connector to move from pending to connected after accepted rollup data.
4. Check delivery-continuity warnings before interpreting a zero.
5. Compare equivalent, unsampled source logs when reconciling totals.

## Related pages

* [Site Readiness](/documentation/optimize/site-readiness)
* [Page Performance](/documentation/measure/page-performance)


# Akamai DataStream 2
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/akamai

Configure an Akamai DataStream 2 custom HTTPS destination for Crawler Analytics.

Use Akamai DataStream 2 to send a minimal JSON request dataset to Crawler Analytics through a custom HTTPS destination.

## Before you start

You need:

* Akamai DataStream 2 for the target property;
* permission to change Property Manager logging and activate a stream;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

## Create and protect the key

1. In Crawler Analytics settings, select **Akamai**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone used for daily snapshots.
4. Copy the secret when it appears. It cannot be displayed again.
5. Store it as the Basic authentication password for the custom HTTPS destination.

To rotate the key, create a replacement, update and activate the destination, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Configure the stream

1. In Akamai Control Center, create or edit a DataStream 2 stream for the target property.

2. Include exactly these request fields:

   ```text theme={null}
   statusCode
   reqTimeSec
   reqHost
   reqMethod
   reqPath
   UA
   ```

3. Select **JSON** as the log format.

4. In Property Manager, enable **Log Request Details** and **Log User-Agent Header** so `UA` is populated.

5. Set the push frequency to 60 seconds or longer.

6. Choose a **Custom HTTPS** destination and set:

   | Setting        | Value                                      |
   | -------------- | ------------------------------------------ |
   | Endpoint URL   | `https://www.qwairy.co/api/v1/logs/akamai` |
   | Content type   | `application/json`                         |
   | Authentication | Basic                                      |
   | Username       | `qwairy`                                   |
   | Password       | The Qwairy connector secret                |

7. If the property can match known AI crawler user agents before streaming, apply that condition. Otherwise keep the dataset minimal and let Qwairy discard unrecognized rows.

8. Review and activate the stream.

See [Akamai's custom HTTPS destination guide](https://techdocs.akamai.com/datastream2/v2/docs/stream-custom-https) for the current provider workflow.

## Test delivery

Use Akamai's destination validation or a mock stream to verify the HTTPS and Basic authentication settings. A validation payload does not necessarily contain an accepted crawler record.

After activation, request a safe path on the monitored hostname with a recognized crawler User-Agent:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Check the DataStream delivery status. Qwairy changes the connector from pending after a valid crawler row reaches the rollup pipeline.

## Limits, sampling, and cost

* Qwairy accepts Akamai wire deliveries up to 4,000,000 bytes. DataStream can split larger provider files into additional deliveries.
* Keep the push frequency at 60 seconds or longer for this connector.
* A DataStream sample below 100%, or a Property Manager rule that excludes requests, makes Qwairy totals partial for that scope.
* The minimal field list excludes client address, query, cookie, and referrer data.
* DataStream delivery and destination traffic may carry Akamai charges. Shared Qwairy daily ceilings also apply.

## Troubleshooting

* **Destination validation fails**: confirm HTTPS, `application/json`, Basic authentication, username `qwairy`, and the current connector secret.
* **Qwairy stays pending**: confirm the stream is active, the push frequency is supported, and `UA`, `reqHost`, `reqMethod`, `reqPath`, and `reqTimeSec` are populated.
* **Rows are acknowledged but not counted**: only current `GET` and `HEAD` rows for the configured hostname with a recognized crawler User-Agent are aggregated.
* **Counts are lower than Akamai reports**: check the DataStream sampling rate, Property Manager match criteria, upload errors, Qwairy exclusion rules, and equivalent time windows.
* **Delivery is intermittent**: review the destination's DataStream upload metrics and alerts before interpreting missing periods as zero.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# AWS CloudFront through Firehose
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/aws-cloudfront

Send CloudFront Standard Logging v2 records to Crawler Analytics through Amazon Data Firehose.

Use CloudFront Standard Logging v2 with Amazon Data Firehose to deliver a minimal JSON request dataset to Crawler Analytics.

## Before you start

You need:

* a CloudFront distribution serving the hostname configured for the Qwairy brand;
* permission to configure Standard Logging v2, Firehose, IAM, CloudWatch, and an S3 failure-backup bucket;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

CloudFront requires its Firehose log-delivery destination in `us-east-1`.

## Create and protect the key

1. In Crawler Analytics settings, select **AWS CloudFront**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone used for daily snapshots.
4. Copy the secret when it appears. Qwairy shows only its prefix later.
5. Store it as the Firehose HTTP endpoint access key. Do not add it to a URL, source repository, or CloudWatch log message.

To rotate the key, create a replacement, update Firehose, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Configure Firehose

1. In `us-east-1`, create an Amazon Data Firehose delivery stream with an HTTP endpoint destination.

2. Set the endpoint URL to:

   ```text theme={null}
   https://www.qwairy.co/api/v1/logs/cloudfront
   ```

3. Use the Qwairy connector secret as the Firehose **Access key**. Firehose adds the required `X-Amz-Firehose-Access-Key` header.

4. Set the HTTP buffer size to **1 MiB** and the interval to **60 seconds**. Shorter delivery intervals are not supported by this connector.

5. Enable S3 backup for failed HTTP deliveries and enable Firehose error logging in CloudWatch.

6. Grant the Firehose role access to the backup bucket and required log resources.

## Configure Standard Logging v2

1. In CloudFront, create or edit a Standard Logging v2 configuration for the distribution.

2. Select **JSON** output.

3. Select the Firehose stream as the delivery destination.

4. Use exactly this field list:

   ```text theme={null}
   timestamp(ms),x-edge-request-id,sc-status,cs-method,cs-uri-stem,cs(Host),cs(User-Agent)
   ```

   This list excludes client address, query, cookie, and referrer fields.

5. Enable the logging configuration.

See [CloudFront Standard Logging v2](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/standard-logging.html) and [Firehose HTTP backup settings](https://docs.aws.amazon.com/firehose/latest/dev/create-configure-backup.html) for the current AWS controls.

## Test delivery

After enabling both configurations, request a safe path on the distribution hostname with a recognized crawler User-Agent:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Check the Firehose HTTP delivery metrics and CloudWatch error log. A successful Qwairy response includes the Firehose request ID. The connector changes from pending after an accepted CloudFront row reaches the rollup pipeline.

Generic Firehose demo records do not use the CloudFront Standard Logging v2 shape and therefore do not prove that crawler aggregation is configured correctly.

## Limits, delivery, and cost

* Keep the HTTP buffer at 1 MiB and 60 seconds. This keeps the base64 Firehose envelope inside Qwairy's 2,000,000-byte wire boundary.
* A delivery can contain at most 10,000 Firehose records or parsed occurrences for this route.
* Upstream exclusions make the resulting crawler counts partial. Compare only equivalent CloudFront and Qwairy scopes.
* CloudFront logging, Firehose delivery, CloudWatch error logs, and S3 backup can each incur AWS charges.
* Shared Qwairy daily ingestion ceilings also apply.

## Troubleshooting

* **401 from the HTTP endpoint**: confirm that Firehose uses the current Qwairy secret as its Access key.
* **400 invalid delivery request**: verify that the source is CloudFront Standard Logging v2, output is JSON, the exact field list is selected, and the Firehose request ID is preserved.
* **413 payload too large**: restore the 1 MiB Firehose buffer and check that no transformation expands individual records.
* **415 unsupported encoding**: use the Firehose HTTP delivery encoding supported by the setup and keep the destination content type as JSON.
* **Firehose retries or writes to S3 backup**: inspect CloudWatch delivery errors, IAM permissions, endpoint settings, and buffering hints.
* **Qwairy stays pending**: confirm that logging is enabled on the intended distribution and generate a current `GET` or `HEAD` request with a recognized crawler User-Agent to the configured hostname.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Cloudflare Logpush
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/cloudflare

Configure a bounded Cloudflare Logpush HTTP job for Crawler Analytics.

Use Cloudflare Logpush to send a filtered HTTP Requests dataset to Crawler Analytics.

## Before you start

You need:

* a Cloudflare Enterprise zone with Logpush access;
* permission to create the Logpush job;
* a Cloudflare API token with `Logs Write` permission to apply the required upload bounds;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

## Create and protect the key

1. In Crawler Analytics settings, select **Cloudflare Logpush**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone used for daily snapshots.
4. Copy the secret when it appears. Qwairy shows only its prefix later.
5. Keep it in the Logpush destination header configuration. Do not place it in an ordinary query parameter, source control, or client-side code.

To rotate the key, create a replacement, update the Logpush destination, validate delivery, and then delete the previous key. An integration can have up to five active keys.

## Create the Logpush job

1. In Cloudflare, open **Analytics & Logs > Logs > Add Logpush job** for the target zone.

2. Select the HTTP Requests dataset and an **HTTP destination**.

3. Use this destination configuration, replacing the placeholder with the one-time Qwairy secret:

   ```text theme={null}
   https://www.qwairy.co/api/v1/logs/cloudflare?header_Authorization=Bearer%20YOUR_CRAWLER_KEY
   ```

   Cloudflare converts `header_Authorization` into an HTTP header. The space after `Bearer` must remain encoded as `%20`.

4. Select only these fields:

   ```text theme={null}
   ClientRequestHost
   ClientRequestMethod
   ClientRequestPath
   ClientRequestUserAgent
   EdgeResponseStatus
   EdgeStartTimestamp
   ```

5. Keep the timestamp format as RFC 3339.

6. Before enabling the job, use the Cloudflare Logpush API to set:

   ```json theme={null}
   {
     "max_upload_bytes": 5000000,
     "max_upload_records": 10000
   }
   ```

   The default upload size is outside Qwairy's bounded route contract.

7. Add this job filter. It deliberately over-matches several crawler families; Qwairy's registry performs the final classification.

   ```json theme={null}
   {"where":{"or":[{"key":"ClientRequestUserAgent","operator":"contains","value":"Bot"},{"key":"ClientRequestUserAgent","operator":"contains","value":"bot"},{"key":"ClientRequestUserAgent","operator":"contains","value":"User"},{"key":"ClientRequestUserAgent","operator":"contains","value":"MistralAI"},{"key":"ClientRequestUserAgent","operator":"contains","value":"Notebook"},{"key":"ClientRequestUserAgent","operator":"contains","value":"Google-Agent"},{"key":"ClientRequestUserAgent","operator":"contains","value":"meta-"},{"key":"ClientRequestUserAgent","operator":"contains","value":"Meta-"},{"key":"ClientRequestUserAgent","operator":"contains","value":"spider"},{"key":"ClientRequestUserAgent","operator":"contains","value":"omgili"},{"key":"ClientRequestUserAgent","operator":"contains","value":"Extended"}]}}
   ```

8. Keep sampling at 100% for the filtered dataset, then enable the job.

See [Cloudflare's HTTP destination guide](https://developers.cloudflare.com/logs/logpush/logpush-job/enable-destinations/http/) for the current dashboard and API controls.

## Test delivery

Cloudflare validates the destination with a gzip-compressed `{"content":"tests"}` payload. The Qwairy route accepts that challenge, but it does not create a crawler aggregate.

After validation, request a safe path on the monitored zone with a recognized crawler User-Agent:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Check the Logpush job for a successful upload. Qwairy moves the connector from pending after an accepted crawler row reaches the rollup pipeline.

## Limits, sampling, and cost

* Each Logpush upload is limited to 5,000,000 uncompressed bytes and 10,000 records.
* The pre-filter reduces delivery volume but intentionally includes some rows that Qwairy later discards.
* A Cloudflare sampling rate below 100% produces partial Qwairy counts.
* Logpush delivery and retained provider logs may carry Cloudflare charges. Review current pricing for the target zone.
* Shared daily ingestion ceilings also apply.

## Troubleshooting

* **Destination validation fails**: confirm the `%20` encoding, current secret, HTTPS endpoint, and required upload bounds.
* **401**: verify that the destination still sends `Authorization: Bearer YOUR_CRAWLER_KEY` and that the key belongs to Cloudflare Logpush.
* **400 with too many logs**: set `max_upload_records` to `10000` before enabling the job.
* **413**: set `max_upload_bytes` to `5000000` and check compression or decoded payload size.
* **Qwairy stays pending**: verify the six selected fields, the User-Agent filter, 100% sampling, and a current request to the configured hostname.
* **Counts are lower than Cloudflare logs**: compare the same filter and sampling scope, then check Qwairy exclusions and delivery-continuity warnings.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Cloudflare Worker
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/cloudflare-worker

Deploy Qwairy's generated edge collector on a Cloudflare Worker route and verify crawler delivery safely.

Use the Cloudflare Worker collector when the monitored site is proxied through Cloudflare but Cloudflare Logpush is not the selected delivery source. The Worker filters known AI crawler User-Agents, forwards the request to the origin, and reports eligible page responses to Qwairy.

<Warning>
  Use the **Cloudflare Worker** key created by this setup. A Cloudflare Logpush or Generic HTTP key belongs to a different provider contract and is rejected or discarded by this endpoint.
</Warning>

## Before you start

You need:

* access to **Measure > Crawler Analytics > Settings** for the brand;
* a Cloudflare Worker attached to the hostname configured for that brand;
* permission to create an encrypted Worker secret and attach a production route;
* a test page that returns `text/html` or `text/plain`.

Only activate one delivery source for a brand. Running this Worker alongside another active collector can duplicate observations.

## Create and protect the key

1. In Crawler Analytics settings, select **Cloudflare Worker**.
2. Select **Create Key**.
3. Enter a descriptive name and the IANA time zone used for daily analytics.
4. Copy the plaintext secret when it appears. Qwairy shows only its prefix later.
5. Store it as the encrypted Worker secret `QWAIRY_API_KEY`.

Do not put the key in Worker source, ordinary environment variables, request URLs, browser code, or logs. Leave `QWAIRY_ENDPOINT` unset unless Qwairy explicitly gives you a different endpoint.

## Deploy the generated Worker

Create `worker.js` with the recipe generated by the current Qwairy setup:

```javascript theme={null}
/**
 * Qwairy Crawler Analytics - Cloudflare Worker
 *
 * Setup:
 * 1. Create a new Worker in Cloudflare dashboard
 * 2. Set environment variables: QWAIRY_API_KEY, QWAIRY_ENDPOINT (optional)
 * 3. Deploy to a route (e.g., yourdomain.com/*)
 */

const IGNORE_EXTENSIONS = /\.(?:png|jpe?g|gif|svg|webp|ico|mp4|webm|css|js|json|xml|woff2?|ttf|eot|map)$/i;
const IGNORE_PATHS = [/^\/api\//i, /^\/dashboard\//i, /^\/_next\//i, /^\/favicon/i];
const AI_CRAWLER_UA = /(?:^|[^a-z0-9_-])(?:Claude-SearchBot|MistralAI-Index|OAI-SearchBot|PerplexityBot|ChatGPT-User|Google-GeminiNotebook|Google-NotebookLM|Google-Agent|MistralAI-User|Perplexity-User|Claude-User|Google-CloudVertexBot|ClaudeBot|GPTBot|GrokBot|meta-webindexer|Amzn-User|Meta-ExternalFetcher|AI2Bot|Ai2Bot-Dolma|Amazonbot|Bytespider|CCBot|Meta-ExternalAgent|DuckAssistBot|KimiBot|Kimi-SearchBot|YouBot|Kimi-User|Diffbot|Kangaroo Bot|omgili|omgilibot|PanguBot|Timpibot|Webzio-Extended)(?=$|[^a-z0-9_-])/i;

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);
    const pathname = url.pathname;
    const userAgent = request.headers.get('User-Agent') || '';

    if (!AI_CRAWLER_UA.test(userAgent) || IGNORE_EXTENSIONS.test(pathname) || IGNORE_PATHS.some(r => r.test(pathname))) {
      return fetch(request);
    }

    const response = await fetch(request);
    const contentType = response.headers.get('content-type')?.split(';')[0];
    if (!contentType || !['text/html', 'text/plain'].includes(contentType)) {
      return response;
    }

    const apiKey = env.QWAIRY_API_KEY;
    const endpoint = env.QWAIRY_ENDPOINT || 'https://www.qwairy.co/api/v1/logs/cloudflare';
    if (!apiKey) return response;

    ctx.waitUntil(
      fetch(endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'X-API-Key': apiKey },
        body: JSON.stringify({
          status_code: response.status,
          request_method: request.method,
          request_path: pathname,
          hostname: request.headers.get('Host') || url.hostname,
          user_agent: userAgent,
          timestamp: new Date().toISOString(),
        }),
      }).catch(err => console.error('Qwairy: Failed to send log', err))
    );

    return response;
  },
};
```

Then:

1. Paste the recipe into the Worker.
2. Add `QWAIRY_API_KEY` as an encrypted secret with the one-time Qwairy value.
3. Attach the Worker to the exact production route to monitor, such as `www.example.com/*`.
4. Deploy the Worker and confirm normal requests still receive the origin response.

The generated recipe sends only the path, not the query string. Review your path design and add exclusions in Qwairy if path segments can contain sensitive identifiers.

## Verify delivery

Use a dedicated page that returns HTML and replace the example hostname. This synthetic request creates a crawler observation in the current analytic day:

```bash theme={null}
curl --user-agent "Mozilla/5.0 (compatible; GPTBot/1.1)" \
  --output /dev/null \
  --write-out "%{http_code}\n" \
  "https://www.example.com/docs/qwairy-collector-check"
```

1. Confirm the command returns the expected origin status.
2. In Qwairy, wait for the connector to move from pending to connected after the accepted event reaches a daily rollup.
3. Open the current analytic day and look for `/docs/qwairy-collector-check`.
4. If the connector stays pending, inspect Worker logs for `Qwairy: Failed to send log`, then confirm the route, secret, hostname, User-Agent, and response content type.

An origin response alone proves only that the Worker proxy path works. It does not prove that Qwairy accepted and rolled up the event.

## Limits and behavior

* The recipe reports only matching User-Agents on non-ignored paths whose origin response is `text/html` or `text/plain`.
* The recipe can attempt delivery for other HTTP methods, but Qwairy accepts only `GET` and `HEAD` records for aggregation.
* Static file extensions, `/api/`, `/dashboard/`, `/_next/`, and `/favicon` paths are ignored by the generated code.
* The Worker sends one Qwairy request per matching origin response. It has no delivery queue or retry loop, so network failures can create gaps.
* The integration route allows a burst of 120 ingestion requests per minute. The route can acknowledge over-limit Worker deliveries without aggregating them, so check coverage warnings after traffic spikes.
* Qwairy applies its maintained crawler registry, hostname checks, exclusions, late-arrival window, and ingestion ceilings after receipt.
* The shared technical ceilings are 10,000,000 events per integration per day and 200,000,000 events per billed team per day.
* The collector observes requests. It does not prove indexing, model training, or citation use.

## Rotate or roll back

To rotate the key, create a replacement in Qwairy, update the encrypted Worker secret, deploy, verify a new accepted observation, and then delete the previous key.

To roll back the collector:

1. Detach the Worker route or disable the Worker deployment.
2. Confirm the origin still serves normal traffic and no new Worker observations arrive.
3. Remove the Worker secret.
4. Revoke the corresponding Qwairy key.

Disabling delivery creates an analytics coverage gap. Check delivery-continuity warnings before comparing periods that cross the rollback.

## Related pages

* [Crawler Analytics](/documentation/measure/crawler-analytics)
* [Cloudflare Logpush](/documentation/measure/crawler-analytics/connectors/cloudflare)


# Fastly HTTPS Logging
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/fastly

Configure a bounded Fastly HTTPS logging endpoint for Crawler Analytics.

Use Fastly HTTPS Logging to deliver a minimal request record from a Fastly CDN service to Crawler Analytics.

## Before you start

You need:

* permission to edit and activate the target Fastly service;
* a service serving the hostname configured for the Qwairy brand;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

## Create and protect the key

1. In Crawler Analytics settings, select **Fastly**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone used for daily snapshots.
4. Copy the secret when it appears. It cannot be displayed again.
5. Keep it only in Fastly's custom header value or another restricted secret store.

To rotate the key, create a replacement, update the Fastly endpoint, activate the new service version, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Configure the HTTPS endpoint

1. In the target Fastly service, add an **HTTPS** logging endpoint.

2. Set the delivery URL to:

   ```text theme={null}
   https://www.qwairy.co/api/v1/logs/fastly
   ```

3. Fastly validates ownership through this public challenge endpoint:

   ```text theme={null}
   https://www.qwairy.co/.well-known/fastly/logging/challenge
   ```

   The challenge authorizes domain validation only. Log delivery still requires the connector key.

4. Use `POST`, set the content type to `application/json`, and add this custom header:

   ```text theme={null}
   X-API-Key: YOUR_CRAWLER_KEY
   ```

5. Set **Message type** to blank.

6. Set **Request max entries** to `10000` and **Request max bytes** to `2000000`.

7. Choose either an array of JSON or newline-delimited JSON. gzip compression is supported.

## Use the minimal log format

Paste this format into the HTTPS logging endpoint:

```text theme={null}
{
  "timestamp": "%{strftime(\{"%Y-%m-%dT%H:%M:%S.000Z"\}, time.start)}V",
  "host": "%{json.escape(req.http.Host)}V",
  "request_path": "%{json.escape(req.url.path)}V",
  "request_method": "%{json.escape(req.method)}V",
  "request_user_agent": "%{json.escape(req.http.User-Agent)}V",
  "response_status": %{resp.status}V
}
```

This format omits the client address, query string, cookies, and referrer. If your Fastly service already has a condition for known AI crawler user agents, apply it before delivery. Qwairy still performs authoritative classification on receipt.

Activate the updated service version on Production. See [Fastly HTTPS log streaming](https://www.fastly.com/documentation/guides/integrations/logging-endpoints/protocol-based-and-self-hosted/log-streaming-https/) for the current provider controls.

## Test delivery

First confirm that Fastly accepts the domain-control challenge. Then request a safe path on the monitored hostname:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Check Fastly's endpoint delivery status. Qwairy moves the connector from pending after an accepted log row reaches the rollup pipeline; a successful challenge alone does not connect it.

## Limits, filtering, and cost

* Keep the configured request boundaries at 10,000 entries and 2,000,000 bytes.
* Qwairy accepts JSON arrays, NDJSON, and gzip for this route and splits valid deliveries into bounded internal claims.
* Upstream filtering reduces delivered volume. Sampling or a condition that omits crawler requests makes counts partial for the excluded scope.
* Without an upstream condition, Fastly forwards other requests and Qwairy discards them after receipt. Those rows can still affect provider delivery volume and cost.
* Shared daily ingestion ceilings also apply.

## Troubleshooting

* **Endpoint validation fails**: confirm that the URL uses `www.qwairy.co` and that Fastly can reach the displayed well-known challenge path.
* **401**: check the exact `X-API-Key` header name and the current Fastly connector secret.
* **413**: restore the 2,000,000-byte request maximum or reduce the delivery size.
* **Logs are rejected or ignored**: keep Message type blank, use valid JSON or NDJSON, and preserve the timestamp, host, path, method, User-Agent, and status fields from the minimal format.
* **Qwairy stays pending**: activate the service version and generate a current `GET` or `HEAD` request with a recognized crawler User-Agent on the configured hostname.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Generic HTTP collector
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/generic-http

Send filtered server or edge request logs to Crawler Analytics through the generic ingestion endpoint.

Use the Generic HTTP API when you control a server or edge runtime and no managed connector matches your stack. Filter requests before delivery and send only the fields needed for crawler aggregation.

## Before you start

You need:

* access to **Measure > Crawler Analytics > Settings** for the brand;
* a server-side or edge runtime that can observe requests after routing;
* the hostname configured for the Qwairy brand;
* a secure secret store for the connector key.

The collector accepts only `GET` and `HEAD` request events for the configured brand hostname. An apex domain and its `www` form are treated as equivalent. Other subdomains need their own brand scope.

## Create and protect the key

1. In Crawler Analytics settings, select **Generic HTTP API**.
2. Select **Create Key**.
3. Enter a descriptive name and an IANA analytics time zone, such as `Europe/Paris`.
4. Copy the secret when it appears. Qwairy shows only its prefix later.
5. Store it as a server-side secret. Do not place it in browser code, source control, request URLs, or application logs.

To rotate the key, create a replacement, update the collector, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Send events

Send `POST` requests to:

```text theme={null}
https://www.qwairy.co/api/v1/logs/ingest
```

Use these headers:

```text theme={null}
Content-Type: application/json
X-API-Key: YOUR_CRAWLER_KEY
```

`Authorization: Bearer YOUR_CRAWLER_KEY` is also accepted. Prefer `X-API-Key` for the setup shown in Qwairy.

Each event used for aggregation needs these fields:

| Field            | Requirement                                                          |
| ---------------- | -------------------------------------------------------------------- |
| `request_method` | `GET` or `HEAD`                                                      |
| `request_path`   | Path for the requested page; query strings and fragments are removed |
| `hostname`       | Configured brand hostname, or its apex/`www` equivalent              |
| `user_agent`     | Full User-Agent used for crawler classification                      |
| `timestamp`      | Valid ISO 8601 event time                                            |
| `status_code`    | Optional HTTP response status                                        |

The API accepts one object, an array of objects, newline-delimited JSON, or an object with a `logs` array. A stable `Idempotency-Key` header or `batch_id` field lets byte-different retries be deduplicated.

Filter known AI crawler user agents in your runtime before calling the endpoint. Qwairy applies its maintained registry again on receipt and discards human, traditional-search, and unknown user agents.

## Test delivery

Replace the hostname and key before running this synthetic check:

```bash theme={null}
event_time=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
curl --request POST "https://www.qwairy.co/api/v1/logs/ingest" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $QWAIRY_CRAWLER_KEY" \
  --data "{\"request_method\":\"GET\",\"request_path\":\"/docs/crawler-check\",\"hostname\":\"www.example.com\",\"user_agent\":\"GPTBot/1.0\",\"timestamp\":\"${event_time}\",\"status_code\":200}"
```

A valid request returns a JSON acknowledgement. The connector changes from pending only after the rollup pipeline accepts an event in the configured brand scope. An endpoint health response or a filtered event does not establish that connection.

## Limits and delivery scope

* A generic request can contain at most 1,000 events and 2,000,000 normalized bytes.
* Events delivered more than 72 hours late fall outside the current late-arrival window.
* The shared ceilings are 10,000,000 events per integration per day and 200,000,000 events per billed team per day.
* Your runtime, network provider, or observability stack may charge for reading and forwarding logs.
* Filtering or sampling before delivery makes the resulting counts partial for that scope.

## Troubleshooting

* **401 or 403**: confirm that the secret belongs to the Generic HTTP connector for this brand and is still active.
* **400**: validate the JSON shape, record count, method, path, hostname, User-Agent, and timestamp.
* **413**: reduce the batch size or encoded payload size.
* **429**: pause until the `Retry-After` interval has elapsed, then retry the same idempotent batch.
* **Acknowledged but not connected**: confirm that the hostname matches the brand and that the test uses a currently recognized AI crawler User-Agent and a current timestamp.
* **Counts are lower than source logs**: check upstream filters, sampling, excluded paths, excluded user agents, late delivery, and rejected hostnames.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Netlify Log Drains
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/netlify

Connect Netlify traffic logs to Crawler Analytics through a General HTTP log drain.

Use a Netlify General HTTP log drain to send site traffic records to Crawler Analytics.

## Before you start

You need:

* a Netlify Enterprise account with permission to configure the target site;
* a site serving the hostname configured for the Qwairy brand;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

## Create and protect the key

1. In Crawler Analytics settings, select **Netlify**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone used for daily snapshots.
4. Copy the secret when it appears. Qwairy shows only its prefix later.
5. Keep the secret in the Netlify authorization setting. Do not add it to the endpoint query string, source control, or browser code.

For rotation, create a replacement, update the Netlify authorization value, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Configure the log drain

1. In the target Netlify site, open **Logs & Metrics > Log Drains**.

2. Select **Enable a log drain** and choose **General HTTP endpoint**.

3. Select **Traffic logs**. Do not add Function, Edge Function, or Deploy logs for this connector.

4. Leave **Exclude personally identifiable information (PII)** unchecked. Crawler classification requires the `user_agent` field.

5. Set the full endpoint URL to:

   ```text theme={null}
   https://www.qwairy.co/api/v1/logs/netlify
   ```

6. Set the authorization header value to:

   ```text theme={null}
   Bearer YOUR_CRAWLER_KEY
   ```

7. Choose **JSON** or **NDJSON** as the Log Drain Format.

8. Select **Connect**.

Netlify's traffic payload can include `client_ip`. Qwairy ignores that field before aggregation and does not retain raw payloads, query parameters, or human requests.

See [Netlify Log Drains](https://docs.netlify.com/manage/monitoring/log-drains/) for the current provider workflow.

## Test delivery

Request a safe path on the monitored site with a recognized crawler User-Agent:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Check that Netlify reports a successful drain delivery. In Qwairy, the connector changes from pending only after an accepted traffic row contains a matching hostname, current timestamp, `GET` or `HEAD` method, path, and recognized crawler User-Agent.

## Limits, filtering, and cost

* Netlify's General HTTP drain sends the selected traffic stream and does not expose a crawler-only filter for this integration.
* Human and unknown User-Agent rows are discarded by Qwairy, but they still contribute to Netlify delivery volume and the Qwairy ingress ceilings.
* Review current Netlify log-drain and traffic-delivery pricing before enabling the integration on a high-volume site.
* If the PII exclusion removes `user_agent`, Qwairy cannot classify the request and discards it.
* The shared integration and billed-team daily ceilings are documented on the Crawler Analytics overview.

## Troubleshooting

* **The drain cannot connect**: verify the full HTTPS endpoint and the `Bearer ` prefix before the current key.
* **Qwairy stays pending**: confirm that **Traffic logs** are selected and that the PII exclusion is off, then generate a current request with a recognized crawler User-Agent.
* **Rows are acknowledged but not counted**: check that `log_type` is `traffic`, the URL hostname matches the brand, the method is `GET` or `HEAD`, and the event has a valid timestamp.
* **Counts are lower than source traffic**: human, traditional-search, unknown, excluded, invalid, or out-of-scope rows do not enter crawler aggregates.
* **Delivery volume is unexpectedly high**: Netlify forwards the full selected traffic stream. Reassess provider cost before leaving the connector enabled.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Vercel Drains
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/vercel

Connect Vercel production request logs to Crawler Analytics through a dedicated JSON drain.

Use a Vercel Drain to forward production Static and Runtime request logs to Crawler Analytics.

## Before you start

You need:

* a Vercel Pro or Enterprise team with permission to manage Drains;
* a production project serving the hostname configured for the Qwairy brand;
* access to **Measure > Crawler Analytics > Settings**;
* a secure place to retain the one-time connector secret.

## Create and protect the key

1. In Crawler Analytics settings, select **Vercel**.
2. Select **Create Key**.
3. Enter a name and the IANA time zone that should define daily snapshots.
4. Copy the secret when it appears. It cannot be displayed again.
5. Keep it in the Vercel Drain configuration or another restricted secret store. Do not include it in a URL, repository, or client-side variable.

To rotate the key, create a replacement, update the Drain header, confirm delivery, and then delete the previous key. An integration can have up to five active keys.

## Configure the drain

1. In the Vercel dashboard, open **Team Settings > Drains > Add Drain**.

2. Choose a custom log destination and set the data type to **Logs**.

3. Select **JSON** format.

4. Select the **Production** environment.

5. Include **Static** and **Runtime** sources.

6. Set the endpoint to:

   ```text theme={null}
   https://www.qwairy.co/api/v1/logs/vercel
   ```

7. Add this custom header, using the secret copied from Qwairy as its value:

   ```text theme={null}
   X-API-Key: YOUR_CRAWLER_KEY
   ```

   Existing Drains that use `x-qwairy-token` remain compatible. Prefer
   `X-API-Key` for new configurations.

8. Keep production traffic at 100% sampling, or add no sampling rule. A lower sampling rate produces partial counts.

9. Save the Drain.

See the [Vercel Log Drains reference](https://vercel.com/docs/drains/reference/logs) for the current provider controls and schema.

## Test delivery

Use Vercel's destination test to check the endpoint and header. That test may not contain an accepted crawler request, so it does not by itself move the Qwairy connector to connected.

Then request an allowed path on the monitored production hostname with a recognized crawler User-Agent. For example, replace the URL below with a safe path on your site:

```bash theme={null}
curl --head --user-agent "GPTBot/1.0" "https://www.example.com/docs/crawler-check"
```

Confirm that the Vercel Drain reports successful delivery. In Qwairy, the connector changes from pending after the rollup pipeline accepts an event for the configured hostname.

## Limits, sampling, and cost

* Vercel cannot restrict this Drain by User-Agent. It forwards matching Static and Runtime traffic, and Qwairy discards non-AI requests on receipt.
* Forwarded human traffic can still count toward Vercel delivery volume and provider charges. Review current Vercel pricing before enabling the Drain on a high-volume site.
* Any Vercel sampling rule below 100% makes Crawler Analytics totals partial.
* Qwairy applies shared event, request, and daily ingestion ceilings described on the Crawler Analytics overview.

## Troubleshooting

* **Destination test fails**: check the HTTPS endpoint, the `X-API-Key` or legacy `x-qwairy-token` header name, and the one-time secret.
* **Drain succeeds but Qwairy stays pending**: verify that Static and Runtime production sources are selected, then send a current `GET` or `HEAD` request with a recognized crawler User-Agent to the configured brand hostname.
* **Counts are lower than Vercel logs**: check sampling rules, environment selection, source selection, Qwairy exclusion rules, and delivery continuity warnings.
* **Counts differ from all request traffic**: only classified AI crawler requests enter Crawler Analytics; other rows are intentionally discarded.
* **Provider delivery errors continue after rotation**: confirm that the Drain uses the replacement key before deleting the old one.

## Related page

* [Crawler Analytics](/documentation/measure/crawler-analytics)


# WordPress
Source: https://docs.qwairy.co/documentation/measure/crawler-analytics/connectors/wordpress

Install Qwairy's generated PHP tracker in WordPress, protect its key, and verify eligible crawler requests.

Use the WordPress collector when PHP handles the monitored page requests and no managed log-stream connector is selected. The generated tracker reports eligible HTML page requests through the Generic HTTP ingestion endpoint.

<Warning>
  Full-page caches and CDNs can serve a response without running WordPress or PHP. Those requests cannot be observed by this recipe. Use an edge or managed log collector when the traffic you need to measure bypasses PHP.
</Warning>

## Before you start

You need:

* access to **Measure > Crawler Analytics > Settings** for the brand;
* PHP 7.4 or later with the cURL extension enabled;
* access to the active theme directory and `functions.php`;
* outbound HTTPS access from PHP to `https://www.qwairy.co`;
* a server-side secret facility or configuration excluded from source control.

Theme updates can replace custom files. Record the installation or use your normal child-theme deployment process. Only activate one Crawler Analytics delivery source for the brand.

## Create and protect the key

1. In Crawler Analytics settings, select **WordPress**.
2. Select **Create Key**.
3. Enter a descriptive name and the IANA time zone used for daily analytics.
4. Copy the plaintext secret when it appears. Qwairy shows only its prefix later.
5. Store it in server-side configuration. Do not commit it to the theme, expose it to JavaScript, place it in a URL, or write it to logs.

WordPress uses the Generic HTTP provider contract. Its endpoint is `https://www.qwairy.co/api/v1/logs/ingest`.

## Add the generated tracker

Create `qwairy-tracker.php` in the active theme directory with the current generated recipe:

```php theme={null}
<?php
/**
 * Qwairy Crawler Analytics - PHP Tracker
 *
 * WordPress: Add to functions.php:
 *   require_once get_template_directory() . '/qwairy-tracker.php';
 *   qwairy_init('YOUR_API_KEY');
 *
 * Generic PHP: Include at top of index.php:
 *   require_once 'qwairy-tracker.php';
 *   qwairy_init('YOUR_API_KEY');
 */

function qwairy_init($api_key, $options = []) {
    if (empty($api_key)) return;

    $defaults = ['endpoint' => 'https://www.qwairy.co/api/v1/logs/ingest', 'async' => true];
    $options = array_merge($defaults, $options);

    register_shutdown_function(function() use ($api_key, $options) {
        qwairy_send_log($api_key, $options);
    });
}

function qwairy_send_log($api_key, $options) {
    if ($_SERVER['REQUEST_METHOD'] !== 'GET') return;
    $user_agent = $_SERVER['HTTP_USER_AGENT'] ?? '';
    if (!preg_match('/(?:^|[^a-z0-9_-])(?:Claude-SearchBot|MistralAI-Index|OAI-SearchBot|PerplexityBot|ChatGPT-User|Google-GeminiNotebook|Google-NotebookLM|Google-Agent|MistralAI-User|Perplexity-User|Claude-User|Google-CloudVertexBot|ClaudeBot|GPTBot|GrokBot|meta-webindexer|Amzn-User|Meta-ExternalFetcher|AI2Bot|Ai2Bot-Dolma|Amazonbot|Bytespider|CCBot|Meta-ExternalAgent|DuckAssistBot|KimiBot|Kimi-SearchBot|YouBot|Kimi-User|Diffbot|Kangaroo Bot|omgili|omgilibot|PanguBot|Timpibot|Webzio-Extended)(?=$|[^a-z0-9_-])/i', $user_agent)) return;

    $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) ?: '/';
    if (preg_match('/\.(png|jpe?g|gif|svg|webp|ico|mp4|webm|css|js|json|xml|woff2?|ttf|eot|map)$/i', $path)) return;

    $ignore_paths = ['/wp-admin/', '/wp-json/', '/api/', '/admin/'];
    foreach ($ignore_paths as $ignore) {
        if (strpos($path, $ignore) === 0) return;
    }

    $content_type = '';
    foreach (headers_list() as $header) {
        if (stripos($header, 'content-type:') === 0) {
            $content_type = trim(substr($header, 13));
            break;
        }
    }
    if ($content_type && strpos($content_type, 'text/html') === false) return;

    $log = [
        'status_code' => http_response_code() ?: 200,
        'request_method' => $_SERVER['REQUEST_METHOD'],
        'request_path' => $path,
        'hostname' => $_SERVER['HTTP_HOST'] ?? null,
        'user_agent' => $user_agent,
        'timestamp' => gmdate('c'),
    ];

    if (function_exists('curl_init')) {
        $ch = curl_init($options['endpoint']);
        curl_setopt_array($ch, [
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($log),
            CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Key: ' . $api_key],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => 5,
        ]);
        curl_exec($ch);
        curl_close($ch);
    }
}
```

Add the setup snippet to `functions.php`:

```php theme={null}
<?php
require_once get_template_directory() . '/qwairy-tracker.php';
qwairy_init('YOUR_API_KEY');
```

If `functions.php` already starts with `<?php`, add only the two statements and do not insert a second opening tag.

`YOUR_API_KEY` is a placeholder. Replace it only during deployment with the server-side value. If your host exposes secrets to PHP as environment variables, keep the value out of theme source:

```php theme={null}
<?php
require_once get_template_directory() . '/qwairy-tracker.php';

$qwairy_api_key = getenv('QWAIRY_API_KEY');
if (is_string($qwairy_api_key) && $qwairy_api_key !== '') {
    qwairy_init($qwairy_api_key);
}
```

Do not initialize the tracker twice. The generated function names are global, so confirm that another plugin or theme file does not define `qwairy_init` or `qwairy_send_log`.

## Verify delivery

Use an uncached HTML page and replace the example hostname. The tracker accepts `GET`, not `HEAD`. This synthetic request creates a crawler observation in the current analytic day:

```bash theme={null}
curl --user-agent "Mozilla/5.0 (compatible; GPTBot/1.1)" \
  --output /dev/null \
  --write-out "%{http_code}\n" \
  "https://www.example.com/docs/qwairy-collector-check"
```

1. Confirm the request returns the expected page status.
2. Confirm PHP handled the request rather than a CDN or full-page cache.
3. In Qwairy, wait for the connector to move from pending to connected after the accepted event reaches a daily rollup.
4. Open the current analytic day and look for `/docs/qwairy-collector-check`.

If the page loads but the connector stays pending, verify the cURL extension, outbound HTTPS, key, hostname, User-Agent, current timestamp, content type, and ignored-path rules.

## Limits and behavior

* The generated tracker reports only `GET` requests with a matching User-Agent.
* Static file extensions and paths beginning with `/wp-admin/`, `/wp-json/`, `/api/`, or `/admin/` are ignored.
* A response with an explicit content type is reported only when it contains `text/html`.
* Delivery is a blocking cURL call during PHP shutdown with a five-second timeout. The generated tracker has no retry queue and does not inspect the Qwairy response.
* The integration route allows a burst of 120 ingestion requests per minute. Responses above that rate are not retried by the generated tracker.
* The endpoint applies hostname validation, Qwairy exclusions, maintained crawler classification, a 72-hour late-arrival window, and shared ingestion ceilings.
* The shared technical ceilings are 10,000,000 events per integration per day and 200,000,000 events per billed team per day.
* The collector observes requests. It does not prove indexing, model training, or citation use.

## Rotate or roll back

To rotate the key, create a replacement in Qwairy, update the server-side value, confirm a new accepted observation, and then delete the previous key.

To roll back the tracker:

1. Remove the `require_once` and `qwairy_init` call from `functions.php`.
2. Deploy and clear the relevant WordPress or host caches.
3. Confirm the site still serves normally and no new tracker observations arrive.
4. Remove `qwairy-tracker.php` and the server-side secret.
5. Revoke the corresponding Qwairy key.

Disabling delivery creates an analytics coverage gap. Check delivery-continuity warnings before comparing periods that cross the rollback.

## Related pages

* [Crawler Analytics](/documentation/measure/crawler-analytics)
* [Generic HTTP collector](/documentation/measure/crawler-analytics/connectors/generic-http)


# Google Search Console
Source: https://docs.qwairy.co/documentation/measure/google-search-console

Connect a Search Console property, review query and page data, and turn selected searches into monitoring prompts.

Open **Measure > Google Search Console** to connect a property and review Google Search performance alongside Qwairy data.

## Connect a property

1. Select **Connect Google Search Console**.
2. Authenticate with a Google account that can access the intended property.
3. Grant the requested read permission.
4. Select the property associated with the monitored brand.

Check the exact domain and property type before confirming. Data availability follows Search Console's own processing and retention rules.

## Review queries and pages

Use the query and page views to inspect the metrics returned by Search Console, including clicks, impressions, click-through rate, and position where available.

Filters and sorting help identify records relevant to the selected date range. Search Console metrics describe Google Search, not AI-provider answers.

## Track a search as a prompt

Use the available **Track** action to add a selected query to the workspace prompt set. Edit conversational or ambiguous wording before saving, then assign the relevant topic, funnel stage, and tags.

Creating a prompt does not alter the Search Console record and does not guarantee that an AI provider receives the same wording from users.

## Export and troubleshoot

Use the export control for the current view. If the page is empty, confirm the property, permissions, date range, and whether Search Console reports data for that period.

## Related pages

* [Prompts](/documentation/workspace/prompts)
* [Page Performance](/documentation/measure/page-performance)


# Adobe Analytics
Source: https://docs.qwairy.co/documentation/measure/integrations/adobe-analytics

Connect an Adobe Analytics report suite for AI-referral traffic and configurable purchase or metric conversions.

## Connect Adobe Analytics

1. Open **Measure > Referrer Analytics** and choose **Adobe Analytics**.
2. Enter the OAuth Server-to-Server Client ID and Client Secret.
3. Enter the scopes requested by the connection form.
4. Select the report suite associated with the monitored domain.
5. Confirm the connection.

Use credentials with only the access required for the selected report suite and follow your organization's rotation policy.

## Available data

The connection can populate Referrer Analytics from Adobe referral and traffic dimensions.

AI Revenue can use purchases or discovered Adobe metrics. Purchases support provider-native revenue where the connected data provides it. Other metrics can be counted as conversions and assigned a fixed value in Qwairy for an estimate. Confirm currency, allocation, and attribution settings before using any native value in a report.

## Validate and troubleshoot

Compare the same report suite, segment, date range, and time zone in Adobe Analytics. If the connection fails, check the server-to-server credential, scopes, organization access, and report-suite permission.

If a conversion is unavailable, verify that the metric exists and is visible to the integration. If purchases appear without measured revenue, confirm that the compatible revenue metric is populated for the same scope.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [Page Performance](/documentation/measure/page-performance)


# Amplitude
Source: https://docs.qwairy.co/documentation/measure/integrations/amplitude

Connect an Amplitude project for AI-referrer users or events when referring-domain data is available.

## Connect Amplitude

1. Open **Measure > Referrer Analytics** and choose **Amplitude**.
2. Enter the project API key and Secret Key.
3. Select the project region.
4. Confirm the connection.

Use a credential with the required read scope and follow your organization's storage and rotation policy.

## Available data

Amplitude can populate Referrer Analytics when the project captures usable `referring_domain` values. Depending on the event model, the resulting measures may represent users or events rather than the session semantics used by another provider.

Amplitude does not power AI Revenue in Qwairy.

## Validate and troubleshoot

Check that the selected project and region are correct and that recent events contain the expected `referring_domain` property. Compare an equivalent date range and event definition in Amplitude.

If the connection succeeds but the page is empty, inspect the source event schema before changing credentials.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [Referrer Analytics](/documentation/measure/referrer-analytics)


# Google Analytics 4
Source: https://docs.qwairy.co/documentation/measure/integrations/google-analytics

Connect a GA4 property for measured AI-referral traffic and configurable purchase or event conversions.

## Connect GA4

1. Open **Measure > Referrer Analytics**.
2. Choose **Google Analytics 4** and select **Connect**.
3. Sign in with a Google account that can read the intended property.
4. Grant the requested read access.
5. Select the GA4 property associated with the monitored domain.

Check the property name, account, reporting time zone, and currency before confirming.

## Available data

The connection can populate Referrer Analytics with GA4 sessions and engagement fields for traffic classified as AI referrals.

AI Revenue can use purchases or discovered GA4 events. Purchases support provider-native ecommerce revenue. Other events can be counted as conversions and assigned a fixed value in Qwairy for an estimate.

## Validate and troubleshoot

Compare the Qwairy period with a GA4 report using equivalent dates and referral dimensions. Differences can result from consent mode, attribution, thresholding, time zones, or referrer loss.

If no properties appear, confirm the signed-in Google account and property permissions. If a conversion is unavailable, verify that the event occurred in the discovery period. If purchases appear without measured revenue, verify the ecommerce event parameters in GA4.

Disconnecting stops future retrieval for this connection. Reconnecting may require selecting the property again.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [AI Revenue](/documentation/measure/ai-revenue)


# Matomo
Source: https://docs.qwairy.co/documentation/measure/integrations/matomo

Connect a Matomo site for AI-referral traffic and configurable purchase or goal conversions.

## Connect Matomo

1. Open **Measure > Referrer Analytics** and choose **Matomo**.
2. Enter the Matomo instance URL.
3. Enter an authentication token with read access to the intended site.
4. Select the site associated with the monitored domain.
5. Confirm the connection.

For a self-hosted instance, Qwairy must be able to reach the configured URL. Do not expose an internal-only endpoint solely to complete the connection without a security review.

## Available data

The connection can populate Referrer Analytics with Matomo visits and engagement fields for traffic classified as AI referrals.

AI Revenue can use purchases or discovered Matomo goals. Use a provider-native value when the selected source supports one, or assign a fixed value in Qwairy for an estimate.

## Validate and troubleshoot

Compare the same site, dates, time zone, and referral segment in Matomo. If verification fails, check the instance URL, TLS configuration, token permissions, and site access.

If a conversion is unavailable, verify the goal configuration and source data. If purchases appear without measured revenue, confirm ecommerce orders and currency in Matomo.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [AI Revenue](/documentation/measure/ai-revenue)


# Analytics Integrations
Source: https://docs.qwairy.co/documentation/measure/integrations/overview

Choose an analytics connection for AI-referral traffic, revenue attribution, and page-level reporting.

Connect one supported analytics source to populate **Referrer Analytics** and related Measure views.

## Supported providers

| Provider                                                                   | Status | Referrer Analytics | AI Revenue                        |
| -------------------------------------------------------------------------- | ------ | :----------------: | --------------------------------- |
| [Google Analytics 4](/documentation/measure/integrations/google-analytics) | Live   |         Yes        | Purchases and events              |
| [Piwik PRO](/documentation/measure/integrations/piwik-pro)                 | Live   |         Yes        | Purchases and events              |
| [Matomo](/documentation/measure/integrations/matomo)                       | Beta   |         Yes        | Purchases and goals               |
| [Piano Analytics](/documentation/measure/integrations/piano-analytics)     | Beta   |         Yes        | Purchases and Transactions metric |
| [Adobe Analytics](/documentation/measure/integrations/adobe-analytics)     | Beta   |         Yes        | Purchases and metrics             |
| [Amplitude](/documentation/measure/integrations/amplitude)                 | Beta   |         Yes        | No                                |

## What a connection powers

* **Referrer Analytics** uses the selected provider's referral and engagement data.
* **AI Revenue** uses configured purchases, events, goals, or metrics on paid plans. Provider-native revenue and fixed-value estimates remain separate.
* **Page Performance** can add GA4 AI-referral sessions to page-level signals.

Provider metric definitions remain provider-specific. Qwairy does not make sessions, users, bounce rate, or revenue semantics identical across analytics products.

## Before connecting

1. Identify the property, site, project, or report suite for the monitored domain.
2. Confirm the required read permissions with its owner.
3. Check that referrer fields are populated.
4. For AI Revenue, verify the purchases, events, goals, or metrics you intend to configure, plus any provider-native revenue value you intend to report.
5. Use a credential that follows your organization's rotation and access policy.

Connection and reconnection actions depend on your Qwairy team role.

## Validate the connection

Compare a matching date range and segment in the source analytics product. Differences can result from time zones, attribution rules, consent, thresholds, sampling, or Qwairy's AI-referrer classification.

## Related pages

* [Referrer Analytics](/documentation/measure/referrer-analytics)
* [AI Revenue](/documentation/measure/ai-revenue)
* [Page Performance](/documentation/measure/page-performance)


# Piano Analytics
Source: https://docs.qwairy.co/documentation/measure/integrations/piano-analytics

Connect the Piano Analytics Data API for AI-referral traffic and configurable purchase or metric conversions.

## Connect Piano Analytics

1. Open **Measure > Referrer Analytics** and choose **Piano Analytics**.
2. Enter a Data API key with access to the intended site.
3. Enter the numeric Site ID.
4. Confirm the connection and the selected reporting scope.

Treat the API key as a credential and rotate it according to your organization's policy.

## Available data

The connection can populate Referrer Analytics from Piano traffic-source properties.

AI Revenue offers purchases and the built-in `m_transactions` Transactions metric. Purchases support provider-native revenue where the connected data provides it. The Transactions metric can be counted as a conversion and assigned a fixed value in Qwairy for an estimate. Managers and Owners can enter another metric identifier manually.

## Validate and troubleshoot

Compare equivalent dates, site scope, traffic-source filters, and time zones in Piano Analytics. If verification fails, check the API key permissions and Site ID.

If Transactions is unavailable, verify that `m_transactions` is populated in the selected site. If purchases appear without measured revenue, verify that Sales Insights is enabled and contains revenue for the reporting period.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [AI Revenue](/documentation/measure/ai-revenue)


# Piwik PRO
Source: https://docs.qwairy.co/documentation/measure/integrations/piwik-pro

Connect a Piwik PRO site for AI-referral traffic and configurable purchase or event conversions.

## Connect Piwik PRO

1. Open **Measure > Referrer Analytics** and choose **Piwik PRO**.
2. Enter the account address requested by the form.
3. Enter a Client ID and Client Secret with the required read access.
4. Select the site associated with the monitored domain.
5. Confirm the connection.

Store and rotate the client credentials according to your organization's policy. Do not share them in support screenshots or public documentation.

## Available data

The connection can populate Referrer Analytics with the sessions and engagement fields returned by Piwik PRO for classified AI-referral traffic.

AI Revenue can use purchases or discovered Piwik PRO events. Purchases support provider-native ecommerce revenue. Other events can be counted as conversions and assigned a fixed value in Qwairy for an estimate.

## Validate and troubleshoot

Compare equivalent dates, time zones, and referrer segments in Piwik PRO. If the connection fails, check the account address, credential scope, site access, and whether the API is available to the account.

If a conversion is unavailable, verify that the event occurred in the discovery period. If purchases appear without measured revenue, verify ecommerce tracking and revenue fields in Piwik PRO before reconnecting.

## Related pages

* [Analytics Integrations](/documentation/measure/integrations/overview)
* [Referrer Analytics](/documentation/measure/referrer-analytics)


# Page Performance
Source: https://docs.qwairy.co/documentation/measure/page-performance

Compare page-level signals from AI answers, GA4 referrals, retained crawler rollups, Google Search Console, and Bing Webmaster Tools.

<Info>
  Page Performance is available on active paid plans. Each source contributes only when its own connection and entitlement requirements are met.
</Info>

Open **Measure > Page Performance** to compare several page-level data sources in one table. A tracked page is a normalized path present in at least one source, not a separate list of configured pages.

The page can combine:

* recorded source mentions in monitored AI answers;
* GA4 sessions classified from recognized AI referrers;
* observed crawler occurrences from retained daily rollups;
* Google Search Console and Bing Webmaster Tools clicks, impressions, and position.

The table exposes source connection states. Read a missing source as unavailable, not as an observed zero. The score has a documented exception below: disconnected non-crawler sources currently remain zero-valued in its percentile inputs.

## Summary and table

The summary can show tracked paths, GA4 AI-referral sessions, observed crawler occurrences, and combined Google plus Bing clicks. The table keeps the underlying units separate and shows source-specific trends where comparison data is available.

Use source-state indicators to distinguish connected, disconnected, empty, and unavailable data. Sort by the metric relevant to the current question rather than treating every column as the same type of evidence.

## About the score

The score compares each page with the site's other pages using site-wide percentiles:

* AI-answer source mentions: 40%;
* GA4 AI-referral sessions: 25%;
* crawler occurrences: 20%;
* Google plus Bing clicks: 15%.

If crawler detail is not measured, its component is `null` and the remaining 80% is normalized to 100%; the score is marked partial. Other disconnected sources currently remain zero-valued rather than having their weights removed. A folder filter does not recalculate the site-wide percentiles.

The score is a relative Qwairy summary for the current site dataset. It is not an absolute quality grade, a search-engine ranking, or a forecast of AI visibility.

## Scope and coverage

Crawler page detail is queried only for windows of 30 days or less. The dashboard reads at most 250 crawler page identities; it marks crawler detail as bounded when pagination, count precision, or occurrences without a retained 2xx page identity prevent an exact page-level match.

Missing delivery is not inferred as zero. When crawler detail is not measured, the crawler occurrence value is `null`. Paths pseudonymized by Crawler Analytics are excluded from matching with GA4, Search Console, and Bing.

## Reconcile URLs

Cross-source matching removes query strings and fragments and lowercases paths. It does not reliably merge trailing-slash variants, redirects, or canonical alternatives. Confirm those mappings before comparing totals.

## Page Performance in MCP

The dashboard and the MCP tool answer different questions:

* **Measure > Page Performance** combines page-level signals from the connected product surfaces listed above.
* MCP `get_page_performance` returns retained Crawler Analytics rollups only. It does not return answer citations, referral sessions, Search Console metrics, or raw HTTP events.

The MCP page-detail window covers at most 30 completed UTC days. `period: "all"` means 30 days, not lifetime history. Read the coverage caveats in the returned text before interpreting counts. The tool does not render a measured zero when no supported public occurrence exists.

Pseudonymized paths are labelled as such in the rendered result and do not receive a page title. The tool also separates current pages from up to 10 neglected page identities and reports lifecycle states such as `new`, `hot`, and `neglected`.

## Related pages

* [Source Explorer](/documentation/monitor/content-sources)
* [Referrer Analytics](/documentation/measure/referrer-analytics)
* [Crawler Analytics](/documentation/measure/crawler-analytics)
* [Google Search Console](/documentation/measure/google-search-console)
* [Bing Webmaster Tools](/documentation/measure/bing-webmaster)
* [MCP Measure tools](/mcp/tools/measure)


# Referrer Analytics
Source: https://docs.qwairy.co/documentation/measure/referrer-analytics

Analyze sessions that a connected analytics provider classifies as referrals from AI platforms.

Open **Measure > Referrer Analytics** to review human traffic associated with detected AI referrers.

## Connect a provider

Choose a supported provider from the connection flow:

* Google Analytics 4;
* Piwik PRO;
* Matomo;
* Piano Analytics;
* Adobe Analytics;
* Amplitude.

See [Analytics Integrations](/documentation/measure/integrations/overview) for provider-specific requirements.

## Metrics and views

Depending on the connected provider, the page can show sessions or users, duration, bounce or engagement behavior, pages per session, source distribution, trends, and landing pages.

Metric names and semantics come from the analytics provider. For example, session, user, bounce, and duration definitions are not necessarily identical across providers.

## Attribution limits

AI referrer classification relies on the referral information available in the analytics source. Traffic can be missed or grouped differently when:

* a provider removes or changes the referrer;
* a user copies a URL or moves across devices;
* consent, blockers, or browser controls prevent measurement;
* redirects or campaign parameters alter attribution;
* the analytics provider applies thresholds or sampling.

Use the results to describe measured AI-referral traffic, not total influence from AI platforms.

## Troubleshoot an empty view

Confirm the connection, selected property or site, date range, permissions, and whether matching referrer values exist in the source system.

## Related pages

* [AI Revenue](/documentation/measure/ai-revenue)
* [Page Performance](/documentation/measure/page-performance)


# Response Analysis
Source: https://docs.qwairy.co/documentation/monitor/analyzing-answers

Search and filter individual AI answers, then inspect the mentions, sources, and insight metadata attached to them.

Open **Monitor > Response Analysis** to inspect the answers behind dashboard metrics.

## Filter answers

The page supports filters for:

* prompt text;
* answer text;
* funnel stage;
* competitor status;
* source status;
* detected insights such as web search, shopping, social, local, sponsored, or no insights.

Global brand, provider, list, and date controls may also affect the result set.

## Read a row

Each row represents a captured answer. Open its details to review the prompt, provider, generated text, detected brands, citations or links, and available insight metadata.

Use the raw answer to verify a dashboard conclusion. Detection is structured analysis of provider output, so review the surrounding text when classification or context matters.

## Common checks

### A metric has an unexpected denominator

Check whether the answer contains at least one SELF or DIRECT brand or source. Mention Rate and Citation Rate exclude answers without the corresponding SELF or DIRECT denominator.

### A prompt is missing

Clear filters, widen the date range, and confirm in **Workspace > Prompts** that the prompt was active for the selected run.

### An insight page is empty

Filter for the corresponding insight on this page. If no matching metadata is present, the dedicated insight page may have no records for the current scope.

## Related pages

* [Overview](/documentation/cockpit/performance-dashboard)
* [Competitor Mentions](/documentation/monitor/competitor-mentions)
* [Source Explorer](/documentation/monitor/content-sources)


# Competitor Mentions
Source: https://docs.qwairy.co/documentation/monitor/competitor-mentions

Review detected brands, correct their relationship to your brand, and inspect competitor presence in monitored answers.

Open **Monitor > Competitor Mentions** to review brands detected in monitored answers.

## Relationship tabs

The page organizes records into the tabs that apply to the workspace:

* **Competitors**: the monitored brand and brands classified as SELF or DIRECT.
* **Related Brands**: brands classified as INDIRECT.
* **To Review**: detections awaiting a relationship decision.
* **Favorites**: favorited competitors, when present.
* **Ignored**: brands excluded from competitive analysis.
* **Processing**: records still being analyzed, when present.

## Why classification matters

The dashboard's Mention Rate, Citation Rate, and Share of Voice calculations use SELF and DIRECT relationships. Changing a relationship can therefore change a historical view without changing the underlying answer text.

Use DIRECT for a brand that should be included in the competitive denominator. Use INDIRECT for a related brand that you want to keep visible without treating it as a direct competitor. Ignore a detection when it should not participate in analysis.

## Review competitors

You can add a competitor manually, edit a detected relationship, and favorite records used frequently in comparison views.

The page also supports filters for detected shopping, local, and sponsored signals. Open a competitor to inspect its appearances in the current scope.

<Note>
  A mention shows that a brand appeared in a captured answer. It does not establish recommendation, preference, market share, or a commercial relationship without further context.
</Note>

## Related pages

* [Compare](/documentation/cockpit/compare)
* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Core Concepts](/documentation/get-started/core-concepts)


# Source Explorer
Source: https://docs.qwairy.co/documentation/monitor/content-sources

Analyze cited domains and pages, ownership, usage type, and on-page presence across monitored answers.

Open **Monitor > Source Explorer** to inspect sources associated with monitored answers.

## Tabs

* **Domains** groups source activity by domain.
* **Pages** lists individual source URLs.
* **On-Page Presence** compares detected page content with brand presence where analysis is available.

## Filters

Use the available filters to narrow by:

* domain or page search;
* source type;
* own, competitor, third-party, or available-to-buy status;
* top-level domain;
* usage as Citation, Linked, or Grounding;
* on-page presence or mention status.

The usage labels describe how Qwairy classified the source in the captured provider output. They are not interchangeable across every provider.

## Investigate a source

1. Start with the domain view to understand its overall presence.
2. Open the Pages tab to identify the URLs behind that total.
3. Compare the source with the answers in **Response Analysis**.
4. Use On-Page Presence when you need to check whether the analyzed page mentions the selected brand.

Source analysis may fetch a public page URL. Results can be incomplete when a page blocks access, changes after the answer was captured, or requires authentication.

## Related pages

* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Backlink Opportunities](/documentation/act/backlink-opportunities)
* [Site Diagnostics](/documentation/optimize/site-diagnostics)


# Local Businesses
Source: https://docs.qwairy.co/documentation/monitor/insights/local-intelligence

Review businesses, categories, locations, and opportunities detected in local AI answer metadata.

Open **Monitor > Insights > Local Businesses** to inspect local-business metadata detected in monitored answers.

## Summary cards

The page shows **Business Mentions**, **Unique Businesses**, **Top Category**, and **Opportunities** for the active scope.

## Tabs

* **Overview** summarizes local result activity.
* **Businesses** lists detected businesses and their available details.
* **Opportunities** groups detected gaps or comparison points for review.

Use the available filters and row details to connect a business to its prompt, provider, and answer.

## Data limitations

Names, categories, ratings, addresses, and other local details come from captured provider metadata. They can be missing, normalized differently, or become outdated. Verify operational details with the business or source before publishing them.

## Related pages

* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Competitor Mentions](/documentation/monitor/competitor-mentions)


# Query Fan-Out
Source: https://docs.qwairy.co/documentation/monitor/insights/query-fan-out

Review search queries detected within AI answers, their intents, brand mentions, and prompt opportunities.

Open **Monitor > Insights > Query Fan-Out** to review search queries detected as part of provider answer generation.

## Summary cards

The page shows:

* **Total Queries**;
* **Total Usages**;
* **Brand Mention Rate**;
* **Opportunities**.

Read each value within the active date, provider, and workspace filters.

## Tabs

* **Overview** lists detected queries and their usage information.
* **Intents** groups queries by detected intent.

Use search, prompt, and priority filters to narrow the table.

## Add a query to monitoring

When a detected query belongs in the monitoring scope, add it to the prompt set. Review its wording, then assign a topic, funnel stage, and tags before saving.

Adding a query creates a prompt for future monitoring. It does not change the answer in which the query was detected.

<Note>
  Query fan-out metadata depends on what the provider returns and what Qwairy can detect. Absence from this page does not prove that a provider performed no internal query expansion.
</Note>

## Related pages

* [Prompts](/documentation/workspace/prompts)
* [Response Analysis](/documentation/monitor/analyzing-answers)


# Shopping Results
Source: https://docs.qwairy.co/documentation/monitor/insights/shopping-intelligence

Review products, stores, ratings, and brand opportunities detected in shopping-related AI answer metadata.

Open **Monitor > Insights > Shopping Results** to inspect shopping metadata detected in monitored answers.

## Summary cards

The page shows **Total Products**, **Total Stores**, **Avg Rating**, and **Opportunities** for the current scope.

## Tabs

* **Overview** summarizes shopping results.
* **Stores** groups detected products by store.
* **Products** lists individual detected products.

Use priority, store, competitor, and relationship filters to narrow the records.

## Interpret a record

Shopping metadata reflects the provider output captured by Qwairy. Product names, prices, ratings, and availability may change after the answer was collected. Verify time-sensitive information at the referenced store before using it externally.

An opportunity indicates a detected comparison or gap in the monitored dataset. It does not predict that a product change will alter future AI answers.

## Related pages

* [Competitor Mentions](/documentation/monitor/competitor-mentions)
* [Response Analysis](/documentation/monitor/analyzing-answers)


# Social Signals
Source: https://docs.qwairy.co/documentation/monitor/insights/social-intelligence

Review social platforms and pages cited in monitored AI answers, including their contribution to the source mix.

Open **Monitor > Insights > Social Signals** to inspect social sources detected in monitored answers.

## Summary cards

* **Social Citations** counts citations classified as social.
* **Social Share of Voice** is the share of citations in scope that are social citations.
* **Top Platform** identifies the leading detected social platform for the current scope.
* **Active Platforms** counts social platforms represented in the result set.

## Explore platforms

The **Overview** tab summarizes the result set. Additional tabs can appear for platforms detected in the current scope.

Use the page to identify the cited platform, page or discussion, related prompt, and provider. Open the underlying answer before deciding how the source influenced the response.

<Note>
  A citation records source use in a monitored answer. It does not by itself measure reach, engagement, authority, or sentiment on the social platform.
</Note>

## Related pages

* [Source Explorer](/documentation/monitor/content-sources)
* [Response Analysis](/documentation/monitor/analyzing-answers)


# Sponsored Content
Source: https://docs.qwairy.co/documentation/monitor/insights/sponsored-content

Review ads, advertisers, products, and prompts detected in sponsored AI answer metadata.

Open **Monitor > Insights > Sponsored Content** to inspect advertising metadata detected in monitored provider output.

## Summary cards

The page shows **Total Ads**, **Advertisers**, **Prompts with Ads**, and **Products** for the current scope.

## Tabs

* **Overview** summarizes detected sponsored records.
* **Advertisers** groups records by advertiser.
* **Products** lists products associated with detected ads.
* **Prompts** shows which monitored prompts returned sponsored content.

Open a record to connect the ad, advertiser, product, prompt, and provider where those fields are available.

<Note>
  Sponsored metadata depends on provider, market, account context, and collection time. An empty result means no supported sponsored record was detected in the selected dataset, not that advertising was absent for every user.
</Note>

## Related pages

* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Shopping Results](/documentation/monitor/insights/shopping-intelligence)


# Prompt Tracking
Source: https://docs.qwairy.co/documentation/monitor/tracking-queries

Review monitored prompts, their latest results, and detected signals without changing workspace configuration.

Open **Monitor > Prompt Tracking** to review how the current prompt set is represented in monitoring data.

## Tracking tab

The **Tracking** tab summarizes prompts and their latest available monitoring information. Use the page filters to narrow the current brand, date range, provider, topic, tag, or funnel scope where those controls are available.

Select a prompt to move from the summary to its related answers or details.

## Signals tab

The **Signals** tab groups detected changes or notable observations associated with monitored prompts. A signal reflects the data and comparison window shown in the interface. Check the underlying answers before treating it as a durable change.

You can use the available share and export controls for the current signal view.

## Manage the prompt set

Prompt Tracking is an analysis page. To add, edit, pause, schedule, tag, or boost a prompt, use [Workspace > Prompts](/documentation/workspace/prompts).

Each prompt can:

* inherit the workspace monitoring frequency;
* override it with Daily, Weekly, Monthly, or No monitoring;
* be paused and resumed;
* request 2 to 20 answers per model and run with a boost.

These settings affect future runs and credit estimates. They do not rewrite previously collected answers.

## Related pages

* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Monitoring](/documentation/workspace/monitoring)
* [Prompts](/documentation/workspace/prompts)


# Site Diagnostics
Source: https://docs.qwairy.co/documentation/optimize/site-diagnostics

Crawl selected public pages, review technical and content checks, and track audit results over time.

Open **Optimize > Site Diagnostics** to analyze public pages associated with the monitored brand.

Unlike the answer-monitoring pipeline, Site Diagnostics fetches pages. Only submit URLs that Qwairy is permitted to access.

## Add pages

Use the available sitemap synchronization or URL controls to create the page set. Review the discovered URLs and remove paths that should not be audited.

Pages behind authentication, bot protection, or network restrictions may not be accessible. A failed fetch should be investigated separately from a failed page check.

## Run an audit

An audit can examine technical access, metadata, content structure, and other signals shown in the interface. Open a page to see its current checks, affected elements, and suggested remediation.

Each completed page audit or re-audit costs **5 credits**. A multi-page run is billed per completed page. See [Providers & Credits](/documentation/get-started/credits) for the operation table and calculation examples.

Scores summarize the checks implemented by this feature. They are not search rankings and do not guarantee inclusion in an AI answer.

## Work through findings

1. Separate fetch errors from page findings.
2. Confirm the current page content in a browser.
3. Group repeated findings by template or component.
4. Prioritize according to business scope and implementation risk.
5. Re-run the relevant pages after deployment.

Use audit history to compare results only when the page set and check configuration are comparable.

## Related pages

* [Site Readiness](/documentation/optimize/site-readiness)
* [Page Performance](/documentation/measure/page-performance)
* [Source Explorer](/documentation/monitor/content-sources)


# Site Readiness
Source: https://docs.qwairy.co/documentation/optimize/site-readiness

Check robots.txt policy for configured crawler and robots-policy identities, then review llms.txt guidance.

Open **Optimize > Site Readiness** to review access signals for the monitored domain.

## Crawler and robots-policy access

The access table checks configured crawler and robots-policy identities against the site's current robots.txt rules. Use it to identify whether each identity appears allowed, blocked, mixed by path, or could not be evaluated.

Some entries are observable crawler User-Agents, such as GPTBot. Others are policy tokens, such as `Google-Extended`, that control permitted uses of content fetched by another crawler. A policy-token result cannot produce a Crawler Analytics occurrence or last-seen timestamp.

The result is a robots-policy observation. It does not show that a provider has crawled, indexed, cited, or will use the site. Only the supported observable User-Agent subset can appear in Crawler Analytics.

## robots.txt

The robots.txt section reads the public file and summarizes relevant directives. Review the raw file before changing it, especially when rules differ by user agent or path.

If Qwairy cannot retrieve the file, check the URL, status code, redirects, firewall, and authentication requirements.

## llms.txt

The llms.txt section helps you inspect or prepare a text file that describes selected site resources. Support and interpretation vary across AI systems. Publishing the file does not guarantee discovery or citation.

If Qwairy generates suggested content, review every URL and description before placing it on the public site.

## Recommended review sequence

1. Confirm the monitored domain and protocol.
2. Inspect the current robots.txt response.
3. Review user-agent-specific rules.
4. Check the proposed llms.txt content, if used.
5. Coordinate deployment with the site owner.
6. Re-run the check after the public files change.

## Related pages

* [Site Diagnostics](/documentation/optimize/site-diagnostics)
* [Crawler Analytics](/documentation/measure/crawler-analytics)


# Billing
Source: https://docs.qwairy.co/documentation/team/billing

Review the current plan, credit allocation, payment status, subscription controls, purchases, and invoices.

Open **Team Management > Billing** to manage billing for the root team.

Only the team Owner can access this page. Sub-teams inherit their parent organization's plan and do not have a separate Billing page.

## Current plan

The plan card shows the subscription, billing period, renewal or scheduled change, and payment status available for the account.

Use **Compare plans** to review plan options. When the subscription is linked to a billing customer, **Manage billing** opens the external billing portal for payment and subscription controls.

## Credits

The credit card shows the current team balance and the plan allocation for the active billing period where available.

An active subscription with a billing customer can expose **Buy credits**. Credit consumption and transaction detail are documented on [Usage](/documentation/team/usage).

## Payment history and invoices

The payment history lists subscription payments and credit-pack purchases. Use the invoice actions on a row to view or download an available invoice.

If an invoice link has expired, use the row action again to request a current link.

## Troubleshooting

When an expected control is missing, check:

* that you are the Owner of the root team;
* the current subscription and payment status;
* whether the account is linked to a billing customer;
* whether the item is a plan payment or a one-time credit purchase.

## Related pages

* [Usage](/documentation/team/usage)
* [Providers & Credits](/documentation/get-started/credits)


# Members
Source: https://docs.qwairy.co/documentation/team/manage-members

Invite team members, assign roles, manage Viewer brand access, and review pending invitations.

Open **Team Management > Members** to review the team roster and invitations.

## Roles

| Role        | Verified product permissions                                                                                                                         |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**   | Can modify workspaces, consume credits, manage the team, access root-team billing, manage SSO, and transfer ownership.                               |
| **Manager** | Can modify workspaces, consume credits, create brands, invite and manage members, and manage Viewers. Cannot access root-team billing or manage SSO. |
| **Member**  | Read-only access to every brand in the team. Cannot modify workspace data or consume credits.                                                        |
| **Viewer**  | Read-only access only to explicitly assigned brands.                                                                                                 |

The product can grant additional access to administrator accounts outside the team-role hierarchy.

## Invite a member

Owner and Manager roles can:

1. select **Add Member**;
2. enter the email address;
3. choose Manager, Member, or Viewer;
4. assign brand access for a Viewer;
5. send the invitation.

Managers and Members receive team-wide brand access according to their role. Viewers require explicit brand assignments.

## Manage an existing member

Use the row menu to change an editable member's role or Viewer brand access. Role changes take effect across the team and can change both navigation and API permissions.

The Owner has protected status. Follow the ownership-transfer workflow rather than trying to remove the Owner directly.

## Pending invitations

Pending invitations can be resent or revoked by an Owner or Manager. Confirm that an invitation was sent to the intended address before resending.

## Related pages

* [Viewers](/documentation/workspace/viewers)
* [Virtual Teams](/documentation/team/virtual-teams)
* [Team Settings](/documentation/team/settings)


# Settings
Source: https://docs.qwairy.co/documentation/team/settings

Review the team identifier, change the display name, and see feature overrides and beta access on the account.

Open **Team Management > Settings** for the current team's general information.

## Team ID

The Team ID is the immutable identifier shown by the page. Use it when an integration or support workflow explicitly asks for the team scope.

Do not confuse the Team ID with a Brand ID, API token, or billing-customer identifier.

## Team name

The team name appears in the team switcher and team-level views. Owners and Managers can edit it; Members can read team settings but the update API requires Manager access or higher.

Choose a name that identifies the organization or isolated sub-team without including confidential customer data unnecessarily.

## Add-ons and beta access

When the account has feature overrides or beta grants, the page lists them under **Add-ons & beta access**. An override can have an expiration date; a beta feature can change or be removed before public release.

This list describes account access. It does not replace the plan and billing information shown on the root team's [Billing](/documentation/team/billing) page.

## Related pages

* [Members](/documentation/team/manage-members)
* [Usage](/documentation/team/usage)


# SSO
Source: https://docs.qwairy.co/documentation/team/sso

Configure an OIDC identity provider, verify email domains, enable sign-in, and optionally enforce SSO.

<Info>
  SSO is available on the Enterprise plan or through an explicit feature override. Only the team Owner can manage it.
</Info>

Open **Team Management > SSO** to configure an OpenID Connect provider using the Authorization Code flow with PKCE.

## Prepare the identity provider

Create a web OIDC application with the callback displayed on the Qwairy SSO page. The default callback path is:

```text theme={null}
/api/auth/sso/callback
```

The origin must match the domain used for sign-in. A white-label custom domain therefore requires its own callback origin.

Collect the issuer URL, Client ID, and Client Secret. The issuer should support OIDC discovery and JWKS retrieval.

## Create the connection

1. Enter a provider display name.
2. Enter the issuer URL, Client ID, and Client Secret.
3. Choose the default role for just-in-time provisioning.
4. Save the connection.
5. Use **Test OIDC Connection** to check discovery and signing-key access.

The available default roles are Member and Viewer. A newly provisioned Viewer still needs brand access before viewing a workspace.

## Verify a domain

Add the organization's email domain, then publish the TXT record shown by the interface. Select **Verify** after DNS can resolve the record.

Each domain can belong to one SSO connection. Removing the last verified domain disables SSO and enforcement for that connection.

## Enable and enforce

You need at least one verified domain before enabling SSO. Matching users can then authenticate through the configured provider and be provisioned with the default role.

**Enforce SSO** requires SSO to be enabled. Test sign-in with the intended domain before enforcement. Users whose matching identity cannot authenticate may otherwise lose access.

## Troubleshooting

* **Discovery failed**: check the issuer root URL and network access to its discovery document and JWKS.
* **Redirect mismatch**: copy the exact origin and `/api/auth/sso/callback` path shown in Qwairy.
* **Domain not verified**: confirm the TXT host and value in public DNS.
* **User not provisioned**: confirm a verified email claim, matching domain, and default role.

Deleting the SSO connection also removes its associated domain records from Qwairy. Coordinate the change before deletion.


# Usage
Source: https://docs.qwairy.co/documentation/team/usage

Review the team credit balance, consumption, additions, projection, breakdowns, and transaction history.

Open **Team Management > Usage** to analyze credit movements. The page is available to Member roles and higher; Viewer access is excluded by the usage API.

## Choose the scope

The default is the current billing period. If the team has no active billing period, the default becomes the last 30 days.

Available periods include Last 7 days, Last 30 days, Last 90 days, All time, and a custom date range. When the team has several brands, you can filter to one brand.

Brand filtering scopes consumption rows. Team-level grants and adjustments remain team movements rather than brand consumption.

## Summary cards

* **Balance** shows credits currently available and the period allocation where present.
* **Credits used** sums feature-consumption transactions in the selected period.
* **Credits added** covers plan allocations, purchases, and grants, with adjustments identified separately.
* **Projection** estimates a runout date from the current burn rate when enough information is available.

The projection is an extrapolation. Changes to monitoring, models, boosts, imports, or purchases can make it inaccurate.

## Charts and breakdowns

Switch the consumption chart between Daily, Weekly, and Monthly views where the selected period supports them. Breakdowns show consumption by brand and by feature. A brand filter removes the redundant team-wide brand split.

## Transactions

The **Activity** tab lists feature consumption with date, brand, feature, model, credits, and description. Filter by feature and model where options are available.

The **Credits added** tab lists grants and other positive additions for the selected period.

For model and operation costs, see [Providers & Credits](/documentation/get-started/credits).


# Virtual Teams
Source: https://docs.qwairy.co/documentation/team/virtual-teams

Create isolated sub-teams, allocate credits and workspace quota, and move eligible workspaces within one organization.

<Info>
  Virtual Teams is available on Business, Enterprise, and Agency Business
  plans, or through an explicit feature override. It is managed by Owners and
  Managers of the parent organization.
</Info>

Open **Team Management > Virtual Teams** from the parent organization. Sub-teams inherit the parent plan and do not have their own subscription or Billing page.

## Organization model

* The parent holds the unallocated credit pool and workspace quota.
* Each sub-team has its own members, brands, credit balance, and allocated workspace quota.
* Virtual Teams are one level deep. A sub-team cannot create another sub-team.

## Create a sub-team

Select **Create**, then enter a name, optional initial credits, and a workspace quota. You can also move eligible existing workspaces during creation.

The sub-team quota must be at least 1 and cannot use more of the organization's available allocation than the preview allows.

## Allocate or reclaim credits

Use **Allocate** to move credits from the parent pool to a sub-team. Use **Reclaim** to return available sub-team credits to the parent.

Credit transfers are ledger adjustments, not feature consumption, so they do not enter the burn-rate calculation as usage.

## Change workspace quota

Use **Quota** to change a sub-team allocation. It cannot be reduced below the sub-team's current number of live workspaces, and the organization envelope remains authoritative.

## Move a workspace

The parent can move an eligible LIVE standard workspace between the parent and its active sub-teams, or between sub-teams.

The move carries the workspace's reserved slot, so it is net-zero for the organization's total quota. Prompt, answer, source, competitor, analytics, and share-link records move with the workspace.

Access changes to the destination team. Monitoring then uses the destination team's credits. If that balance is empty, future monitoring cannot consume credits until an allocation is added.

While the background re-stamp is settling, the workspace shows a migration state and product reads or a second transfer can be temporarily blocked. Draft and audit workspaces are not eligible.

## Membership

Switch to a sub-team and open **Team Management > Members** to manage its roster. A member of one sub-team does not automatically see sibling sub-teams.

Use a sub-team when collaborators need active management inside an isolated boundary. Use a [Viewer](/documentation/workspace/viewers) for read-only access to selected brands in the same team.

## Related pages

* [Members](/documentation/team/manage-members)
* [Usage](/documentation/team/usage)
* [Billing](/documentation/team/billing)


# Activity
Source: https://docs.qwairy.co/documentation/workspace/activity

Follow scheduled, manual, onboarding, and new-prompt generation runs with their scope, progress, and status.

Open **Workspace > Activity** to review generation runs for the selected brand.

This page shows execution state. It does not replace the individual answers in Response Analysis or the credit ledger in Team Usage.

## Activity types

Runs are labeled by purpose:

* **Scheduled monitoring**;
* **New prompts**;
* **Manual analysis**;
* **Onboarding**.

A scheduled run can also display its Daily, Weekly, or Monthly frequency. Priority appears for urgent work where applicable.

## Scope and progress

Each row shows:

* the start time;
* requested response count;
* prompt and model counts;
* completed, processing, failed, and remaining work in the progress display;
* the current status.

Statuses include Queued, Processing, Completed, Completed with warnings, Failed, Cancelled, and No work.

**Completed with warnings** means the run finished with at least one non-successful item. Inspect the corresponding answers and provider results before treating the run as complete for reporting.

**No work** means planning found no eligible generation for that run. Check prompt state, frequency, model selection, and credit availability.

## Live updates and history

The page refreshes active runs and paginates older records. If live refresh fails, use **Retry** before assuming the run stopped.

## Related pages

* [Monitoring](/documentation/workspace/monitoring)
* [Prompts](/documentation/workspace/prompts)
* [Response Analysis](/documentation/monitor/analyzing-answers)
* [Usage](/documentation/team/usage)


# Configuration
Source: https://docs.qwairy.co/documentation/workspace/brand-settings

Add a brand and configure competitor detection and domain scope for the current workspace.

Open **Workspace > Configuration** to review workspace-level settings for the selected brand.

## Add a brand

1. Open the brand selector in the dashboard header.
2. Select **Add new brand**.
3. Complete the onboarding flow.
4. Review the generated brand profile, topics, prompts, and competitors.

You can switch brands from the same selector. See [Quickstart](/documentation/get-started/quickstart) for the onboarding sequence.

## Auto-detect competitors

When enabled, Qwairy can add brand detections from monitored answers to the competitor review workflow. Classify new records in **Monitor > Competitor Mentions** as DIRECT, INDIRECT, or IGNORED.

Disabling automatic detection stops new automatic additions. It does not remove previously detected competitors.

## Limit pages to this subdomain

By default, page and source views can include the registrable domain and its relevant subdomains. Enable **Limit pages to this subdomain** when the workspace should use the exact host and its sub-subdomains instead.

For a workspace on `blog.example.com`:

| Included                                 | Excluded                                             |
| ---------------------------------------- | ---------------------------------------------------- |
| `blog.example.com`, `*.blog.example.com` | `example.com`, `www.example.com`, `shop.example.com` |

This setting changes page and source scope. It does not change brand-level mention, sentiment, or Share of Voice data.

<Note>
  Domain scope can change which records appear in Source Explorer and page-level Measure views. Record the setting when comparing exports across workspaces.
</Note>


# Exports
Source: https://docs.qwairy.co/documentation/workspace/exports

Generate, monitor, download, and remove point-in-time data exports for the current workspace.

Open **Workspace > Exports** to manage generated files.

## Export states

| Status         | Meaning                                                                 |
| -------------- | ----------------------------------------------------------------------- |
| **Pending**    | The request is queued.                                                  |
| **Processing** | The file is being generated.                                            |
| **Completed**  | The file is available for download.                                     |
| **Failed**     | Generation did not complete. Review the scope and retry if appropriate. |

The table can also show the export type, reporting period, row count, creator, and creation time.

## Download an export

Download a completed export from its row action. The file is a snapshot of the data and filters used at generation time. Later monitoring runs, taxonomy changes, or verification decisions are not added to that file.

## Filter and remove exports

Use the status or type filters to locate a request. Deleting an export removes the generated record or file available through this page; it does not delete the underlying Qwairy data.

Before sharing a file, review its contents for confidential data and use an approved destination.

## Related pages

* [Shared Links](/documentation/workspace/shared-links)
* [Lists](/documentation/workspace/lists)


# Lists
Source: https://docs.qwairy.co/documentation/workspace/lists

Save a named filter scope and reuse it across compatible dashboard and analysis views.

Open **Workspace > Lists** to manage saved analysis scopes.

## Create a list

Select **Add List**, enter a name, and configure the fields available in the form. A list can include provider, topic, tag, and period selections.

Use a name that describes both the audience and scope, such as `Quarterly report: France, Core models`.

## Load a list

Choose a saved list from a compatible view to apply its stored filters. Check the active filter chips after loading because a list may not control every page-specific filter.

## Edit or delete a list

Editing a list changes the saved definition used the next time it is loaded. It does not rewrite an export generated from an earlier version.

Deleting a list removes the preset, not the underlying prompts or answers. When a topic or tag is deleted, Qwairy removes that taxonomy reference from saved lists.

## Reporting practice

Record the list name, date range, and relevant configuration with external reports. A mutable saved list is not by itself a durable record of an earlier filter state.

## Related pages

* [Exports](/documentation/workspace/exports)
* [Shared Links](/documentation/workspace/shared-links)


# Monitoring
Source: https://docs.qwairy.co/documentation/workspace/monitoring

Set the workspace monitoring schedule, choose models, and review the credit estimate for prompt-level settings and boosts.

Open **Workspace > Monitoring** to configure the default schedule and selected AI models for the current brand.

<Info>
  Monitoring configuration is unavailable on the Free plan. Existing data remains separate from the ability to schedule new runs.
</Info>

## Set the workspace default

Choose one default frequency:

* **No monitoring**;
* **Daily**;
* **Weekly**, with a weekday;
* **Monthly**, with a day of the month.

This value is the default for prompts set to **Auto**. Save the page after changing the schedule.

## Select models

Choose the Core and Premium models to use for scheduled monitoring:

* **Core models** capture a supported public AI experience and cost 1 credit per prompt-model answer.
* **Premium models** use official provider APIs and cost 2 to 20 credits per prompt-model answer.

Model cost is displayed in the interface and documented in [Providers & Credits](/documentation/get-started/credits).

Changing the model set affects future runs. It does not regenerate historical answers.

## Prompt-level overrides

Open **Workspace > Prompts** to configure individual prompts. Each prompt can:

* inherit the default with **Auto**;
* use Daily, Weekly, Monthly, or No monitoring;
* be paused or resumed;
* use a boost.

Bulk actions can apply frequency, pause, resume, or boost changes to several prompts.

## Boosts

A boost requests **2 to 20 answers per model and run** for a prompt. The workspace also enforces the boosted-prompt limit shown in the interface.

Boosted prompts consume credits for every generated answer. Use the page estimate to review the combined effect of prompt frequencies, selected models, and boosts before saving.

## Estimate limitations

The displayed credit estimate reflects the current configuration. Actual use depends on which scheduled or manual generations run and which answers complete.

## Related pages

* [Prompts](/documentation/workspace/prompts)
* [Providers & Credits](/documentation/get-started/credits)


# Notifications
Source: https://docs.qwairy.co/documentation/workspace/notifications

Enable or disable the weekly email report for the current brand and understand related transactional emails.

Open **Workspace > Notifications** to configure the weekly report for the selected brand.

## Weekly report

Use the **Weekly report** toggle to enable or disable the email summary. The setting applies to the current brand and the cadence is weekly; this page does not provide a custom frequency selector.

Recipients depend on team access to the brand. Review membership and viewer access when an expected recipient is missing.

## Related emails

Other Qwairy emails are controlled by the workflow that creates them. For example, an export can send a completion email when that option is enabled, and team-level credit notifications relate to billing and usage settings.

Turning off the workspace weekly report does not disable required account, security, billing, or transactional messages.

## Troubleshooting

Confirm the current brand, the toggle state, the recipient's access, and the account email address. Delivery can also be affected by mail filtering outside Qwairy.

## Related pages

* [Exports](/documentation/workspace/exports)
* [Billing](/documentation/team/billing)
* [Viewers](/documentation/workspace/viewers)


# Personas
Source: https://docs.qwairy.co/documentation/workspace/personas

Create audience profiles that provide optional context to supported content-generation workflows.

Open **Workspace > Personas** to manage audience context for the current brand.

## Create a persona

Select **Add Persona** and describe the audience using the fields available in the form. Use a clear name and include only information needed for the content task.

Avoid personal data or assumptions about a real individual. A persona should represent a research-backed audience segment.

## Edit or delete a persona

Editing a persona changes its current context for future supported generation. It does not rewrite briefs that were already generated.

Deleting a persona removes it from future selection. Review active editorial work before removal.

## Use in Content Studio

Choose a persona when a Content Studio workflow exposes that option. The persona guides generated tone and focus, but the output still requires editorial and factual review.

## Related pages

* [Content Studio](/documentation/act/content-studio)
* [Content Opportunities](/documentation/act/content-opportunities)


# Prompts
Source: https://docs.qwairy.co/documentation/workspace/prompts

Add, organize, schedule, pause, boost, regenerate, and remove the prompts monitored for a brand.

Open **Workspace > Prompts** to manage the questions in the current brand's monitoring scope.

## Add prompts

Use **Add Prompt** for manual entry. Review the prompt text, topic, funnel stage, tags, and monitoring settings before saving.

Use **Generate Prompts** to create suggestions from brand and taxonomy context. Generated prompts should be reviewed for market, language, duplication, and intent.

Creating prompt suggestions, adding prompts manually, and importing prompt definitions are free. If automatic answers run after prompts are added, each prompt consumes the sum of the models configured and available for the workspace. A boost multiplies the number of answers billed for each model.

## Organize the table

Search and filter by the fields available on the page, including topic, tag, funnel, and prompt text. Select rows to apply bulk actions.

A prompt can have one topic, multiple tags, and one funnel stage. Editing those fields changes future grouping and can affect historical breakdowns that use the current taxonomy projection.

## Configure monitoring per prompt

Each prompt supports:

* **Auto**, which inherits the workspace default;
* Daily, Weekly, Monthly, or No monitoring;
* pause and resume;
* a boost of 2 to 20 answers per model and run.

Use the bulk controls to apply frequency, pause, resume, topic, tag, or boost changes where available. The workspace's boosted-prompt limit still applies.

## Regenerate

Use the generation action to run selected prompts on chosen models. Confirm the model costs and number of generated answers before starting.

## Delete prompts

Deleting a prompt hard-deletes the prompt and its dependent monitoring data. Use the confirmation dialog and export required evidence before deletion. This differs from deleting a topic, which keeps prompts and leaves them unassigned.

## Related pages

* [Monitoring](/documentation/workspace/monitoring)
* [Topics](/documentation/workspace/topics)
* [Tags](/documentation/workspace/tags)
* [Prompt Tracking](/documentation/monitor/tracking-queries)


# Shared Links
Source: https://docs.qwairy.co/documentation/workspace/shared-links

Create, review, expire, and revoke links that expose selected Qwairy views outside the signed-in workspace.

Open **Workspace > Shared Links** to manage shareable views.

## Share types

Available share types can include Overview, Perception, GEO Matrix, competitor comparison, and Prompt Signals.

Create a link from the share control on a supported page, then give it a recognizable name and expiration where available. The Shared Links table shows its type, creator, dates, status, and view activity.

## Manage access

Use row actions to copy or open an active link, edit its expiration, or revoke it. Revocation prevents further access through that link.

<Warning>
  A shared link can be opened without the recipient joining your team. Review the visible filters and data before sending it, choose an expiration, and revoke it when access is no longer needed.
</Warning>

The link reflects the share behavior defined by its type. Confirm whether the recipient sees a snapshot or an interactive view before relying on it for a fixed report.

## Related pages

* [Viewers](/documentation/workspace/viewers)
* [Exports](/documentation/workspace/exports)


# Tags
Source: https://docs.qwairy.co/documentation/workspace/tags

Create reusable labels, assign several tags to a prompt, and filter Qwairy views by custom groupings.

Open **Workspace > Tags** to manage reusable labels for prompts.

Tags support overlapping groupings such as campaigns, markets, audiences, or internal reporting sets. A prompt can have multiple tags.

## Create and edit a tag

Select **Add Tag**, enter a name, choose a color, and save. Keep names distinct enough to remain understandable in filters and exports.

Renaming or recoloring a tag updates its current presentation on assigned prompts.

## Assign tags

Assign tags from a prompt or with the bulk actions in **Workspace > Prompts**. Use tags in the dashboard and analysis filters that expose them.

## Delete a tag

Deleting a tag removes its assignments and taxonomy references. It does not delete the prompts or their answers.

If the tag defined an external reporting segment, record the mapping before deletion.

## Topics and tags

Use a topic for one primary thematic assignment. Use tags for several optional labels that can overlap.

## Related pages

* [Prompts](/documentation/workspace/prompts)
* [Topics](/documentation/workspace/topics)
* [Lists](/documentation/workspace/lists)


# Topics
Source: https://docs.qwairy.co/documentation/workspace/topics

Group prompts into thematic topics and use those groups in dashboard filters and breakdowns.

Open **Workspace > Topics** to manage the thematic groups used by the current brand.

Topics appear in views such as GEO Matrix, Compare, and Content Opportunities. A prompt can be assigned to one topic or remain unassigned.

## Add and rename topics

Select **Add Topic**, enter a distinct name, and save. A brand can have up to **5 topics**. Renaming a topic updates its label for assigned prompts and related views.

Use names that describe a stable subject rather than a temporary campaign. Tags are more suitable for flexible or overlapping labels.

## Delete a topic

Deleting a topic:

* keeps the prompts;
* sets their topic assignment to unassigned;
* removes the deleted topic from saved taxonomy references;
* cleans related topic projections used by analytical fact tables.

It does not delete the prompt answers. Reassign the affected prompts if you want them included in another topic breakdown.

<Warning>
  Topic deletion changes historical topic-level grouping because the topic reference is removed. Export or record the prior mapping if it is needed for reporting.
</Warning>

## Related pages

* [Prompts](/documentation/workspace/prompts)
* [Tags](/documentation/workspace/tags)
* [GEO Matrix](/documentation/cockpit/geo-matrix)


# Viewers
Source: https://docs.qwairy.co/documentation/workspace/viewers

Grant and remove read-only access to selected brands for team members with the Viewer role.

Open **Workspace > Viewers** to manage read-only brand access. Access to this administration page requires the role shown by the interface.

## Active viewers

The active list shows Viewer members who can access the current brand. Removing access does not remove the person from the team or from other brands.

## Pending invitations

The pending list shows Viewer invitations that have not been accepted. Revoke an invitation when the recipient or brand scope is no longer correct.

## Add a viewer

You can invite a new Viewer by email or grant the current brand to an existing Viewer. Confirm the recipient and scope before sending.

Viewers can read the product areas exposed to their brand-scoped role but
cannot change prompts, monitoring, or workspace settings. **Action Center**,
**Content Studio**, and the full-page **Agents** destination are hidden. A beta
page can also remain hidden unless the team has access to that beta.

## Choose the right sharing method

Use a Viewer for ongoing read-only access within the team. Use [Shared Links](/documentation/workspace/shared-links) for a specific shareable view. Use [Virtual Teams](/documentation/team/virtual-teams) when a separate team, workspace allocation, or operating boundary is required.


# Connect Looker Studio
Source: https://docs.qwairy.co/looker-studio/getting-started

Connect Qwairy to Google Looker Studio and build reports from governed monitoring data

The Qwairy Looker Studio connector exposes purpose-specific monitoring data sources in Google Looker Studio. Use them to build reports, combine Qwairy data with other sources, and control how metrics are presented.

<iframe title="YouTube video player" />

***

## Requirements

* **Qwairy Business plan** or higher
* Active monitored brands with GEO data

## Connect the data source

<Steps>
  <Step title="Generate an API token">
    Go to **Team Management** → **Looker Studio** and click **New Token**.
  </Step>

  <Step title="Open Looker Studio">
    Navigate to [Looker Studio](https://lookerstudio.google.com/) and create a new report.
  </Step>

  <Step title="Add the Qwairy connector">
    Click **Add data** → Search for "Qwairy" → Select the Qwairy connector.

    <Tip>
      You can also use this direct link to add the connector: [Add Qwairy Connector →](https://lookerstudio.google.com/datasources/create?connectorId=AKfycbxBOrs7f6m7D_-dRbHbloFW09nNpHH9mhdhKIAIDm0cBrm4tZ83fqC9RGbjYqIjJqr-)
    </Tip>
  </Step>

  <Step title="Configure the connection">
    * Enter your API token
    * Select your brand
    * Choose a data source
  </Step>

  <Step title="Build the report">
    Drag and drop dimensions and metrics to create visualizations.
  </Step>
</Steps>

<img alt="Qwairy token fields in the Looker Studio connector" />

***

## Available data sources

Choose the data source that matches the grain and metric contract required by your report:

| Data source                                                         | Use for                                                  |
| ------------------------------------------------------------------- | -------------------------------------------------------- |
| [Prompt Performance](/looker-studio/sources/prompt-performance)     | Comparing monitored prompts                              |
| [Performance Overview](/looker-studio/sources/performance-overview) | Executive dashboards, trend analysis                     |
| [Competitor Metrics](/looker-studio/sources/competitor-metrics)     | Competitive analysis, market share                       |
| [Source Domains](/looker-studio/sources/source-domains)             | Domain-level citation analysis                           |
| [Source URLs](/looker-studio/sources/source-urls)                   | Page-level citation tracking                             |
| [Source URLs by Topic](/looker-studio/sources/source-urls)          | Page-level citations grouped by topic                    |
| [Source URLs by Tag](/looker-studio/sources/source-urls)            | Page-level citations grouped by tag                      |
| [Tag Performance](/looker-studio/sources/tag-performance)           | Category and topic grouping                              |
| [Keyword Performance](/looker-studio/sources/keyword-performance)   | Topic-level analysis using the connector's current label |
| [Answer Details](/looker-studio/sources/answer-details)             | Qualitative response analysis                            |
| [Shopping Insights](/looker-studio/sources/shopping-insights)       | E-commerce product visibility                            |
| [Local Insights](/looker-studio/sources/local-insights)             | Local business presence                                  |
| [Search Insights](/looker-studio/sources/search-insights)           | AI search behavior patterns                              |
| [Social Insights](/looker-studio/sources/social-insights)           | Reddit, YouTube, social visibility                       |


# Answer Details
Source: https://docs.qwairy.co/looker-studio/sources/answer-details

Per-answer metadata (prompt, funnel, topic) for granular analysis in Looker Studio.

Per-answer metadata for granular, response-level analysis. Each row represents a single AI response, with its prompt, funnel stage, topic, and mention metrics. This source returns answer metadata only, not the response text itself.

<Tabs>
  <Tab title="Dimensions">
    | Field        | Type | Description                           |
    | ------------ | ---- | ------------------------------------- |
    | `date`       | Date | Response date (YYYY-MM-DD)            |
    | `provider`   | Text | AI provider name                      |
    | `model`      | Text | Specific model name                   |
    | `questionId` | Text | Question unique identifier            |
    | `prompt`     | Text | Prompt text (truncated to 200 chars)  |
    | `funnel`     | Text | Query intent stage (TOFU, MOFU, BOFU) |
    | `topic`      | Text | Associated keyword/topic              |
  </Tab>

  <Tab title="Metrics">
    | Field             | Type    | Description                  |
    | ----------------- | ------- | ---------------------------- |
    | `brandMentioned`  | Boolean | True if brand was mentioned  |
    | `brandMentions`   | Number  | Total brand mentions count   |
    | `brandPosition`   | Number  | First brand mention position |
    | `sourceCitations` | Number  | Total source citations count |
    | `sentiment`       | Percent | Sentiment score (0-100)      |
  </Tab>
</Tabs>

## Use this source for

* Granular, answer-level breakdowns by provider and model
* Slicing visibility by funnel stage and topic
* Debugging specific prompts
* Tracking per-answer brand mentions, position, and sentiment


# Competitor Metrics
Source: https://docs.qwairy.co/looker-studio/sources/competitor-metrics

Detailed competitor-level metrics for benchmarking analysis in Looker Studio.

Detailed competitor-level metrics for benchmarking analysis.

<Tabs>
  <Tab title="Dimensions">
    | Field          | Type | Description                              |
    | -------------- | ---- | ---------------------------------------- |
    | `date`         | Date | Analysis date (YYYY-MM-DD)               |
    | `provider`     | Text | Always `All Providers`                   |
    | `model`        | Text | Always `All Models`                      |
    | `competitorId` | Text | Stable competitor domain identifier      |
    | `competitor`   | Text | Competitor brand name                    |
    | `relationship` | Text | SELF or DIRECT                           |
    | `topic`        | Text | Topic filter applied to the source query |
    | `tag`          | Text | Tag filter applied to the source query   |
  </Tab>

  <Tab title="Metrics">
    | Field                     | Type    | Aggregation | Description                                                                           |
    | ------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------- |
    | `totalMentions`           | Number  | SUM         | Total mentions count                                                                  |
    | `answersWithMentions`     | Number  | SUM         | Responses with mentions                                                               |
    | `visibilityScore`         | Percent | AVG         | % of responses with this competitor                                                   |
    | `positionSum`             | Number  | SUM         | Sum of mention positions (component field)                                            |
    | `positionCount`           | Number  | SUM         | Count of positioned mentions (component field)                                        |
    | `sentimentSum`            | Number  | SUM         | Sum of mention sentiment scores (component field)                                     |
    | `sentimentCount`          | Number  | SUM         | Count of scored mentions (component field)                                            |
    | `avgPosition`             | Number  | Calculated  | `SUM(positionSum) / SUM(positionCount)`                                               |
    | `avgSentiment`            | Percent | AVG         | Average sentiment per competitor row                                                  |
    | `shareOfVoice`            | Percent | AVG         | % of total mentions                                                                   |
    | `totalTrackedCompetitors` | Number  | MAX         | Total competitors tracked on this brand (registered SELF + DIRECT, excluding ignored) |
  </Tab>
</Tabs>

<Note>
  `totalTrackedCompetitors` is a brand-level constant (registered count, ignores
  filters). Distinct `competitor` values only cover those mentioned in the
  selected period. Pair as
  `COUNT_DISTINCT(competitor) / MAX(totalTrackedCompetitors)` for a coverage
  ratio.
</Note>

<Note>
  Competitor rows are grouped by `competitorId`, not by display name. This
  prevents duplicate rows when names vary and aligns the connector with the
  Qwairy interface.
</Note>

<Note>
  This source is aggregated across all providers and models. Provider and model
  dimensions remain present for report compatibility, but their values are
  `All Providers` and `All Models`.
</Note>

## Use this source for

* Competitive analysis
* Share of Voice in the selected answer data
* Sentiment comparison vs competitors
* Position benchmarking
* Coverage ratio: mentioned competitors vs total tracked


# Keyword Performance
Source: https://docs.qwairy.co/looker-studio/sources/keyword-performance

Analyze topic-level metrics through the Looker Studio connector's Keyword Performance source

Aggregated metrics by topic: called "keyword" in the underlying data source fields below: for topic-level analysis.

<Tabs>
  <Tab title="Dimensions">
    | Field       | Type | Description                |
    | ----------- | ---- | -------------------------- |
    | `date`      | Date | Analysis date (YYYY-MM-DD) |
    | `provider`  | Text | AI provider name           |
    | `keywordId` | Text | Keyword unique identifier  |
    | `keyword`   | Text | Keyword text               |
  </Tab>

  <Tab title="Metrics">
    | Field                          | Type    | Aggregation | Description                                                                    |
    | ------------------------------ | ------- | ----------- | ------------------------------------------------------------------------------ |
    | `totalPrompts`                 | Number  | SUM         | Number of prompts with this keyword for the provider row                       |
    | `totalAnswers`                 | Number  | SUM         | Total responses analyzed                                                       |
    | `answersWithBrand`             | Number  | SUM         | Responses mentioning your brand                                                |
    | `answersWithAnyBrand`          | Number  | SUM         | Responses mentioning your brand or a direct competitor                         |
    | `totalSelfMentions`            | Number  | SUM         | Total mentions of your brand                                                   |
    | `totalDirectMentions`          | Number  | SUM         | Total mentions of direct competitors                                           |
    | `sentimentSum`                 | Number  | SUM         | Sum of sentiment scores for your brand mentions                                |
    | `sentimentCount`               | Number  | SUM         | Count of scored brand mentions                                                 |
    | `promptsWithSelfBrand`         | Number  | SUM         | Prompts where your brand appears at least once, across all providers           |
    | `totalPromptsAllProviders`     | Number  | SUM         | Total prompts for this keyword/date across all providers                       |
    | `coveragePromptsWithSelfBrand` | Number  | SUM         | Normalized prompt numerator used by `coverage`                                 |
    | `coverageTotalPrompts`         | Number  | SUM         | Normalized prompt denominator used by `coverage`                               |
    | `brandMentionRate`             | Percent | Calculated  | `SUM(answersWithBrand) / SUM(answersWithAnyBrand)`                             |
    | `shareOfVoice`                 | Percent | Calculated  | `SUM(totalSelfMentions) / (SUM(totalSelfMentions) + SUM(totalDirectMentions))` |
    | `avgSentiment`                 | Percent | Calculated  | `SUM(sentimentSum) / SUM(sentimentCount)`                                      |
    | `coverage`                     | Percent | Calculated  | `SUM(coveragePromptsWithSelfBrand) / SUM(coverageTotalPrompts)`                |
  </Tab>
</Tabs>

<Note>
  The percentage metrics are calculated from raw counters in Looker Studio.
  This avoids averaging provider rows and keeps topic-level totals aligned with
  the Qwairy interface.
</Note>

<Note>
  `coverage` is calculated at keyword/date level across all providers, then
  exposed through normalized counters so provider rows do not overweight dates
  when reports aggregate a date range.
</Note>

## Use this source for

* Keyword performance tracking
* SEO-aligned analysis
* Topic prioritization
* Identifying high-performing topics


# Local Insights
Source: https://docs.qwairy.co/looker-studio/sources/local-insights

Local business recommendations extracted from AI responses in Looker Studio.

Local business recommendations extracted from structured results returned by
compatible models. Availability varies by provider and model.

<Tabs>
  <Tab title="Dimensions">
    | Field          | Type   | Description                              |
    | -------------- | ------ | ---------------------------------------- |
    | `date`         | Date   | Analysis date (YYYY-MM-DD)               |
    | `provider`     | Text   | AI provider name                         |
    | `prompt`       | Text   | Original prompt (truncated to 200 chars) |
    | `businessName` | Text   | Business name                            |
    | `category`     | Text   | Business category                        |
    | `address`      | Text   | Business address                         |
    | `websiteUrl`   | Text   | Business website URL                     |
    | `position`     | Number | Position in the list (1 = top)           |
  </Tab>

  <Tab title="Metrics">
    | Field         | Type   | Description           |
    | ------------- | ------ | --------------------- |
    | `rating`      | Number | Business rating (0-5) |
    | `reviewCount` | Number | Number of reviews     |
  </Tab>
</Tabs>

## Use this source for

* Local SEO analysis
* Business presence tracking in AI local results
* Location-based visibility
* Competitive local analysis


# Performance Overview
Source: https://docs.qwairy.co/looker-studio/sources/performance-overview

High-level daily performance metrics aggregated by provider in Looker Studio.

High-level daily performance metrics aggregated by provider.

<Tabs>
  <Tab title="Dimensions">
    | Field      | Type | Description                                                        |
    | ---------- | ---- | ------------------------------------------------------------------ |
    | `date`     | Date | Analysis date (YYYY-MM-DD)                                         |
    | `provider` | Text | AI provider name                                                   |
    | `topic`    | Text | Topic included when requested as a dimension or server-side filter |
    | `tag`      | Text | Tag included when requested as a dimension or server-side filter   |
  </Tab>

  <Tab title="Metrics">
    | Field                          | Type    | Aggregation | Description                                                                    |
    | ------------------------------ | ------- | ----------- | ------------------------------------------------------------------------------ |
    | `totalAnswers`                 | Number  | SUM         | Total responses analyzed                                                       |
    | `answersWithSelfBrand`         | Number  | SUM         | Answers mentioning your brand                                                  |
    | `answersWithAnyBrand`          | Number  | SUM         | Answers mentioning your brand or any direct competitor                         |
    | `answersWithSelfSource`        | Number  | SUM         | Answers citing one of your sources                                             |
    | `answersWithAnySource`         | Number  | SUM         | Answers citing your or any direct competitor source                            |
    | `totalSelfMentions`            | Number  | SUM         | Total brand mentions (raw count)                                               |
    | `totalDirectMentions`          | Number  | SUM         | Total direct competitor mentions (raw count)                                   |
    | `positionSum`                  | Number  | SUM         | Sum of brand mention positions (component field)                               |
    | `positionCount`                | Number  | SUM         | Count of positioned brand mentions (component field)                           |
    | `sentimentSum`                 | Number  | SUM         | Sum of brand mention sentiment scores (component field)                        |
    | `sentimentCount`               | Number  | SUM         | Count of scored brand mentions (component field)                               |
    | `totalPrompts`                 | Number  | SUM         | Total monitored prompts for the date                                           |
    | `promptsWithSelfBrand`         | Number  | SUM         | Prompts where your brand appears at least once                                 |
    | `coverageTotalPrompts`         | Number  | SUM         | Normalized prompt denominator used by `coverage`                               |
    | `coveragePromptsWithSelfBrand` | Number  | SUM         | Normalized prompt numerator used by `coverage`                                 |
    | `totalResponses`               | Number  | SUM         | Total responses analyzed                                                       |
    | `responsesWithSelfBrand`       | Number  | SUM         | Responses mentioning your brand                                                |
    | `brandMentionVisibility`       | Percent | Calculated  | `SUM(answersWithSelfBrand) / SUM(answersWithAnyBrand)`                         |
    | `shareOfVoice`                 | Percent | Calculated  | `SUM(totalSelfMentions) / (SUM(totalSelfMentions) + SUM(totalDirectMentions))` |
    | `sourceCitationVisibility`     | Percent | Calculated  | `SUM(answersWithSelfSource) / SUM(answersWithAnySource)`                       |
    | `coverage`                     | Percent | Calculated  | `SUM(coveragePromptsWithSelfBrand) / SUM(coverageTotalPrompts)`                |
    | `responseCoverage`             | Percent | Calculated  | `SUM(responsesWithSelfBrand) / SUM(totalResponses)`                            |
    | `avgSentiment`                 | Percent | Calculated  | `SUM(sentimentSum) / SUM(sentimentCount)`                                      |
    | `brandMentionAvgPosition`      | Number  | Calculated  | `SUM(positionSum) / SUM(positionCount)`                                        |
  </Tab>
</Tabs>

<Note>
  All ratio and average metrics are calculated as `SUM(numerator) /
    SUM(denominator)`, so they stay volume-weighted and match the Qwairy
  interface across any grouping or date range.
</Note>

<Note>
  `coverage` is prompt coverage: the share of monitored prompts where your
  brand appears at least once. `responseCoverage` is response coverage: the
  share of generated responses that mention your brand.
</Note>

<Note>
  `coverage` uses normalized all-provider counters. This keeps multi-provider
  rows from overweighting dates when reports aggregate a date range.
</Note>

## Use this source for

* Executive dashboards
* Trend analysis over time
* Provider comparison (ChatGPT vs Claude vs Perplexity)
* High-level KPI tracking


# Prompt Performance
Source: https://docs.qwairy.co/looker-studio/sources/prompt-performance

Analyze individual monitored prompts and period-level mention state in Looker Studio

Detailed prompt-level metrics for analyzing individual query performance.

<Tabs>
  <Tab title="Dimensions">
    | Field                       | Type    | Description                                                                                      |
    | --------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
    | `date`                      | Date    | Response date (YYYY-MM-DD)                                                                       |
    | `provider`                  | Text    | AI provider (ChatGPT, Claude, Perplexity, etc.)                                                  |
    | `funnel`                    | Text    | Query intent stage (TOFU, MOFU, BOFU)                                                            |
    | `topic`                     | Text    | Associated keyword/topic                                                                         |
    | `tag`                       | Text    | Tag names joined with " \| " (or "Untagged")                                                     |
    | `prompt`                    | Text    | Prompt text (truncated to 200 chars)                                                             |
    | `brandMentioned`            | Boolean | True if your brand was mentioned                                                                 |
    | `brandMentionedLabel`       | Text    | `Oui` or `Non`, useful for dropdown controls                                                     |
    | `promptBrandMentioned`      | Boolean | True if the brand was mentioned for this prompt anywhere in the selected period                  |
    | `promptBrandMentionedLabel` | Text    | Period-level `Oui` or `Non`, useful for isolating prompts never mentioned in the selected period |
  </Tab>

  <Tab title="Metrics">
    | Field                 | Type    | Description                                                                                                       |
    | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
    | `score`               | Percent | % of brand-mentioning responses among responses mentioning any tracked brand (null when none)                     |
    | `brandMentions`       | Number  | Total brand mentions count                                                                                        |
    | `promptBrandMentions` | Number  | Period-level brand mention total for the prompt; aggregated with MAX because it repeats on each date/provider row |
    | `sourceCitations`     | Number  | Citations of your own sources                                                                                     |
    | `shareOfVoice`        | Percent | Brand / (Brand + Competitors) mentions (null when no mentions)                                                    |
    | `sentiment`           | Percent | Average sentiment score (0-100), null when the brand is not mentioned                                             |
    | `brandPosition`       | Number  | Average brand mention position (null when not mentioned)                                                          |
  </Tab>
</Tabs>

<Note>
  Each row covers one prompt per date and provider. Prompts carrying several
  tags appear once, with all tag names joined in the `tag` field, so SUM
  metrics are never double-counted. To filter on a specific tag, use a
  `CONTAINS_TEXT` condition instead of an exact match.
</Note>

<Note>
  Aggregated `shareOfVoice` here is a prompt-level average (each prompt weighs
  the same regardless of volume), so it will not match the brand-level Share of
  Voice. For the volume-weighted brand figure shown in the Qwairy interface,
  use the Performance Overview connector's Share of Voice.
</Note>

<Note>
  Use `brandMentioned` or `brandMentionedLabel` for a specific date/provider row.
  Use `promptBrandMentioned` or `promptBrandMentionedLabel` to isolate prompts
  where the brand never appears anywhere in the complete selected period.
</Note>

## Use this source for

* Comparing prompt-level observations
* Comparing funnel stages (TOFU, MOFU, BOFU)
* Tag-based filtering and analysis
* Reviewing prompt-level visibility trends


# Search Insights
Source: https://docs.qwairy.co/looker-studio/sources/search-insights

Web search queries generated by AI providers during response generation in Looker Studio.

Web search queries generated by AI providers during response generation.

<Tabs>
  <Tab title="Dimensions">
    | Field      | Type | Description                              |
    | ---------- | ---- | ---------------------------------------- |
    | `date`     | Date | Analysis date (YYYY-MM-DD)               |
    | `provider` | Text | AI provider name                         |
    | `prompt`   | Text | Original prompt (truncated to 200 chars) |
    | `query`    | Text | Search query used by the AI              |
  </Tab>

  <Tab title="Metrics">
    | Field                | Type   | Description                                                         |
    | -------------------- | ------ | ------------------------------------------------------------------- |
    | `count`              | Number | Query count (for aggregation)                                       |
    | `totalBrandMentions` | Number | Mentions of your brand plus direct competitors linked to the answer |
    | `ownBrandMentions`   | Number | Mentions of your brand linked to the answer                         |
  </Tab>
</Tabs>

## Use this source for

* Understanding AI search behavior
* Keyword discovery
* Search pattern analysis
* Identifying what queries AI uses to find information


# Shopping Insights
Source: https://docs.qwairy.co/looker-studio/sources/shopping-insights

Product recommendations extracted from AI responses in Looker Studio.

Product recommendations extracted from structured results returned by
compatible models. Availability varies by provider and model.

<Tabs>
  <Tab title="Dimensions">
    | Field         | Type | Description                                  |
    | ------------- | ---- | -------------------------------------------- |
    | `date`        | Date | Analysis date (YYYY-MM-DD)                   |
    | `provider`    | Text | AI provider name                             |
    | `prompt`      | Text | Original prompt (truncated to 200 chars)     |
    | `productName` | Text | Product name                                 |
    | `description` | Text | Product description (truncated to 300 chars) |
    | `image`       | Text | Product image URL                            |
  </Tab>

  <Tab title="Metrics">
    | Field          | Type   | Description                  |
    | -------------- | ------ | ---------------------------- |
    | `rating`       | Number | Product rating (0-5)         |
    | `reviews`      | Number | Number of reviews            |
    | `optionsCount` | Number | Number of purchasing options |
  </Tab>
</Tabs>

## Use this source for

* E-commerce visibility tracking
* Product presence in AI shopping results
* Competitive product analysis
* Understanding AI product recommendations


# Social Insights
Source: https://docs.qwairy.co/looker-studio/sources/social-insights

Citations from social platforms (Reddit, YouTube, Twitter, forums) in Looker Studio.

Citations from social platforms (Reddit, YouTube, Twitter, forums).

<Tabs>
  <Tab title="Dimensions">
    | Field           | Type | Description                                      |
    | --------------- | ---- | ------------------------------------------------ |
    | `date`          | Date | Analysis date (YYYY-MM-DD)                       |
    | `provider`      | Text | AI provider name                                 |
    | `platform`      | Text | Social platform (reddit, youtube, twitter, etc.) |
    | `communityId`   | Text | Community identifier (subreddit name, channel)   |
    | `communityName` | Text | Community display name                           |
    | `sourceUrl`     | Text | Full URL of the cited content                    |
    | `sourceTitle`   | Text | Content title                                    |
    | `sourceDomain`  | Text | Domain name                                      |
  </Tab>

  <Tab title="Metrics">
    | Field            | Type    | Description                     |
    | ---------------- | ------- | ------------------------------- |
    | `citationsCount` | Number  | Number of citations             |
    | `avgPosition`    | Number  | Average citation position       |
    | `upvotes`        | Number  | Reddit upvotes (when available) |
    | `commentCount`   | Number  | Comment count (when available)  |
    | `shareOfVoice`   | Percent | % of total social citations     |
  </Tab>
</Tabs>

## Use this source for

* Social media visibility in AI responses
* Reddit and YouTube presence tracking
* Community engagement analysis
* Understanding which social content AI cites


# Source Domains
Source: https://docs.qwairy.co/looker-studio/sources/source-domains

Domain-level metrics for tracking which domains are cited in Looker Studio.

Domain-level metrics for tracking which domains are cited (aggregated view).

<Tabs>
  <Tab title="Dimensions">
    | Field          | Type    | Description                                                  |
    | -------------- | ------- | ------------------------------------------------------------ |
    | `date`         | Date    | Analysis date (YYYY-MM-DD)                                   |
    | `provider`     | Text    | AI provider name                                             |
    | `sourceDomain` | Text    | Domain name (e.g., qwairy.co)                                |
    | `sourceType`   | Text    | Category (INSTITUTIONAL, MEDIA, BLOG, etc.)                  |
    | `isSelf`       | Boolean | True if this is your domain                                  |
    | `isCompetitor` | Boolean | True if this is a direct competitor's domain                 |
    | `relationship` | Text    | SELF, DIRECT, or empty when no tracked relationship is found |
    | `competitorId` | Text    | Stable competitor domain identifier                          |
    | `competitor`   | Text    | Competitor display name                                      |
  </Tab>

  <Tab title="Metrics">
    | Field           | Type    | Description                      |
    | --------------- | ------- | -------------------------------- |
    | `totalMentions` | Number  | Total citations count            |
    | `uniqueAnswers` | Number  | Distinct responses with citation |
    | `avgPosition`   | Number  | Average citation position        |
    | `shareOfVoice`  | Percent | % of total citations             |
  </Tab>
</Tabs>

<Note>
  Use `isCompetitor`, `relationship`, `competitorId`, or `competitor` to build
  filters that can also be applied to Source URLs. Both source connectors expose
  the same competitor identity fields.
</Note>

<Note>
  `shareOfVoice` is computed per day and underlying model before the model is
  mapped to its provider label. If several models from one provider are present,
  the connector's `AVG` is an unweighted average of their shares. For a
  volume-weighted share, use `totalMentions` with Looker Studio's built-in
  "Percent of total" comparison.
</Note>

## Use this source for

* Domain-level citation analysis
* Reviewing which domains are cited in the selected answers
* Tracking your domain vs competitors
* Source type breakdown (media, blogs, forums)


# Source URLs
Source: https://docs.qwairy.co/looker-studio/sources/source-urls

Analyze cited pages at URL, topic, or tag grain in Looker Studio.

Use one of the three Source URLs data sources according to the grain required
by your report. The original **Source URLs** option keeps its existing schema.
The topic and tag options aggregate metrics at their selected grain instead of
repeating the metrics from the original source.

## Choose a Source URLs data source

| Data source              | Grain and fields                                           | Use for                                                     |
| ------------------------ | ---------------------------------------------------------- | ----------------------------------------------------------- |
| **Source URLs**          | URL rows with the combined `Topics` and `Tags` text fields | Existing reports, global citation totals, and URL filtering |
| **Source URLs by Topic** | URL and `Topic` rows                                       | Comparing cited pages across topics                         |
| **Source URLs by Tag**   | URL and `Tag` rows                                         | Comparing cited pages across tags                           |

Create a separate Looker Studio data source for every grain needed in a report.
Do not replace an existing **Source URLs** connection when adding a topic or tag
breakdown.

<Steps>
  <Step title="Add another Qwairy data source">
    In your Looker Studio report, select **Add data**, then select the Qwairy
    connector. See [Connect Looker Studio](/looker-studio/getting-started) for
    the complete connection procedure.
  </Step>

  <Step title="Configure the connection">
    Enter your existing API token, select the same brand, and choose **Source
    URLs by Topic** or **Source URLs by Tag**.
  </Step>

  <Step title="Connect the new source">
    Select **Connect**, then use the singular **Topic** or **Tag** dimension in
    the charts that require the breakdown.
  </Step>
</Steps>

## Fields

<Tabs>
  <Tab title="Common dimensions">
    | Field          | Type    | Description                                                  |
    | -------------- | ------- | ------------------------------------------------------------ |
    | `date`         | Date    | Analysis date (YYYY-MM-DD)                                   |
    | `provider`     | Text    | AI provider name                                             |
    | `sourceUrl`    | Text    | Full URL of the cited page                                   |
    | `sourceTitle`  | Text    | Page title                                                   |
    | `sourceDomain` | Text    | Domain name                                                  |
    | `sourceType`   | Text    | Source category, such as MEDIA, BLOG, or FORUM               |
    | `isSelf`       | Boolean | True if this is your domain                                  |
    | `isCompetitor` | Boolean | True if this is a direct competitor's domain                 |
    | `relationship` | Text    | SELF, DIRECT, or empty when no tracked relationship is found |
    | `competitorId` | Text    | Stable competitor domain identifier                          |
    | `competitor`   | Text    | Competitor display name                                      |
  </Tab>

  <Tab title="Grain-specific dimensions">
    | Data source              | Field    | Description                                                     |
    | ------------------------ | -------- | --------------------------------------------------------------- |
    | **Source URLs**          | `topics` | Topics linked to the URL's answers, separated by `\|`           |
    | **Source URLs**          | `tags`   | Tags linked to the URL's answers, separated by `\|`             |
    | **Source URLs by Topic** | `topic`  | One topic for the current row; empty when no topic is assigned  |
    | **Source URLs by Tag**   | `tag`    | One tag for the current row; `Untagged` when no tag is assigned |
  </Tab>

  <Tab title="Metrics">
    | Field           | Type    | Description                                      |
    | --------------- | ------- | ------------------------------------------------ |
    | `totalMentions` | Number  | Citation count at the selected data-source grain |
    | `avgPosition`   | Number  | Average citation position at the selected grain  |
    | `shareOfVoice`  | Percent | Share of daily citations at the selected grain   |
  </Tab>
</Tabs>

## Aggregate tag rows correctly

A prompt can have several tags. In **Source URLs by Tag**, a citation associated
with that prompt contributes to every matching tag row. Metrics are accurate
within each tag, but totals from separate tag rows are not additive.

* Use the original **Source URLs** data source for a global citation total.
* To count unique pages across selected tag rows, set **Source URL** aggregation
  to **Count Distinct** in Looker Studio.
* Treat `Untagged` as one displayed group. It includes prompts without a tag and
  any tag that is literally named `Untagged`.

<Note>
  Existing **Source URLs** connections keep their current fields and do not need
  to be reconfigured. The two breakdowns are available only when you add a new
  Qwairy data source and select the corresponding option.
</Note>

<Note>
  Use the competitor fields to synchronize filters with Source Domains. For
  example, a filter on `isCompetitor = true` can be reused across domain-level
  and URL-level source charts.
</Note>

<Note>
  `shareOfVoice` is computed per day and underlying model before the model is
  mapped to its provider label. If several models from one provider are present,
  the connector's `AVG` is an unweighted average of their shares. For a
  volume-weighted share, use `totalMentions` with Looker Studio's built-in
  "Percent of total" comparison.
</Note>

## Use this source for

* Page-level citation analysis
* Comparing cited URLs by topic or tag
* Identifying specific competitor content being cited
* Tracking which of your pages AI cites most
* Reviewing citation gaps alongside other Qwairy evidence


# Tag Performance
Source: https://docs.qwairy.co/looker-studio/sources/tag-performance

Aggregated metrics by tag for grouped analysis in Looker Studio.

Aggregated metrics by tag for grouped analysis.

<Tabs>
  <Tab title="Dimensions">
    | Field      | Type | Description                |
    | ---------- | ---- | -------------------------- |
    | `date`     | Date | Analysis date (YYYY-MM-DD) |
    | `provider` | Text | AI provider name           |
    | `tagId`    | Text | Tag unique identifier      |
    | `tagName`  | Text | Tag display name           |
  </Tab>

  <Tab title="Metrics">
    | Field              | Type    | Description                                                                                                                                                                       |
    | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `totalPrompts`     | Number  | Number of prompts with this tag                                                                                                                                                   |
    | `totalAnswers`     | Number  | Total responses analyzed                                                                                                                                                          |
    | `brandMentionRate` | Percent | Responses mentioning the tracked brand (`SELF`) divided by responses mentioning the tracked brand or a direct competitor (`SELF` or `DIRECT`); `0` when that denominator is empty |
    | `shareOfVoice`     | Percent | Brand vs competitors share                                                                                                                                                        |
    | `avgSentiment`     | Percent | Average sentiment score                                                                                                                                                           |
  </Tab>
</Tabs>

## Use this source for

* Category performance tracking
* Content grouping analysis
* Comparing tag performance over time
* Campaign or initiative tracking


# Troubleshoot Looker Studio
Source: https://docs.qwairy.co/looker-studio/troubleshooting

Resolve connection, schema, date-range, and metric-alignment issues in the Qwairy Looker Studio connector

## Date filtering

All data sources support Looker Studio's native date range controls. Add a **Date Range Control** to your dashboard to filter data dynamically.

<Note>
  If no date range is specified, data defaults to the last 90 days.
</Note>

***

## Data volume

The connector requests rows for the selected date range and dimensions. Large ranges or high-cardinality fields can make a report slower or harder to read. Narrow the date range and request only the fields required by the chart before splitting the report into several data sources.

***

## Common issues

### Unable to complete authorization

When the authorization step shows "This app is blocked" with no option to proceed:

<img alt="Google Workspace warning that the connector is blocked" />

**Cause:** Your organization's Google Workspace security policies block third-party connectors.

**Solution:** Contact your Google Workspace administrator to allow the Qwairy connector:

1. Open **Google Admin Console**
2. Go to **Security** → **API Controls**
3. Click **Manage Third-Party App Access**
4. Allow access for the **Qwairy connector**

***

### No data appearing in reports

1. Verify your API token is valid in Team Management
2. Ensure the selected brand has monitoring data
3. Check that the date range includes dates with data
4. Confirm your team subscription is active

***

### How to refresh data

Looker Studio caches data for performance. To refresh:

* Click the **Refresh data** button in your report
* Or set up automatic refresh in your data source settings

***

### New fields do not appear after a connector update

When Qwairy adds or changes connector fields, existing Looker Studio data
sources keep their previous schema until you refresh it manually:

1. Open your report in edit mode
2. Go to **Resource → Manage added data sources**
3. Click **Edit** on the Qwairy data source
4. Click **Refresh fields**
5. Confirm the field changes

Refresh fields after connector updates that add metrics such as `coverage`,
`responseCoverage`, `competitorId`, `brandMentionedLabel`,
`totalBrandMentions`, or `ownBrandMentions`.

***

### Numbers in Looker do not match the Qwairy interface

On **Performance Overview** and **Keyword Performance**, ratio metrics are
calculated from raw counters in Looker Studio:
`SUM(numerator) / SUM(denominator)`. This avoids averaging provider rows and
keeps totals aligned with the Qwairy interface. If your dashboard still shows
older numbers, refresh the schema:
**Resource → Manage added data sources → Refresh fields**.

On **Competitor Metrics**, rows are grouped by `competitorId` and aggregated
across all providers/models. The `provider` and `model` dimensions remain
available for compatibility, but their values are `All Providers` and
`All Models`.

For source reports, use `isCompetitor`, `relationship`, `competitorId`, or
`competitor` for synchronized filters across **Source Domains** and
**Source URLs**.

***

### "Mentioned in period" vs "Total tracked" competitors

Competitor Metrics rows only include competitors mentioned in the selected
period. `totalTrackedCompetitors` returns the brand-level registered count
(constant, ignores filters). Combine them for a coverage ratio:

```
COUNT_DISTINCT(competitor) / MAX(totalTrackedCompetitors)
```


# Competitor deep dive
Source: https://docs.qwairy.co/mcp/examples/competitive-deep-dive

Inspect where and how a selected competitor appears in the authorized monitoring scope

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Investigate a competitor

Use this workflow to compare a competitor's observed mentions, sources, topics, and answer context before forming an action hypothesis.

<Steps>
  <Step title="Identify a material change">
    **You:** Show me my competitors ranked by mentions. Is anyone gaining ground?

    Claude lists the competitors and their observed trends. One competitor went from 45 mentions in the previous period to 112 in the current period. Verify that both periods use the same filters, providers, and prompt set before investigating the change.
  </Step>

  <Step title="Get the full competitor profile">
    **You:** Give me the full profile on that competitor: coverage, SOV, sources, everything.

    Claude returns the competitor's coverage, share of voice trend, average position, cited sources, and shopping or local overlap. Media citations increased during the same period. Treat a PR campaign as a hypothesis unless separate evidence confirms it.
  </Step>

  <Step title="Track their evolution">
    **You:** Show me their evolution over the last 90 days. When did they start growing?

    Claude shows the daily trend and the first date on which the stored observations increased. Compare that date with known launches or campaigns, without treating timing alone as proof of cause.
  </Step>

  <Step title="Find their weak spots">
    **You:** On which topics am I still stronger?

    Claude uses the visibility matrix to compare the brands by topic. The sample shows higher values for your brand on DIY and technical prompts, and higher values for the competitor on mass-market consumer prompts.
  </Step>

  <Step title="Analyze their source advantage">
    **You:** What sources cite them that don't cite me?

    Claude identifies sources that cite the competitor but not your brand, including media outlets, review sites, and marketplaces. Review relevance, editorial fit, and source quality before treating any domain as an outreach candidate.
  </Step>

  <Step title="Form testable priorities">
    **You:** Based on all this, what's my strategy?

    The combined analysis supports a set of hypotheses to test:

    1. Preserve coverage on topics where your brand currently records higher values.
    2. Review contested topics where both brands appear.
    3. Compare content and distribution on topics where the competitor records higher values.
    4. Qualify relevant sources that cite the competitor but not your brand.
  </Step>
</Steps>


# MCP competitor review
Source: https://docs.qwairy.co/mcp/examples/competitors

Compare configured competitors, trends, positions, and answer evidence through MCP

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Understanding your competitive landscape

### Who are my competitors in AI?

<Accordion title="Which competitors appear in AI responses?">
  **You:**

  Who are my top competitors in AI search results?

  **Claude:**

  Top competitors for **NordFit** (ranked by mention frequency):

  | Rank | Competitor  | Mentions | Avg Position | Sentiment |
  | ---- | ----------- | -------- | ------------ | --------- |
  | 1    | Peloton     | 520      | 2.0          | 80        |
  | 2    | Mirror      | 345      | 2.6          | 76        |
  | 3    | **NordFit** | 312      | 2.3          | 78        |
  | 4    | Tonal       | 256      | 3.1          | 73        |
  | 5    | Hydrow      | 198      | 3.4          | 71        |

  NordFit ranks third by mention count in this sample. Peloton has 67% more observed mentions, while NordFit's SELF sentiment value is 78 on the returned scale.
</Accordion>

### Head-to-head comparison

<Accordion title="Compare me directly against my top competitor">
  **You:**

  Compare me head-to-head against Peloton.

  **Claude:**

  **NordFit vs Peloton** (last 30 days):

  | Metric         | NordFit | Peloton |
  | -------------- | ------- | ------- |
  | Mentions       | 312     | 520     |
  | Avg Position   | 2.3     | 2.0     |
  | Sentiment      | 78      | 80      |
  | Share of Voice | 26%     | 41%     |

  **Higher NordFit value:** Home gym equipment and budget fitness, where the sampled mention rates are 48% for NordFit and 22% for Peloton.

  **Higher Peloton value:** Connected fitness and live classes, where Peloton appears in 70% of the selected query observations.

  **Hypothesis to review:** Compare answer and source evidence for value, compact equipment, and premium connected-fitness prompts before choosing which positioning to test.
</Accordion>

### Deep-dive on a competitor

<Accordion title="Why are they ahead? What sources support them?">
  **You:**

  Give me the full profile on Peloton: coverage, sources, overlap.

  **Claude:**

  **Peloton**: Deep-dive (last 30 days):

  | Metric         | Value                     |
  | -------------- | ------------------------- |
  | Coverage       | 142/220 questions (64.5%) |
  | Share of Voice | 41%                       |
  | Avg position   | 2.0                       |

  **Top sources citing Peloton:**

  | Source         | Mentions |
  | -------------- | -------- |
  | techcrunch.com | 78       |
  | wired.com      | 52       |
  | reddit.com     | 45       |
  | cnet.com       | 38       |

  **Overlap:** 18 shopping products, 5 local stores.

  Tech media accounts for several of the competitor's cited sources in this sample. Compare relevant fitness-specific sources and review sites before deciding whether outreach or content distribution is appropriate.
</Accordion>

### Prompt signals

<Accordion title="Which prompts should I attack vs defend?">
  **You:**

  Analyze my prompt signals.

  **Claude:**

  | Signal                    | Count |
  | ------------------------- | ----- |
  | Attack (high opportunity) | 28    |
  | Defend (protect position) | 15    |
  | Monitor                   | 48    |
  | Ignore                    | 129   |

  **Highest attack-classification values:**

  | Prompt                               | Market Openness | Your SOV |
  | ------------------------------------ | --------------- | -------- |
  | "best home gym setup 2026"           | 90%             | 6%       |
  | "quiet exercise equipment apartment" | 87%             | 9%       |
  | "fitness equipment small space"      | 84%             | 11%      |

  **Highest defend-classification values:**

  | Prompt                       | Your SOV |
  | ---------------------------- | -------- |
  | "affordable rowing machine"  | 65%      |
  | "compact home gym equipment" | 58%      |

  The tool classifies "best home gym setup 2026" as `ATTACK` with 90% market openness. Review answer context and positioning fit before selecting it for a content test.
</Accordion>


# Content opportunity workflow
Source: https://docs.qwairy.co/mcp/examples/content-strategy

Use observed content, query, shopping, and local gaps to form testable content hypotheses

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Build a content opportunity review

Use Qwairy MCP to investigate where competitors appear and your brand does not. Treat the result as evidence for a content hypothesis, not a guarantee of future mentions or citations.

<Steps>
  <Step title="Find your content gaps">
    **You:** Where do competitors appear in AI responses but I don't?

    Claude finds stored questions where competitors are mentioned and your brand is absent. Each gap is evidence to review, not proof that new content will earn a mention.
  </Step>

  <Step title="Analyze query variations">
    **You:** Show me the query fan-out: what search queries are AI using around my topics?

    Claude returns web search queries detected in the selected answers. Compare small query variations to see whether observed brand presence differs within the sample.
  </Step>

  <Step title="Check shopping visibility">
    **You:** Am I appearing in AI shopping results? Where do competitors show up?

    Claude shows which stores and products appear in the sampled shopping results. Stores carrying competitor products but not yours become candidates for commercial and distribution review.
  </Step>

  <Step title="Explore local signals">
    **You:** Are local businesses appearing in AI responses about my topics?

    Claude returns local businesses mentioned in the selected answers. Check whether any business actually carries your products before deciding on a partnership or listing action.
  </Step>

  <Step title="Prioritize with prompt signals">
    **You:** Which prompts should I attack first?

    Claude returns the tool's attack, defend, monitor, and ignore classifications. Use market openness as one input, then check relevance, answer context, current content, and effort before prioritizing a test.
  </Step>
</Steps>

<Note>
  Prompt classifications and observed gaps prioritize investigation. They do not predict that a specific content change will produce a future mention or citation.
</Note>


# Cross-surface audit workflow
Source: https://docs.qwairy.co/mcp/examples/full-geo-audit

Combine overview, matrix, page-presence, technical, and action evidence in one MCP workflow

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Run a cross-surface audit

Combine multiple tools in one conversation to document the current scope, inspect supporting evidence, and prepare a prioritized review list.

<Steps>
  <Step title="Get the big picture">
    **You:** Give me the full overview for GreenLeaf Cosmetics over the last 30 days, with comparison to the previous period.

    Claude returns key counts, scores, and trend vs previous 30 days. You immediately see if things are improving or declining.
  </Step>

  <Step title="Find weak spots in the matrix">
    **You:** Show me the visibility matrix by topic.

    Claude displays a topic × provider grid. You spot cells with low visibility (e.g., "Hair Care × Gemini = 12%") and compare to your strong cells.
  </Step>

  <Step title="Check which pages AI cites">
    **You:** Which of my pages are cited by AI? And which are invisible?

    Claude shows pages categorized by status: WORKING, NEEDS\_ATTENTION, NOT\_CITED, and DISCOVERED. The result distinguishes pages with no recorded citation from cited pages absent from the sitemap inventory.
  </Step>

  <Step title="Verify technical readiness">
    **You:** Is my site technically ready for AI crawlers?

    Claude checks robots.txt, llms.txt, sitemap, and crawler directives. Review any access issue against the site's intended policy; this check does not predict visibility impact.
  </Step>

  <Step title="Get a prioritized action plan">
    **You:** Based on everything, what are my top 5 actions sorted by impact?

    Claude returns the Action Center's priority, impact, and effort classifications alongside the earlier evidence. Treat the resulting list as triage input and confirm each item before acting.
  </Step>
</Steps>

<Note>
  This workflow combines five surfaces. Keep their scopes distinct: overview and matrix summarize stored answers, page presence records citations, technical status checks public configuration, and Action Center applies its own prioritization rules.
</Note>


# First MCP conversation
Source: https://docs.qwairy.co/mcp/examples/getting-started

Discover accessible brands, inspect one performance scope, and identify evidence to review next

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Your first three questions

Use this sequence after connecting any MCP-compatible client to Qwairy.

### 1. Discover your brands

<Accordion title="What brands am I tracking?">
  **You:**

  What brands do I have in Qwairy?

  **Claude:**

  You have 2 monitored brands:

  1. **FreshBrew Coffee**: freshbrew\.com
  2. **FreshBrew B2B**: freshbrewb2b.com

  Which brand would you like to analyze?
</Accordion>

### 2. Inspect the selected performance scope

<Accordion title="How is my brand doing in AI right now?">
  **You:**

  Give me the full overview for FreshBrew Coffee over the last 30 days.

  **Claude:**

  Here's the cockpit overview for **FreshBrew Coffee**:

  **Last monitoring:** March 14, 2026

  | Metric         | Current | vs Previous 30 days |
  | -------------- | ------- | ------------------- |
  | Mention Rate   | 38.5%   | +2.8%               |
  | Source Rate    | 15.2%   | +0.9%               |
  | Share of Voice | 24.3%   | -1.5%               |
  | Sentiment      | 81/100  | +3                  |

  **Key counts:**

  * 180 monitored questions → 2,640 AI responses
  * 35 competitors detected, 94 sources cited
  * 62 social citations, 28 shopping results

  Your brand visibility is growing (+2.8% mention rate), but Share of Voice dropped: competitors may be gaining on certain topics.
</Accordion>

### 3. Identify what to focus on

<Accordion title="Where should I focus my efforts?">
  **You:**

  Based on this, what are the top 3 things I should focus on?

  **Claude:**

  **1. Investigate the Share of Voice decline (-1.5%)**

  Your SOV dropped mainly on "specialty coffee" and "coffee subscription" topics, where two competitors increased their presence significantly.

  **2. Capitalize on your shopping presence (28 results)**

  You appeared in 28 sampled shopping results across ChatGPT and Google AI Mode. Competing merchants appeared more often in the sampled Amazon and specialty-retailer results.

  **3. Fix your technical setup**

  Your `llms.txt` file is missing. Confirm whether that is intentional and assess it alongside crawler access, indexing, and citation evidence; this finding alone does not predict visibility impact.

  Want me to dive into any of these?
</Accordion>


# MCP performance review
Source: https://docs.qwairy.co/mcp/examples/performance

Inspect visibility trends, provider differences, topic breakdowns, and matrix evidence through MCP

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Weekly performance review

A workflow for recording trends, comparing providers, and investigating topic differences with a consistent scope.

### Check the trend

<Accordion title="Is my visibility improving or declining?">
  **You:**

  Show me my visibility trend over the last 30 days, grouped by week.

  **Claude:**

  Visibility trend for **TechFlow** (weekly):

  | Week | Responses | Brand Mentions | Visibility Rate | Sentiment |
  | ---- | --------- | -------------- | --------------- | --------- |
  | W10  | 286       | 112            | 39%             | 71        |
  | W11  | 310       | 134            | 43%             | 73        |
  | W12  | 274       | 105            | 38%             | 74        |
  | W13  | 328       | 152            | 46%             | 75        |

  Trend: **Improving** (+7% from first to second half). Week 12 dipped but Week 13 recovered strongly with your best numbers yet.
</Accordion>

### Compare providers

<Accordion title="Which providers have the highest and lowest observed rates?">
  **You:**

  Break this down by AI provider.

  **Claude:**

  Provider breakdown (last 30 days):

  | Provider   | Responses | Mentions | Visibility | Sentiment |
  | ---------- | --------- | -------- | ---------- | --------- |
  | ChatGPT    | 724       | 355      | 49%        | 77        |
  | Claude     | 548       | 247      | 45%        | 75        |
  | Perplexity | 445       | 151      | 34%        | 71        |
  | Gemini     | 382       | 115      | 30%        | 70        |
  | Copilot    | 268       | 110      | 41%        | 73        |

  **Highest observed visibility:** ChatGPT (49%, with the highest sentiment value in this sample).

  **Lowest observed visibility:** Gemini (30%). This table does not identify the cause; inspect the underlying prompts, answers, sources, and comparable provider coverage before forming a hypothesis.
</Accordion>

### Find the topic gaps

<Accordion title="Which topics need attention?">
  **You:**

  Show me performance by topic.

  **Claude:**

  Topic performance:

  | Topic               | Score | Mention Rate | Source Rate | SOV |
  | ------------------- | ----- | ------------ | ----------- | --- |
  | Project Management  | 74    | 55%          | 30%         | 40% |
  | Team Collaboration  | 65    | 45%          | 22%         | 33% |
  | Workflow Automation | 48    | 32%          | 16%         | 24% |
  | Time Tracking       | 28    | 20%          | 9%          | 14% |
  | Reporting           | 42    | 30%          | 18%         | 26% |

  **Highest observed score:** Project Management (74) in this sample.

  **Lowest observed score:** Time Tracking (28). Review the underlying answers and competitor mentions before deciding whether this is a content or positioning gap.
</Accordion>

### Read the visibility matrix

<Accordion title="Show me topics × providers to find exact weak spots">
  **You:**

  Show me the full visibility matrix.

  **Claude:**

  GEO Matrix (last 30 days):

  | Topic               | ChatGPT | Claude | Perplexity | Gemini | Overall |
  | ------------------- | ------- | ------ | ---------- | ------ | ------- |
  | Project Management  | 62%     | 55%    | 48%        | 40%    | 51%     |
  | Team Collaboration  | 52%     | 45%    | 35%        | 28%    | 40%     |
  | Workflow Automation | 38%     | 32%    | 28%        | 20%    | 30%     |
  | Time Tracking       | 24%     | 20%    | 18%        | 14%    | 19%     |
  | Reporting           | 40%     | 35%    | 25%        | 20%    | 30%     |

  **Pattern:** Gemini has the lowest value in every topic row shown. In the Time Tracking × Gemini cell, TechFlow records 14% and a selected competitor records 52%. The competitor also has landing pages for these queries, but the matrix does not establish that those pages caused the difference.
</Accordion>


# MCP answer review
Source: https://docs.qwairy.co/mcp/examples/responses

Browse stored answers and inspect brand mentions, citations, competitors, and context through MCP

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Review stored answers

### Browse recent responses

<Accordion title="Show me the latest AI responses mentioning my brand">
  **You:**

  Show me the 5 most recent AI responses where my brand was mentioned.

  **Claude:**

  Latest responses mentioning **CloudSecure**:

  | Date   | Provider   | Prompt                                  | Mentioned | Source Cited |
  | ------ | ---------- | --------------------------------------- | --------- | ------------ |
  | Mar 14 | ChatGPT    | "best cloud security platforms"         | Yes       | Yes          |
  | Mar 14 | Claude     | "zero trust architecture tools"         | Yes       | No           |
  | Mar 14 | Perplexity | "SIEM vs SOAR comparison"               | Yes       | Yes          |
  | Mar 13 | Gemini     | "affordable cybersecurity for startups" | Yes       | No           |
  | Mar 13 | ChatGPT    | "SOC automation tools 2026"             | Yes       | Yes          |

  The sampled answers mention CloudSecure across the providers shown. Three answers also cite its website; a citation confirms source presence in those answers, not its influence on the response.
</Accordion>

### Read the full response

<Accordion title="Show me exactly what ChatGPT said">
  **You:**

  Show me the full details of that ChatGPT response about "best cloud security platforms".

  **Claude:**

  **Response Details:**

  | Field           | Value                           |
  | --------------- | ------------------------------- |
  | Prompt          | "best cloud security platforms" |
  | Provider        | ChatGPT (GPT-5)                 |
  | Date            | March 14, 2026                  |
  | Brand mentioned | Yes, position #3                |
  | Sentiment       | 79/100                          |

  **Competitors mentioned:**

  | Position | Competitor         | Sentiment |
  | -------- | ------------------ | --------- |
  | #1       | CrowdStrike        | 85        |
  | #2       | Palo Alto Networks | 83        |
  | #3       | **CloudSecure**    | 79        |
  | #4       | Zscaler            | 76        |

  **Sources cited:**

  1. gartner.com/reviews (Position #1)
  2. cloudsecure.io/platform (Position #2)
  3. reviews.example/cloud-security (Position #3)

  Your website is cited at position #2. Strengthening your platform page with analyst endorsements could help push you to brand mention position #1.
</Accordion>

### Find content gaps

<Accordion title="Where do competitors appear but I don't?">
  **You:**

  Find prompts where competitors are mentioned but I'm not.

  **Claude:**

  **Content gaps** (last 30 days):

  **Missed opportunities:**

  | Prompt                                 | Competitors mentioned    |
  | -------------------------------------- | ------------------------ |
  | "best endpoint detection and response" | CrowdStrike, SentinelOne |
  | "cloud compliance automation"          | Prisma Cloud, Wiz        |
  | "managed SOC providers"                | Arctic Wolf, Secureworks |

  **Low visibility:**

  | Prompt                  | Visibility |
  | ----------------------- | ---------- |
  | "CSPM tools comparison" | 18%        |
  | "API security testing"  | 12%        |

  **Investigation candidate:** "CSPM tools comparison" has low observed visibility even though the product includes a CSPM feature. Review the stored answers and existing content before testing whether a comparison page changes later observations.
</Accordion>

### Funnel analysis

<Accordion title="Am I visible at every stage of the customer journey?">
  **You:**

  How visible am I at each funnel stage?

  **Claude:**

  | Stage                    | Example Queries                                     | Visibility | Trend |
  | ------------------------ | --------------------------------------------------- | ---------- | ----- |
  | **TOFU** (awareness)     | "what is cloud security"                            | 35%        | +3%   |
  | **MOFU** (consideration) | "best SIEM platforms comparison"                    | 42%        | +1%   |
  | **BOFU** (decision)      | "CloudSecure pricing", "CloudSecure vs CrowdStrike" | 68%        | +2%   |

  You convert well at BOFU but could capture more awareness at TOFU. Educational content about cloud security fundamentals would help you enter the conversation earlier.
</Accordion>


# MCP source review
Source: https://docs.qwairy.co/mcp/examples/sources

Inspect observed source domains, cited URLs, page presence, and social citations through MCP

<Note>
  All organizations, prompts, values, dates, and outputs in this example are synthetic. Tool results depend on the authorized brand, filters, and stored data.
</Note>

## Review the citation landscape

### Which sources are cited in the selected answers?

<Accordion title="What websites do AI assistants cite for my topics?">
  **You:**

  What are the top sources AI cites when answering questions about my industry?

  **Claude:**

  Top sources for **EduPath** topics:

  | Domain             | Type        | Mentions | Avg Position | Self |
  | ------------------ | ----------- | -------- | ------------ | ---- |
  | edupath.com        | Commercial  | 178      | 2.4          | Yes  |
  | coursera.org       | Educational | 156      | 1.6          | No   |
  | edtechmagazine.com | Media       | 98       | 2.2          | No   |
  | reddit.com         | Forum       | 72       | 4.0          | No   |
  | reviews.example    | Review      | 58       | 3.1          | No   |

  Your website has the most citations among commercial sources in this sample. Coursera and the listed media source have a lower average citation position; that observation does not establish why the provider selected or ordered them.
</Accordion>

### Track source momentum

<Accordion title="Which sources are gaining or losing citations?">
  **You:**

  Show me the weekly source trends for the last 30 days. Which domains are gaining ground?

  **Claude:**

  **Source Trends** for **EduPath**:

  | Domain             | Type        | Citations | Previous period | Change |
  | ------------------ | ----------- | --------- | --------------- | ------ |
  | coursera.org       | Educational | 54        | 39              | +38.5% |
  | edtechmagazine.com | Media       | 31        | 28              | +10.7% |
  | reddit.com         | Forum       | 18        | 25              | -28.0% |

  Educational sources now represent 41% of citations, up from the previous period. Coursera is the clearest mover, while Reddit is losing citation share. I would inspect the prompts and pages where Coursera gained before deciding whether this is a content or outreach opportunity.
</Accordion>

### Deep-dive on a source

<Accordion title="Tell me more about a key source domain">
  **You:**

  Give me the full profile on edtechmagazine.com: what pages are cited, who else appears?

  **Claude:**

  **Source Profile: edtechmagazine.com**

  | Metric           | Value |
  | ---------------- | ----- |
  | Type             | Media |
  | Total mentions   | 98    |
  | Unique questions | 31    |
  | Avg position     | 2.2   |

  **Top cited URLs:**

  | URL                            | Mentions |
  | ------------------------------ | -------- |
  | /lms-comparison-2026           | 28       |
  | /ai-in-education-guide         | 22       |
  | /best-corporate-training-tools | 18       |

  **Co-cited competitors:**

  | Competitor     | Co-occurrences |
  | -------------- | -------------- |
  | EduPath (SELF) | 34             |
  | Docebo         | 28             |
  | TalentLMS      | 22             |

  **Backlink available:** Yes: via 3 platforms.

  Your brand co-appears in 35% of the sampled answers that cite this source. Review editorial relevance and existing coverage before deciding whether to test an outreach hypothesis.
</Accordion>

### On-page presence

<Accordion title="Which of my pages are cited by AI?">
  **You:**

  Show me my on-page presence: which pages get cited?

  **Claude:**

  **On-Page Presence** for edupath.com:

  | Stat                        | Count |
  | --------------------------- | ----- |
  | Total pages                 | 245   |
  | Cited by AI                 | 32    |
  | Not cited                   | 198   |
  | Discovered (not in sitemap) | 15    |

  **Top performing pages:**

  | Path                           | Status  | Citations | Questions |
  | ------------------------------ | ------- | --------- | --------- |
  | /features/lms                  | WORKING | 62        | 28        |
  | /blog/corporate-training-guide | WORKING | 38        | 18        |
  | /pricing                       | WORKING | 24        | 12        |

  **Discovered pages** (AI cites them but they're not in your sitemap):

  | Path                      | Citations |
  | ------------------------- | --------- |
  | /help/api-documentation   | 8         |
  | /community/best-practices | 5         |

  Within this inventory, 81% of pages have no recorded citation and 15 cited pages are absent from the sitemap. Review whether those 15 pages are canonical and intended for discovery before changing the sitemap; a citation does not prove quality or future value.
</Accordion>

### Social citations

<Accordion title="Is my brand discussed on social platforms?">
  **You:**

  What social platforms cite my brand?

  **Claude:**

  **Social Insights** (last 30 days):

  | Metric                | Value          |
  | --------------------- | -------------- |
  | Social citations      | 72 / 890 total |
  | Social share of voice | 8.1%           |

  **Platform distribution:**

  | Platform       | Citations | %   |
  | -------------- | --------- | --- |
  | Reddit         | 35        | 49% |
  | YouTube        | 22        | 31% |
  | LinkedIn       | 10        | 14% |
  | Stack Overflow | 5         | 7%  |

  Reddit accounts for the largest share of social citations in this sample. Discussions in r/elearning and r/instructionaldesign frequently reference the platform; this overlap does not establish that they caused the AI responses.
</Accordion>


# Connect an MCP client
Source: https://docs.qwairy.co/mcp/getting-started

Connect an MCP-compatible client to Qwairy with OAuth or a Personal Access Token

Connect your favorite AI assistant to your Qwairy GEO monitoring data. All you need is the server URL:

```
https://mcp.qwairy.co
```

OAuth-capable clients discover Qwairy's OAuth 2.1 flow from this endpoint. Depending on the client, authorization can start automatically, on first use, or after an explicit sign-in command.

For headless clients that cannot complete interactive OAuth, create a Personal Access Token under [**Team Management > MCP Server**](https://www.qwairy.co/dashboard/team/mcp). Prefer OAuth whenever the client supports it.

<Warning>
  MCP client interfaces change independently of Qwairy. The stable inputs are the server URL and OAuth. The client procedures below were verified against the linked vendor documentation on August 28, 2026.
</Warning>

## Prerequisites

* Access to an active Qwairy team on a **Starter plan or higher**, including paid Agency plans
* A client that supports remote MCP servers over Streamable HTTP
* To query monitoring data: at least one accessible active brand with generated responses

## Choose a client

<Tabs>
  <Tab title="Claude Desktop / Claude.ai">
    1. Go to **Settings** → **Connectors**
    2. Click **Add custom connector**
    3. Enter a name (e.g. `Qwairy`) and the server URL:

    ```
    https://mcp.qwairy.co
    ```

    4. Click **Add**, then authorize the connection when prompted

    <Note>
      Custom connectors are available on supported Claude plans. Team and Enterprise workspace owners may need to enable or add the connector for the organization. See [Anthropic's custom connector guide](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp).
    </Note>
  </Tab>

  <Tab title="ChatGPT">
    Availability and publishing controls depend on your ChatGPT plan and workspace policy. Full MCP support is available on ChatGPT Business, Enterprise, and Edu. ChatGPT Pro supports read and fetch custom apps in developer mode.

    1. Confirm that developer mode is enabled for your account. Business admins and owners can enable it from **Workspace Settings > Apps > Create**. Authorized Enterprise and Edu users can also use **Settings > Apps > Advanced Settings**.
    2. Open **Apps > Create**. In a managed workspace, an owner or administrator may need to grant access first.
    3. Enter a name such as `Qwairy` and the server URL:

    ```
    https://mcp.qwairy.co
    ```

    4. Select OAuth authentication, scan the tools, and complete the Qwairy authorization flow.
    5. Create the app. A workspace owner may need to publish it before other members can use it.

    See [OpenAI's custom app guide](https://help.openai.com/en/articles/12584461) for the current plan and workspace controls.
  </Tab>

  <Tab title="Cursor">
    Add Qwairy to `~/.cursor/mcp.json` for a personal, cross-project connection. Use a project's `.cursor/mcp.json` only when the server should be project-scoped.

    ```json theme={null}
    {
      "mcpServers": {
        "qwairy": {
          "url": "https://mcp.qwairy.co"
        }
      }
    }
    ```

    Save the file, restart Cursor, then open **Customize > MCPs** to confirm the server is enabled and complete OAuth. See [Cursor's MCP documentation](https://cursor.com/docs/mcp) for current interface steps.
  </Tab>

  <Tab title="Claude Code">
    Add the remote HTTP server at user scope, then sign in and verify it:

    ```bash theme={null}
    claude mcp add --transport http qwairy --scope user https://mcp.qwairy.co
    claude mcp login qwairy
    claude mcp get qwairy
    ```

    On Claude Code versions without `claude mcp login`, run `/mcp` inside Claude Code to complete OAuth. See [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp) for scope and management commands.
  </Tab>

  <Tab title="VS Code / Copilot">
    1. Open the Command Palette and run **MCP: Add Server**.
    2. Choose an HTTP server and enter:

    ```
    https://mcp.qwairy.co
    ```

    3. Choose **Global** for all workspaces or **Workspace** for the current repository.
    4. Trust the server when prompted and complete Qwairy authorization.

    The equivalent workspace configuration in `.vscode/mcp.json` is:

    ```json theme={null}
    {
      "servers": {
        "qwairy": {
          "type": "http",
          "url": "https://mcp.qwairy.co"
        }
      }
    }
    ```

    See [VS Code's MCP server guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for workspace and user configuration options.
  </Tab>

  <Tab title="Windsurf / Devin Local">
    Devin Local is the default agent for new Windsurf tabs. Add Qwairy at user scope, then sign in and verify it:

    ```bash theme={null}
    devin mcp add -s user qwairy https://mcp.qwairy.co
    devin mcp login qwairy
    devin mcp get qwairy
    ```

    The legacy Cascade agent uses **Devin Settings > Cascade > MCP Servers** or `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "qwairy": {
          "serverUrl": "https://mcp.qwairy.co"
        }
      }
    }
    ```

    <Note>
      Cascade accepts `serverUrl` or `url` for remote HTTP servers. Team policies may require an administrator to enable or allowlist MCP access. See the [Devin Local MCP guide](https://docs.devin.ai/cli/extensibility/mcp/configuration) and [legacy Cascade guide](https://docs.devin.ai/desktop/cascade/mcp).
    </Note>
  </Tab>

  <Tab title="Other Clients">
    Prefer a client's native **Streamable HTTP** transport with OAuth and use the URL:

    ```
    https://mcp.qwairy.co
    ```

    If a client only supports stdio, choose a maintained HTTP bridge that your organization has reviewed. Pin an approved package and version instead of executing an unpinned package at runtime. Bridge configuration and OAuth callback support are client-specific.
  </Tab>
</Tabs>

## Authorize the connection

After adding the server, your client will initiate the OAuth flow:

1. A browser window opens with the Qwairy sign-in page
2. Sign in with your Qwairy account
3. Authorize the connection
4. You're redirected back: the connection is active

<Note>
  Your credentials are never shared with the AI client. Authentication uses OAuth 2.1 with PKCE: only a secure, scoped access token is exchanged. [Learn more about OAuth](/mcp/oauth).
</Note>

## Query your data

Try these example prompts:

```
What brands am I monitoring?
```

```
Show me my GEO performance for the last 30 days
```

```
Who are my top competitors in AI responses?
```

```
Which sources cite my brand most often?
```

```
What are the top content opportunities for my brand right now?
```

```
Compare my brand's sentiment across different AI providers
```

```
Which prompts are driving the most visibility for my competitors?
```

## Troubleshooting

### "Server not found" error

* Use the root endpoint `https://mcp.qwairy.co`; do not append `/mcp`
* Check that your config file is valid JSON
* Restart your AI client after editing the config

### "Authentication failed" error

1. Check that you have a **Starter plan** or higher
2. Ensure you're signing in with the correct Qwairy account
3. Try disconnecting and reconnecting

### "No data returned"

Make sure you have:

* At least one brand with status **"Live"**
* Monitoring enabled with generated responses
* Recent data (within the last 30 days by default)

### Client doesn't support remote MCP?

Prefer a client with native Streamable HTTP and OAuth support. If your organization approves a bridge, pin its version and follow that client's documented OAuth callback procedure.

## Rate limits

The MCP server currently allows **300 requests per minute** and **3,000 requests per day** per access token. HTTP `429` responses expose `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` for the per-minute window; successful responses do not expose quota headers. The JSON error message's retry delay is derived from that same per-minute reset. Apply exponential backoff, and if requests remain limited after the reset, stop automated retries and resume later because the daily cap may be exhausted. These service limits can evolve; treat the documented values as current policy and `429` headers as burst-window guidance, not a complete daily-quota signal.

## Measurement tools and scopes

Tools that read off-AI analytics (Search Console, Bing, referrer traffic, AI revenue, crawler activity) live under the **Measure** category and require the `read:measure` scope. If you connected before this scope existed, disconnect and reconnect to pick it up: scopes are never expanded silently on an already-issued token. See [Measure Tools](/mcp/tools/measure).

## Next steps

<CardGroup>
  <Card title="Tools Reference" icon="wrench" href="/mcp/tools/discovery">
    Learn what each tool does and its parameters
  </Card>

  <Card title="Example Conversations" icon="messages" href="/mcp/examples/getting-started">
    See real-world usage examples
  </Card>

  <Card title="Combine with Other Tools" icon="puzzle-piece" href="/mcp/workflows">
    Connect Qwairy with your SEO, CMS, and project management tools
  </Card>

  <Card title="OAuth Setup" icon="key" href="/mcp/oauth">
    How authentication works under the hood
  </Card>
</CardGroup>


# Qwairy MCP server
Source: https://docs.qwairy.co/mcp/introduction

Connect an MCP-compatible assistant to read authorized Qwairy monitoring data and documentation

The Qwairy MCP server lets an MCP-compatible assistant read the Qwairy data you authorize. You can discover brands, inspect monitored answers, compare competitors and sources, and query connected measurement data from a conversation.

<Note>
  The MCP surface is read-only. Available tools depend on the scopes granted to the connection, the selected brand, its plan, and configured integrations.
</Note>

## Connection

Use this server URL in your MCP client:

```text theme={null}
https://mcp.qwairy.co
```

Qwairy supports OAuth 2.1 with PKCE for compatible clients. Personal Access Tokens are also available for clients that require a bearer token. See [Connect a client](/mcp/getting-started) and [Authentication](/mcp/oauth).

## Requirements

* An active Qwairy Starter plan or higher, including eligible agency plans
* At least one accessible brand with monitoring data
* An MCP-compatible client

Some tools have additional requirements. For example, measurement tools require the `read:measure` scope and the relevant connected integration. Crawler Analytics also follows its product plan gate.

## What you can query

Tool discovery is the authoritative list for the current connection. Qwairy groups tools by the type of evidence they return:

| Area                | Typical tasks                                                               |
| ------------------- | --------------------------------------------------------------------------- |
| Discovery           | List accessible brands, topics, and tags before using their IDs             |
| Performance         | Inspect visibility metrics, trends, providers, topics, and the matrix       |
| Prompts and answers | Read monitored prompts, stored answers, and prompt-level signals            |
| Competitors         | Compare configured competitors, positions, and trends                       |
| Sources             | Inspect cited domains and URLs, source trends, and source profiles          |
| Strategy            | Review actions, content opportunities, perception, and technical status     |
| Insights            | Query shopping, local, social, sponsored, and query fan-out evidence        |
| Measure             | Read connected search, traffic, revenue, crawler, and page-performance data |
| Agency              | Discover and read authorized pitch audits                                   |
| Documentation       | Search Qwairy product and integration documentation                         |

<Warning>
  Metrics with similar names can use different units or denominators across product, API, exports, and MCP tools. Use the definition returned by the specific tool and keep filters unchanged when comparing results.
</Warning>

## Recommended workflow

<Steps>
  <Step title="Discover the scope">
    Call `list_brands`, then list topics or tags when you need a segmented analysis.
  </Step>

  <Step title="Choose one brand">
    Pass its `brandId` to the next tool. A single tool call never combines data across teams.
  </Step>

  <Step title="Set filters explicitly">
    Specify the period, providers, topics, tags, or prompt types required by the decision.
  </Step>

  <Step title="Inspect underlying evidence">
    Move from aggregate metrics to prompts, answers, sources, or connected analytics before drawing a conclusion.
  </Step>
</Steps>

## Next steps

<CardGroup>
  <Card title="Connect a client" icon="plug" href="/mcp/getting-started">
    Configure OAuth or a bearer token in a supported MCP client.
  </Card>

  <Card title="Understand authentication" icon="key" href="/mcp/oauth">
    Review scopes, team isolation, token behavior, and revocation.
  </Card>

  <Card title="Discover data" icon="magnifying-glass" href="/mcp/tools/discovery">
    Resolve the brand, topic, and tag IDs used by other tools.
  </Card>

  <Card title="Read performance" icon="chart-line" href="/mcp/tools/performance">
    Query metric definitions, filters, trends, and breakdowns.
  </Card>

  <Card title="Use measurement tools" icon="chart-mixed" href="/mcp/tools/measure">
    Read connected analytics with their coverage and availability limits.
  </Card>

  <Card title="Follow a workflow" icon="route" href="/mcp/workflows">
    Combine tools without losing scope or evidence between steps.
  </Card>
</CardGroup>


# OAuth Authentication
Source: https://docs.qwairy.co/mcp/oauth

How the Qwairy MCP server authenticates connections using OAuth 2.1 with PKCE.

The Qwairy MCP server uses **OAuth 2.1 with PKCE** for secure authentication. Your credentials are never shared with AI clients: only a secure, scoped access token.

## How it works

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Client as MCP Client
    participant Auth as Qwairy Auth
    participant MCP as Qwairy MCP

    User->>Client: Start conversation
    Client->>Auth: Authorization request (with PKCE)
    Auth->>User: Login prompt
    User->>Auth: Sign in with Qwairy account
    Auth->>Client: Authorization code
    Client->>Auth: Exchange code for token
    Auth->>Client: User-scoped access token
    Client->>MCP: API request with access token
    MCP->>Client: Data response
```

<Note>
  Most MCP clients handle this flow automatically. You just click "Authorize" when prompted: there's no team to pick and no manual token management. The connection is **user-scoped**: it can read every MCP-eligible workspace you can access directly or through inherited parent-team access.
</Note>

## OAuth endpoints

| Endpoint                    | URL                                                            |
| --------------------------- | -------------------------------------------------------------- |
| Discovery                   | `https://mcp.qwairy.co/.well-known/oauth-authorization-server` |
| Dynamic client registration | `https://auth.qwairy.co/register`                              |
| Authorization               | `https://auth.qwairy.co/authorize`                             |
| Token                       | `https://auth.qwairy.co/token`                                 |
| Revocation                  | `https://auth.qwairy.co/revoke`                                |

<Tip>
  Modern MCP clients automatically discover these endpoints from the server URL. You only need to provide `https://mcp.qwairy.co`: the client fetches the OAuth configuration via the discovery endpoint.
</Tip>

## Available scopes

Request only the scopes you need:

| Scope               | Description                                                                                                                                                                               |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read:brands`       | See the list of brands monitored on this account (brand names and primary domains).                                                                                                       |
| `read:visibility`   | See visibility metrics, GEO scores, and trends for monitored brands across AI providers.                                                                                                  |
| `read:competitors`  | See competitors detected in AI answers, their rankings, sentiment, and evolution over time.                                                                                               |
| `read:sources`      | See the third-party domains and URLs that AI providers cite as sources in answers.                                                                                                        |
| `read:prompts`      | See the questions and prompts monitored across AI providers, including their text, status, and tags. `get_prompt_answers` includes response excerpts limited to the first 500 characters. |
| `read:answers`      | See the full text and metadata of AI answers collected for monitored prompts (response text, provider, citations, sentiment).                                                             |
| `read:topics`       | See topic groups, keyword performance, and topic-level breakdowns of brand visibility.                                                                                                    |
| `read:pitch-audits` | List and read completed or in-progress Pitch Audit reports for agency workspaces you can access.                                                                                          |
| `read:measure`      | See off-AI analytics from connected integrations: search performance, AI-referral traffic, configured conversions and value, and retained AI crawler rollups.                             |

<Note>
  If no scopes are specified, all read scopes are granted by default. If any requested scope is unrecognized, the entire authorization request is rejected with `invalid_scope`.
</Note>

<Note>
  `read:measure` and `read:pitch-audits` are newer scopes. Existing OAuth connections must reconnect and re-authorize to gain access to their tools. Scopes are never expanded silently on an already-issued token.
</Note>

## Token lifecycle

The OAuth flow issues a single **user-scoped access token**: the same kind of token as a Personal Access Token (`qw-usr-`). It is long-lived and has no refresh token: there is nothing to rotate, and clients simply reuse the bearer until it is revoked.

| Token                                         | Duration        | Notes                                                                                |
| --------------------------------------------- | --------------- | ------------------------------------------------------------------------------------ |
| Current OAuth or PAT access token (`qw-usr-`) | No fixed expiry | Revoke any time from **Team Management > MCP Server**; re-authorize to get a new one |
| Legacy OAuth access token (`qw-mcp-`)         | 1 hour          | Already-issued legacy connections only                                               |
| Legacy rotating refresh token (`qw-mcpr-`)    | 30 days         | Already-issued legacy connections only; each refresh rotates the token               |
| Authorization Code                            | 5 minutes       | One-time use, PKCE-protected                                                         |

New OAuth connections issue a long-lived `qw-usr-` token without a refresh token. Disconnecting and reconnecting a legacy connection migrates it to this current token flow.

## Personal Access Tokens

For headless clients that cannot run an interactive OAuth flow: automation platforms (n8n, Make), scripts, or custom agents: Qwairy supports **user-scoped Personal Access Tokens (PATs)**. Create and revoke them from **Team Management > MCP Server** in Qwairy.

* A PAT is prefixed `qw-usr-` and is tied to **your user account**, not a single team.
* It can read every MCP-eligible team you can access directly or through inherited parent-team access, so one token can cover multiple workspaces.
* Pass it as a bearer token: `Authorization: Bearer qw-usr-...`.
* Like the OAuth access token, a PAT has no fixed expiry. Revoke it from **Team Management > MCP Server** when it is no longer needed.

<Note>
  PATs are read-only, like all Qwairy MCP access: they never expose write operations.
</Note>

### Choosing a team

Brand-scoped tools take a `brandId`, and Qwairy resolves that brand to exactly one owning team for the call. A response never aggregates brand data across teams. Call `list_brands` first, then pass the `brandId` you want.

User-scoped tokens can include directly accessible teams and sub-teams inherited through a parent-team Owner or Manager role. `list_pitch_audits` is the other cross-workspace discovery tool: it lists only agency workspaces the token may access and accepts an optional `teamId` filter. Detail calls still resolve one audit from one authorized workspace.

## PKCE support

The server requires PKCE with the **S256** method only:

* **S256**: SHA-256 hash of the code verifier

The `plain` method is not supported. Most MCP clients use S256 by default, so no extra configuration is needed.

## Security features

<AccordionGroup>
  <Accordion title="No Password Sharing">
    Your Qwairy password is never shared with any AI client. Authentication happens directly with Qwairy's auth server.
  </Accordion>

  <Accordion title="Scoped Access">
    Tokens are scoped to specific data types. An MCP client can only access what you've authorized.
  </Accordion>

  <Accordion title="Team Isolation">
    Both OAuth connections and Personal Access Tokens are user-scoped (`qw-usr-`): they span MCP-eligible teams you can access directly or through inherited parent Owner or Manager access. Each brand-scoped call still resolves the requested `brandId` to exactly one owning team, so one response never mixes brand data across teams.
  </Accordion>

  <Accordion title="Short-Lived Authorization Code">
    The authorization code is single-use and expires after 5 minutes, so the window to exchange it for a token is tight. The issued access token itself is revocable at any time (see below).
  </Accordion>

  <Accordion title="Revocation">
    You can revoke access at any time from your Qwairy account settings.
  </Accordion>
</AccordionGroup>

## Manual token exchange

For developers building custom MCP clients, register the public client first and reuse the returned `client_id` throughout the authorization-code exchange.

### 1. Register the client

The redirect URI registered here must match the redirect URI used in both later requests.

```bash theme={null}
curl --request POST https://auth.qwairy.co/register \
  --header 'Content-Type: application/json' \
  --data '{
    "client_name": "My Qwairy MCP client",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "grant_types": ["authorization_code"],
    "response_types": ["code"]
  }'
```

The response includes the registered public client ID:

```json theme={null}
{
  "client_id": "mcp-client-0123456789abcdef0123456789abcdef",
  "client_name": "My Qwairy MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}
```

### 2. Start authorization

Generate an RFC 7636 verifier and its S256 challenge, then open this URL in the user's browser. Replace `REGISTERED_CLIENT_ID` with the `client_id` returned above.

```bash theme={null}
GET https://auth.qwairy.co/authorize
  ?response_type=code
  &client_id=REGISTERED_CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback
  &scope=read%3Abrands%20read%3Avisibility
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256
```

The callback contains `code` and `state`. Verify `state` before exchanging the code.

### 3. Exchange the code

```bash theme={null}
curl --request POST https://auth.qwairy.co/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTH_CODE_FROM_CALLBACK' \
  --data-urlencode 'client_id=REGISTERED_CLIENT_ID' \
  --data-urlencode 'redirect_uri=http://127.0.0.1:8765/callback' \
  --data-urlencode 'code_verifier=ORIGINAL_CODE_VERIFIER'
```

**Response:**

```json theme={null}
{
  "access_token": "qw-usr-abc123...",
  "token_type": "Bearer",
  "scope": "read:brands read:visibility"
}
```

The access token is a long-lived, user-scoped token (`qw-usr-`). There is no `refresh_token` or `expires_in`: reuse the bearer until you revoke it.

### 4. Reuse or revoke

The token does not expire and has no refresh step: reuse the bearer for subsequent requests. To rotate it, revoke the old one and run the authorization flow again:

```bash theme={null}
POST https://auth.qwairy.co/revoke
Content-Type: application/x-www-form-urlencoded

token=qw-usr-abc123...
```

## Troubleshooting

### "Invalid or expired token"

The token was revoked: user-scoped tokens do not expire on their own. Disconnect and reconnect to authorize a new one.

### "Insufficient scope"

The tool you're trying to use requires a scope that wasn't granted. Reconnect and authorize all requested scopes.

### "No eligible team"

Your account isn't a member of any team on an MCP-eligible plan (Starter and above), or the subscription has lapsed. Authorization is denied until at least one workspace is eligible.


# Competitor tools
Source: https://docs.qwairy.co/mcp/tools/competitors

Tools to analyze competitors mentioned in AI responses and track their evolution.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative global evidence-filter contract. Those shared parameters apply in addition to the tool-specific parameters shown below.
</Note>

## get\_competitors

Rank competitors by mentions in an evidence scope. The tool returns all-time results when no window is supplied; use a rolling period or inclusive custom dates, optionally combined with one topic and/or tag.

### Parameters

| Parameter           | Type              | Required | Description                                                                  |
| ------------------- | ----------------- | -------- | ---------------------------------------------------------------------------- |
| `brandId`           | string            | Yes      | The brand ID                                                                 |
| `relationship`      | string            | No       | `SELF`, `DIRECT`, `INDIRECT`, `ECOSYSTEM`, `COMPLEMENTARY`, or `SELF_DIRECT` |
| `period`            | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"` with dates; omit for all-time  |
| `startDate`         | string            | No       | Inclusive start date (`YYYY-MM-DD`); provide with `endDate`                  |
| `endDate`           | string            | No       | Inclusive end date (`YYYY-MM-DD`); provide with `startDate`                  |
| `provider`          | string            | No       | Legacy single-provider or model alias                                        |
| `providers`         | string\[]         | No       | AI provider or model IDs; values are ORed                                    |
| `topic` / `topicId` | string            | No       | Single-topic aliases using a UUID returned by `list_topics`                  |
| `topicIds`          | string\[]         | No       | Topic UUIDs; values are ORed                                                 |
| `tag` / `tagId`     | string            | No       | Single-tag aliases using a UUID returned by `list_tags`                      |
| `tagIds`            | string\[]         | No       | Tag UUIDs; values are ORed                                                   |
| `funnelStages`      | string\[]         | No       | Any of `TOFU`, `MOFU`, and `BOFU`; values are ORed                           |
| `limit`             | integer           | No       | Max competitors to return (default: 20, max: 100)                            |

### Relationship types

| Type            | Description                                          |
| --------------- | ---------------------------------------------------- |
| `SELF`          | Your own brand                                       |
| `DIRECT`        | Direct competitors (same product category)           |
| `INDIRECT`      | Indirect competitors (adjacent solutions)            |
| `ECOSYSTEM`     | Ecosystem players (complementary products)           |
| `COMPLEMENTARY` | Complementary products or services                   |
| `SELF_DIRECT`   | Your brand and its direct competitors in one ranking |

### Returns

| Field                                             | Type           | Description                                                            |
| ------------------------------------------------- | -------------- | ---------------------------------------------------------------------- |
| `brandName`                                       | string         | Monitored brand name                                                   |
| `appliedFilters`                                  | object         | Resolved evidence window and taxonomy filters used for the ranking     |
| `competitors[].id`                                | string         | Competitor domain ID                                                   |
| `competitors[].name`                              | string         | Competitor name                                                        |
| `competitors[].domain`                            | string or null | Competitor's domain                                                    |
| `competitors[].relationship`                      | string         | Relationship type                                                      |
| `competitors[].mentions`                          | number         | Mention count inside the requested evidence scope                      |
| `competitors[].uniqueAnswers` / `uniqueQuestions` | number         | Distinct answers and monitored questions contributing mentions         |
| `competitors[].shareOfVoice`                      | number or null | Share of SELF + DIRECT mentions in scope; null for other relationships |
| `competitors[].shareOfResponses` / `mentionRate`  | number or null | Response-level visibility rates when available                         |
| `competitors[].avgPosition`                       | number or null | Average position in responses inside the requested scope               |
| `competitors[].avgSentiment`                      | number or null | Average sentiment (0-100)                                              |
| `competitors[].providers`                         | string\[]      | Providers contributing evidence for the competitor                     |

### Example output

```markdown theme={null}
## Competitors for Acme Corp

| Rank | Name | Relationship | Mentions | Share of Voice | Avg Position | Sentiment | Competitor Domain ID |
|------|------|--------------|----------|----------------|--------------|-----------|----------------------|
| 1 | CompetitorA | DIRECT | 892 | 34.26% | 2.3 | 75/100 | 11111111-1111-4111-8111-111111111111 |
| 2 | CompetitorB | DIRECT | 654 | 25.11% | 3.1 | 72/100 | 22222222-2222-4222-8222-222222222222 |
| 3 | Acme Corp | SELF | 612 | 23.50% | 2.8 | 78/100 | 33333333-3333-4333-8333-333333333333 |
| 4 | CompetitorC | DIRECT | 445 | 17.09% | 4.2 | 68/100 | 44444444-4444-4444-8444-444444444444 |
| 5 | ToolX | INDIRECT | 234 | - | 5.1 | 71/100 | 55555555-5555-4555-8555-555555555555 |
```

### Example prompts

```
Who are my competitors in AI responses?
```

```
Show me only direct competitors
```

```
Which brands appear alongside mine most often?
```

```
Rank my brand and direct competitors for this tag over the last 30 days
```

### OAuth scope

Requires: `read:competitors`

***

## get\_competitor\_evolution

Track how a competitor's presence changes over time: mentions, position, and sentiment trends.

### Parameters

| Parameter      | Type              | Required | Description                                       |
| -------------- | ----------------- | -------- | ------------------------------------------------- |
| `brandId`      | string            | Yes      | The brand ID                                      |
| `competitorId` | string            | Yes      | The competitor domain ID (from `get_competitors`) |
| `period`       | integer or string | No       | Global evidence window; defaults to 30 days       |
| `groupBy`      | string            | No       | `day` (default) or `week`                         |

### Returns

Array of daily data points:

| Field          | Type   | Description          |
| -------------- | ------ | -------------------- |
| `date`         | string | Date (YYYY-MM-DD)    |
| `mentions`     | number | Mentions on that day |
| `avgPosition`  | number | Average position     |
| `avgSentiment` | number | Average sentiment    |

### Example output

```markdown theme={null}
## CompetitorA - Evolution Over Time

Relationship: DIRECT

| Date | Mentions | Avg Position | Sentiment |
|------|----------|--------------|-----------|
| 2025-01-21 | 28 | 2.5 | 73/100 |
| 2025-01-22 | 31 | 2.3 | 74/100 |
| 2025-01-23 | 35 | 2.1 | 76/100 |
| 2025-01-24 | 29 | 2.4 | 75/100 |
| 2025-01-25 | 38 | 2.0 | 77/100 |
```

### Example prompts

```
How has CompetitorA trended over the last month?
```

```
Is CompetitorB gaining or losing visibility?
```

```
Show me the evolution of my own brand mentions
```

<Tip>
  Use `get_competitors` first to find the `competitorId` you want to track.
</Tip>

### OAuth scope

Requires: `read:competitors`

***

## get\_competitor\_comparison

Head-to-head comparison of the brand against its top direct competitors: your own stats, your market rank, the top competitors' stats, a per-competitor win/loss summary on mention count, and the biggest perceived threat.

### Parameters

| Parameter       | Type              | Required | Description                                           |
| --------------- | ----------------- | -------- | ----------------------------------------------------- |
| `brandId`       | string            | Yes      | The brand ID from `list_brands`                       |
| `period`        | integer or string | No       | Global evidence window; defaults to 30 days           |
| `competitorIds` | string\[]         | No       | Restrict the comparison to 1-10 Competitor Domain IDs |

### Returns

| Field                    | Description                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `period` / `periodLabel` | The analyzed window                                                                                                               |
| `yourStats`              | Your brand: `name`, `mentionCount`, `avgSentiment`, `avgPosition` (null if not mentioned in the period)                           |
| `marketRank`             | Your rank across SELF + DIRECT brands by mention count                                                                            |
| `totalCompetitors`       | Number of direct competitors found                                                                                                |
| `topCompetitors[]`       | Per competitor: `name`, `domain`, `mentionCount`, `avgSentiment`, `avgPosition`                                                   |
| `headToHead[]`           | Top 5 matchups: `competitor`, `yourMentions`, `theirMentions`, `winner` (you/them/tie), plus your vs their sentiment and position |
| `insights`               | `winsAgainstTop5`, `lossesAgainstTop5`, `biggestThreat`                                                                           |

### Example prompts

```
How do I compare to my top competitors right now?
```

```
Which competitors am I beating, and which are beating me?
```

### OAuth scope

Requires: `read:competitors`


# Deep-dive tools
Source: https://docs.qwairy.co/mcp/tools/deep-dive

Tools for detailed analysis: on-page presence, source profiles, competitor positioning, and the GEO visibility matrix.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## get\_page\_presence

Get on-page presence: which pages of the brand's website are cited by AI, with citation counts, unique questions, and optimization status.

### Parameters

| Parameter | Type   | Required | Description                                                     |
| --------- | ------ | -------- | --------------------------------------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands`                                 |
| `limit`   | number | No       | Max pages to return (default: 50)                               |
| `status`  | string | No       | Filter: `WORKING`, `NEEDS_ATTENTION`, `NOT_CITED`, `DISCOVERED` |

### Page status

| Status            | Meaning                          |
| ----------------- | -------------------------------- |
| `WORKING`         | In sitemap + 3 or more citations |
| `NEEDS_ATTENTION` | In sitemap + 1-2 citations       |
| `NOT_CITED`       | In sitemap + 0 citations         |
| `DISCOVERED`      | Not in sitemap but cited by AI   |

### Returns

| Field     | Description                                                                             |
| --------- | --------------------------------------------------------------------------------------- |
| `stats`   | Total pages, cited count, not cited count, discovered count                             |
| `pages[]` | Pages with path, URL, status, citation count, unique questions, avg position, providers |

### OAuth scope

Requires: `read:sources`

***

## get\_source\_profile

Get a deep-dive on a source domain: Qwairy Source Authority, citation statistics, top cited URLs, co-cited competitors, and backlink availability.

### Parameters

| Parameter        | Type              | Required | Description                                      |
| ---------------- | ----------------- | -------- | ------------------------------------------------ |
| `brandId`        | string            | Yes      | The brand ID from `list_brands`                  |
| `sourceDomainId` | string            | Yes      | The source domain ID (from `get_source_domains`) |
| `period`         | integer or string | No       | Global evidence window; defaults to 30 days      |
| `limit`          | number            | No       | Max URLs to return (default: 10)                 |

### Returns

| Field                  | Description                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `source`               | Domain, name, type, relationship (SELF/DIRECT/third-party), and `aiSourceAuthorityScore` (0-100 or `null`) |
| `stats`                | Total mentions, unique questions/answers, avg position, providers                                          |
| `topUrls[]`            | Most cited URLs with mention counts                                                                        |
| `coCitedCompetitors[]` | Competitors appearing in same answers as this source                                                       |
| `backlink`             | Availability, best price, number of platforms                                                              |

### OAuth scope

Requires: `read:sources`

***

## get\_competitor\_position

Get a deep-dive on a competitor: market coverage, share of voice, average position/sentiment, top citing sources, and shopping/local overlap.

### Parameters

| Parameter      | Type              | Required | Description                                                        |
| -------------- | ----------------- | -------- | ------------------------------------------------------------------ |
| `brandId`      | string            | Yes      | The brand ID from `list_brands`                                    |
| `competitorId` | string            | Yes      | Competitor ID, domain (e.g. "adidas.com"), or name (e.g. "Adidas") |
| `period`       | integer or string | No       | Global evidence window; defaults to 30 days                        |

### Returns

| Field                      | Description                                            |
| -------------------------- | ------------------------------------------------------ |
| `stats.coveragePercentage` | % of monitored questions where this competitor appears |
| `stats.shareOfVoice`       | Competitor's share of all SELF+DIRECT mentions         |
| `stats.avgPosition`        | Average position in AI responses                       |
| `stats.avgSentiment`       | Average sentiment score                                |
| `stats.providers[]`        | AI providers mentioning this competitor                |
| `topSources[]`             | Domains most frequently citing this competitor         |
| `shoppingOverlap`          | Number of shopping products linked to this competitor  |
| `localOverlap`             | Number of local businesses linked to this competitor   |

### OAuth scope

Requires: `read:competitors`

***

## get\_matrix

Get the GEO visibility matrix: rows (topics, tags, prompts, or funnel stages) crossed with columns (AI providers), showing composite scores, sub-scores, rankings, citations, and top competitors per cell.

### Parameters

| Parameter     | Type              | Required | Description                                                  |
| ------------- | ----------------- | -------- | ------------------------------------------------------------ |
| `brandId`     | string            | Yes      | The brand ID from `list_brands`                              |
| `granularity` | string            | No       | Group by: `topics` (default), `tags`, `prompts`, or `funnel` |
| `period`      | integer or string | No       | Global evidence window; defaults to 30 days                  |
| `limit`       | number            | No       | Max rows to return (default: 20)                             |

### Granularity options

| Value     | Groups rows by                 |
| --------- | ------------------------------ |
| `topics`  | Keywords/topics (default)      |
| `tags`    | Configured prompt tags         |
| `prompts` | Individual monitored questions |
| `funnel`  | Funnel stages (TOFU/MOFU/BOFU) |

### Returns

| Field            | Description                                                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `providers[]`    | List of AI providers (columns)                                                                                                                                                                    |
| `rows[]`         | Matrix rows, each with `mentionRate`, `coverage` (`{count, total, percentage}`), and cells per provider                                                                                           |
| `rows[].cells[]` | Per-cell: `score` (composite 0-100), `subScores` (mentionRate, shareOfVoice, citationRate, sentiment), `ranking` (rank/total per metric), `citations`, `position`, `topCompetitor` (name or null) |

<Tip>
  The matrix is powerful for identifying **which topics underperform on which providers**. Look for cells with low scores or poor rankings where competitors have high mention rates.
</Tip>

### OAuth scope

Requires: `read:visibility`


# Discovery tools
Source: https://docs.qwairy.co/mcp/tools/discovery

Tools to discover monitored brands and their configured topics and tags in Qwairy.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## list\_brands

List all monitored brands for your account. **Use this first** to get brand IDs needed for other tools.

### Parameters

This tool takes no parameters.

### Returns

| Field                          | Type   | Description                                                   |
| ------------------------------ | ------ | ------------------------------------------------------------- |
| `id`                           | string | Unique brand identifier                                       |
| `name`                         | string | Brand display name                                            |
| `domain`                       | string | Brand's primary domain                                        |
| `team`                         | object | Workspace ID and name                                         |
| `countryCode` / `languageCode` | string | Configured market and language                                |
| `monitoring`                   | object | Enabled state, frequency, model codes, and last analysis date |
| `counts`                       | object | Configured prompt, topic, and tag counts                      |

### Example output

```markdown theme={null}
## Your monitored brands

1. **Acme Corp** (ID: abc-123-def)
   Domain: acme.example
   Workspace: Agency workspace (ID: team-123)
   Market: en / US
   Monitoring: enabled, weekly
   Models: openai-chatgpt-core, google-gemini-core
   Last analysis: 2026-07-19T12:00:00.000Z
   Configuration: 156 prompts, 12 topics, 8 tags
```

### Example prompts

```
What brands am I monitoring?
```

```
List my Qwairy brands
```

```
Show me my monitored brands
```

### OAuth scope

Requires: `read:brands`

***

## list\_topics

List every topic configured for a brand, including topics without recent answers. Use this tool to discover stable topic IDs before applying topic filters elsewhere.

### Parameters

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands`     |
| `search`  | string | No       | Case-insensitive topic label search |
| `limit`   | number | No       | Max topics (default: 50, max: 100)  |
| `offset`  | number | No       | Pagination offset (default: 0)      |

### Returns

| Field          | Type   | Description                                    |
| -------------- | ------ | ---------------------------------------------- |
| `id`           | string | Topic ID used by topic filters                 |
| `text`         | string | Topic label                                    |
| `promptsCount` | number | Active monitored prompts assigned to the topic |

### OAuth scope

Requires: `read:topics`

***

## list\_tags

List every prompt tag configured for a brand. Use this tool to discover stable tag IDs before applying tag filters elsewhere.

### Parameters

| Parameter | Type   | Required | Description                       |
| --------- | ------ | -------- | --------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands`   |
| `search`  | string | No       | Case-insensitive tag label search |
| `limit`   | number | No       | Max tags (default: 50, max: 100)  |
| `offset`  | number | No       | Pagination offset (default: 0)    |

### Returns

| Field          | Type   | Description                               |
| -------------- | ------ | ----------------------------------------- |
| `id`           | string | Tag ID used by tag filters                |
| `name`         | string | Tag label                                 |
| `color`        | string | Configured color, or `null`               |
| `promptsCount` | number | Active monitored prompts carrying the tag |

### OAuth scope

Requires: `read:topics`

***

## get\_overview

Get a quick cockpit overview of a brand: key counts, performance scores with trend vs previous period, and last monitoring date.

**Use this as the second call** after `list_brands` to get a snapshot before diving into specifics.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |

### Returns

| Field                  | Description                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `counts`               | questions, answers, competitors, sources, selfMentions, socialCitations, shoppingInsights, localBusinesses |
| `scores`               | mentionRate, sourceRate, shareOfVoice, sentiment (current period)                                          |
| `previousPeriodScores` | Same metrics for previous period (trend comparison)                                                        |
| `lastMonitoringDate`   | Most recent AI response date                                                                               |

### OAuth scope

Requires: `read:brands`


# Documentation tool
Source: https://docs.qwairy.co/mcp/tools/documentation

Search Qwairy product documentation, guides, best practices, and GEO strategies directly from the MCP.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## search\_documentation

Search the Qwairy knowledge base: product documentation, GEO guides, best practices, and strategy playbooks: without leaving your AI assistant.

This tool connects to [docs.qwairy.co](https://docs.qwairy.co) and returns relevant documentation excerpts. If the documentation service is unavailable, it falls back to a local glossary and FAQ search.

### Parameters

| Parameter | Type   | Required | Description                                                               |
| --------- | ------ | -------- | ------------------------------------------------------------------------- |
| `query`   | string | Yes      | The search query (e.g., "How to improve visibility score", "What is GEO") |

### Returns

**When documentation is available (Mintlify):**

| Field     | Type   | Description                     |
| --------- | ------ | ------------------------------- |
| `source`  | string | Always `"mintlify"`             |
| `results` | array  | Matching documentation excerpts |

**When falling back to local data:**

| Field           | Type   | Description                              |
| --------------- | ------ | ---------------------------------------- |
| `source`        | string | Always `"local_fallback"`                |
| `glossaryTerms` | array  | Matching glossary terms with definitions |
| `faqItems`      | array  | Matching FAQ questions and answers       |

### Example output

```markdown theme={null}
## GEO (Generative Engine Optimization)

GEO is the practice of optimizing your brand's presence in AI-generated
responses. Unlike traditional SEO which focuses on search engine rankings,
GEO targets how AI models like ChatGPT, Claude, and Gemini reference
and recommend your brand.

Metric definitions depend on the surface. In the product dashboard:
- **Mention Rate**: SELF-mentioned answers divided by answers with a SELF or DIRECT mention
- **Citation Rate**: SELF-citing answers divided by answers with a SELF or DIRECT citation
- **Share of Voice**: SELF mention occurrences divided by SELF plus DIRECT occurrences
- **Coverage**: distinct answered prompts with a SELF mention divided by distinct answered prompts

---

## Improving your visibility score

1. Define a stable prompt, provider, and date scope
2. Inspect the stored answers and citations behind an observed gap
3. Check public access configuration against your intended crawler policy
4. Test one relevant content or distribution hypothesis and retain the baseline
```

### Example prompts

```
What is GEO and how does it work?
```

```
How do I improve my visibility score?
```

```
What are the best practices for AI brand optimization?
```

```
Explain the difference between mention rate and source rate
```

### OAuth scope

No specific scope required: documentation is publicly accessible.

### Use cases

* **Onboarding**: New users can ask the AI assistant to explain Qwairy concepts
* **Strategy guidance**: Get GEO best practices while analyzing your data
* **Feature discovery**: Learn about Qwairy features you haven't tried yet
* **Terminology**: Quickly understand metrics, scores, and report fields


# Filter compatibility
Source: https://docs.qwairy.co/mcp/tools/filters

Canonical filter contract and tool-by-tool compatibility for all Qwairy MCP tools.

This page documents filter behavior across the customer MCP. Live tool discovery (`tools/list`) remains authoritative for the current tool inventory and input schemas.

## Global evidence filters

The following parameters are available on every tool listed in the **Global evidence tools** section below.

| Parameter           | Type              | Description                                                                  |
| ------------------- | ----------------- | ---------------------------------------------------------------------------- |
| `period`            | integer or string | Rolling days (1-3650), `"all"`, or `"custom"` with `startDate` and `endDate` |
| `startDate`         | string            | Inclusive UTC start date in `YYYY-MM-DD` format                              |
| `endDate`           | string            | Inclusive UTC end date in `YYYY-MM-DD` format                                |
| `providers`         | string\[]         | AI provider or model IDs; values are ORed                                    |
| `provider`          | string            | Legacy single-provider alias                                                 |
| `topicIds`          | string\[]         | Topic UUIDs returned by `list_topics`; values are ORed                       |
| `topic` / `topicId` | string            | Legacy single-topic aliases                                                  |
| `tagIds`            | string\[]         | Tag UUIDs returned by `list_tags`; values are ORed                           |
| `tag` / `tagId`     | string            | Legacy single-tag aliases                                                    |
| `funnelStages`      | string\[]         | Any of `TOFU`, `MOFU`, and `BOFU`; values are ORed                           |

Values inside one array are ORed. Different dimensions are ANDed. For example, two providers plus one topic and one tag means “either provider, inside this topic, and carrying this tag.”

Custom dates must be provided as a complete pair. Both endpoints are inclusive UTC calendar days. Invalid dates, UUIDs, provider values, funnel stages, incomplete ranges, and unsupported periods return `INVALID_PARAMETER`.

Most evidence tools default to 30 days. `get_competitors` intentionally preserves its established all-time result when no window is supplied. Pass `period: 30` when you want the same explicit 30-day scope used by most dashboard views.

When a tool returns `appliedFilters`, that object echoes the resolved period, dates, providers, topics, tags, and funnel stages used for the result.

## Global evidence tools

The following tools support the complete global evidence contract above:

* `get_brand_performance`
* `get_competitors`
* `get_competitor_evolution`
* `get_prompts`
* `get_prompt_answers`
* `get_answers`
* `get_source_domains`
* `get_source_urls`
* `get_source_trends`
* `get_topics`
* `get_visibility_trend`
* `get_sentiment_trend`
* `get_provider_breakdown`
* `get_keyword_triggers`
* `get_content_opportunities`
* `get_competitor_comparison`
* `get_prompt_signals`
* `get_overview`
* `get_shopping_insights`
* `get_social_insights`
* `get_local_insights`
* `get_query_fan_out`
* `get_page_presence`
* `get_source_profile`
* `get_competitor_position`
* `get_matrix`
* `get_sponsored_content`
* `get_backlink_opportunities`

Tool-specific selectors such as `relationship`, `competitorId`, `domain`, `type`, `isSelf`, `status`, `promptId`, `granularity`, `groupBy`, `limit`, and `offset` can be combined with the global filters when advertised by that tool.

## Action Center filters

`get_actions` uses the dashboard Action Center vocabulary:

| Parameter                                | Type      | Description                                          |
| ---------------------------------------- | --------- | ---------------------------------------------------- |
| `period`                                 | string    | `"1"`, `"7"`, `"14"`, `"30"`, `"all"`, or `"custom"` |
| `periodStart` / `periodEnd`              | string    | Inclusive custom range used with `period: "custom"`  |
| `providers`                              | string\[] | Evidence provider IDs                                |
| `topicIds`                               | string\[] | Topic UUIDs                                          |
| `tagIds`                                 | string\[] | Tag UUIDs                                            |
| `funnelStages`                           | string\[] | `TOFU`, `MOFU`, or `BOFU`                            |
| `actionId`, `status`, `type`, `category` | string    | Action-specific selectors                            |
| `limit`                                  | integer   | Max actions to return (default: 25, max: 100)        |

## Measure date filters

The following tools support `period`, inclusive `startDate`/`endDate`, and legacy `days`:

* `get_ai_revenue`
* `get_search_console_metrics`
* `get_bing_metrics`
* `get_referrer_analytics`

Use either `days` or `period`, not both. Numeric `period` accepts 1-3650; legacy `days` accepts 1-365. For the four connected-provider tools above, `"all"` maps to a 16-month lookback. Rolling and `"all"` windows end on the previous UTC day; custom dates use the exact inclusive range supplied.

`get_page_performance` uses the same date vocabulary but page-level crawler evidence retains at most 30 analytic days. Numeric periods and custom ranges longer than 30 days return `INVALID_PARAMETER`; `period: "all"` means all retained page history.

## Tool-specific filters and selectors

The following tools do not consume the global answer-evidence filters:

| Tool                     | Supported filters or selectors                                        |
| ------------------------ | --------------------------------------------------------------------- |
| `list_brands`            | None                                                                  |
| `list_pitch_audits`      | `teamId`, `status`, `limit`, `offset`                                 |
| `get_pitch_audit`        | `auditId`, `subjectId`, `includeAnswers`, `includeCoCompetitorScores` |
| `list_topics`            | `search`, `limit`, `offset`                                           |
| `list_tags`              | `search`, `limit`, `offset`                                           |
| `get_answer_details`     | `brandId`, `answerId`                                                 |
| `get_brand_perception`   | Latest completed snapshot for `brandId`                               |
| `get_technical_status`   | Current technical state for `brandId`                                 |
| `get_perception_history` | `limit`                                                               |
| `get_crawler_activity`   | Current retained crawler lifecycle for `brandId`                      |
| `get_site_diagnostics`   | `limit`                                                               |
| `search_documentation`   | Public documentation `query`                                          |

Snapshot and detail tools intentionally do not accept evidence filters: they return one selected record or the latest/current state rather than an aggregate over answer evidence.

## Examples

```json theme={null}
{
  "brandId": "brand-uuid",
  "period": 30,
  "providers": ["openai", "anthropic"],
  "topicIds": ["topic-uuid"],
  "tagIds": ["tag-uuid"],
  "funnelStages": ["BOFU"]
}
```

```json theme={null}
{
  "brandId": "brand-uuid",
  "startDate": "2026-08-01",
  "endDate": "2026-08-22",
  "tag": "tag-uuid"
}
```


# Insight tools
Source: https://docs.qwairy.co/mcp/tools/insights

Tools for vertical insights: shopping, social, local businesses, and web search query analysis.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## get\_shopping\_insights

Get e-commerce visibility in AI shopping results: stores that mention your products, competitor products, ratings, and opportunities.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |
| `limit`   | number            | No       | Max items to return (default: 10)           |

### Returns

| Field             | Description                                                                  |
| ----------------- | ---------------------------------------------------------------------------- |
| `summary`         | Total products, stores, mentions, avg rating                                 |
| `topStores[]`     | Stores with product counts, mention counts, self/competitor presence         |
| `topProducts[]`   | Most mentioned products with ratings                                         |
| `opportunities[]` | Stores where competitors appear but brand doesn't (priority: very-high/high) |

### OAuth scope

Requires: `read:visibility`

***

## get\_social\_insights

Get social media and forum citations in AI responses: Reddit, YouTube, HackerNews, Stack Overflow, and more.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |
| `limit`   | number            | No       | Max communities to return (default: 10)     |

### Returns

| Field                          | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `summary.totalSocialCitations` | Total social/forum citations                   |
| `summary.socialShareOfVoice`   | Social citations as % of all citations         |
| `platformDistribution[]`       | Citations per platform (reddit, youtube, etc.) |
| `topCommunities[]`             | Most cited social domains with avg position    |

### OAuth scope

Requires: `read:sources`

***

## get\_local\_insights

Get local business visibility in AI responses: businesses mentioned, categories, ratings, and review counts.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |
| `limit`   | number            | No       | Max businesses to return (default: 10)      |

### Returns

| Field                    | Description                                                      |
| ------------------------ | ---------------------------------------------------------------- |
| `summary`                | Total mentions, unique businesses, avg position, top category    |
| `categoryDistribution[]` | Mentions by business category                                    |
| `topBusinesses[]`        | Most mentioned businesses with ratings, reviews, competitor flag |

### OAuth scope

Requires: `read:visibility`

***

## get\_query\_fan\_out

Get web search queries detected in AI responses: query variations around monitored topics with brand visibility and competitor presence per query.

### Parameters

| Parameter  | Type              | Required | Description                                     |
| ---------- | ----------------- | -------- | ----------------------------------------------- |
| `brandId`  | string            | Yes      | The brand ID from `list_brands`                 |
| `promptId` | string            | No       | Filter to one tracked prompt from `get_prompts` |
| `period`   | integer or string | No       | Global evidence window; defaults to 30 days     |
| `limit`    | number            | No       | Max queries to return (default: 20, max: 500)   |
| `offset`   | number            | No       | Pagination offset (default: 0)                  |

### Returns

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `summary`      | Total queries, unique queries, avg brand presence %                     |
| `topQueries[]` | Most frequent queries with brand presence %, competitor count, priority |

The summary is calculated across the full filtered result set, so `avgBrandPresence` stays stable while paginating.

### Example prompts

```
Show the query fan-out for this monitored prompt
```

```
Which derived queries surface competitors but not my brand?
```

### OAuth scope

Requires: `read:prompts`

***

## get\_sponsored\_content

Detect sponsored content and ads surfaced in AI responses: which advertisers, products, and prompts trigger ads, and whether competitors are among them.

### Parameters

| Parameter | Type              | Required | Description                                                   |
| --------- | ----------------- | -------- | ------------------------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`                               |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days                   |
| `limit`   | number            | No       | Max advertisers / recent ads to return (default: 10, max: 20) |

### Returns

| Field              | Description                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------- |
| `summary`          | `totalAds`, `uniqueAdvertisers`, `uniquePrompts`, `uniqueProducts`                       |
| `topAdvertisers[]` | Per advertiser: `name`, `count`, `products`, `prompts`, `isCompetitor`                   |
| `recentAds[]`      | Per ad: `advertiserName`, `productName`, `description`, `promptText`, `provider`, `date` |

### Example prompts

```
Are competitors running ads in AI responses for my topics?
```

```
Which prompts trigger sponsored content?
```

### OAuth scope

Requires: `read:visibility`


# Measure tools
Source: https://docs.qwairy.co/mcp/tools/measure

Off-AI web analytics from connected integrations: Google Search Console, Bing, analytics revenue and referrers, and AI crawler activity.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative Measure date-filter contract and the coverage of every MCP tool.
</Note>

The Measure tools surface connected web analytics alongside AI visibility data: search performance, classified AI-referral traffic, supported revenue attribution, and observed AI crawler occurrences. They read from integrations you connect inside Qwairy under **Measure**.

<Note>
  **Connection required.** Each tool depends on its corresponding integration: Google Search Console, Bing Webmaster Tools, a supported analytics provider, or Crawler Analytics. After OAuth scope, brand access, and plan or entitlement checks pass, an absent integration is rendered as not connected with empty data so an assistant can explain what to connect. Missing scope, brand access, or product eligibility can return an error instead.
</Note>

<Note>
  All Measure tools require the `read:measure` scope. Existing OAuth connections created before this scope must reconnect to use them.
</Note>

<Note>
  Qwairy MCP returns each tool result as rendered Markdown in `content[0].text`; it does not currently include JSON `structuredContent`. The tables below describe the values rendered for the reader, not a stable JSON wire schema. Do not parse the Markdown as an application data contract.
</Note>

***

## get\_search\_console\_metrics

Google Search Console performance for the brand's site: clicks, impressions, CTR, and average position, broken down by search query or by page.

### Parameters

| Parameter               | Type              | Required | Description                                                     |
| ----------------------- | ----------------- | -------- | --------------------------------------------------------------- |
| `brandId`               | string            | Yes      | The brand ID from `list_brands`                                 |
| `dimension`             | string            | No       | `query` or `page` (default: `query`)                            |
| `period`                | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"`; default: 30 days |
| `startDate` / `endDate` | string            | No       | Inclusive custom range in `YYYY-MM-DD` format                   |
| `days`                  | number            | No       | Legacy 1-365 day alias; do not combine with `period`            |
| `limit`                 | number            | No       | Max rows to return                                              |

### Returns

| Field       | Description                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `connected` | Whether Google Search Console is connected for this brand                                        |
| `dimension` | The dimension used (`query` or `page`)                                                           |
| `dateRange` | `startDate`, `endDate`                                                                           |
| `summary`   | `totalClicks`, `totalImpressions`, `avgCtr` (%), `avgPosition` (impression-weighted), `rowCount` |
| `rows[]`    | Per query/page: `key`, `clicks`, `impressions`, `ctr` (%), `position`                            |

### Example prompts

```
What are my top Search Console queries this month?
```

```
Which pages get the most search impressions but a low CTR?
```

### OAuth scope

Requires: `read:measure`

***

## get\_bing\_metrics

Bing Webmaster Tools search performance for the brand's site, by query or by page. Same shape as `get_search_console_metrics`, sourced from Bing.

### Parameters

| Parameter               | Type              | Required | Description                                                     |
| ----------------------- | ----------------- | -------- | --------------------------------------------------------------- |
| `brandId`               | string            | Yes      | The brand ID from `list_brands`                                 |
| `dimension`             | string            | No       | `query` or `page` (default: `query`)                            |
| `period`                | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"`; default: 30 days |
| `startDate` / `endDate` | string            | No       | Inclusive custom range in `YYYY-MM-DD` format                   |
| `days`                  | number            | No       | Legacy 1-365 day alias; do not combine with `period`            |
| `limit`                 | number            | No       | Max rows to return                                              |

### Returns

| Field       | Description                                                                |
| ----------- | -------------------------------------------------------------------------- |
| `connected` | Whether Bing Webmaster Tools is connected for this brand                   |
| `dimension` | The dimension used (`query` or `page`)                                     |
| `dateRange` | `startDate`, `endDate`                                                     |
| `summary`   | `totalClicks`, `totalImpressions`, `avgCtr` (%), `avgPosition`, `rowCount` |
| `rows[]`    | Per query/page: `key`, `clicks`, `impressions`, `ctr` (%), `position`      |

### OAuth scope

Requires: `read:measure`

***

## get\_referrer\_analytics

Google Analytics sessions classified from recognized AI referrers, compared with total site sessions in the selected scope.

### Parameters

| Parameter               | Type              | Required | Description                                                     |
| ----------------------- | ----------------- | -------- | --------------------------------------------------------------- |
| `brandId`               | string            | Yes      | The brand ID from `list_brands`                                 |
| `period`                | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"`; default: 30 days |
| `startDate` / `endDate` | string            | No       | Inclusive custom range in `YYYY-MM-DD` format                   |
| `days`                  | number            | No       | Legacy 1-365 day alias; do not combine with `period`            |
| `limit`                 | number            | No       | Max sources / landing pages to return                           |

### Returns

| Field               | Description                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `connected`         | Whether Google Analytics is connected for this brand                                           |
| `dateRange`         | `startDate`, `endDate`                                                                         |
| `summary`           | `totalAiSessions`, `totalTrafficSessions`, `aiSharePct`, `avgBounceRate`, `avgSessionDuration` |
| `sources[]`         | Per AI source: `name`, `sessions`, `bounceRate`, `pagesPerSession`, `newUsers`                 |
| `topLandingPages[]` | `path`, `sessions`, `topSource`                                                                |

### Example prompts

```
How much of my traffic is coming from AI assistants?
```

```
Which AI source sends the most engaged visitors?
```

### OAuth scope

Requires: `read:measure`

***

## get\_ai\_revenue

Configured business conversions attributed to AI-referral traffic from a connected analytics provider. The tool keeps provider-native measured revenue separate from estimated value calculated from your fixed-value conversion definitions.

### Parameters

| Parameter               | Type              | Required | Description                                                                                                                                                                |
| ----------------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brandId`               | string            | Yes      | The brand ID from `list_brands`                                                                                                                                            |
| `period`                | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"`; default: 30 days                                                                                                            |
| `startDate` / `endDate` | string            | No       | Inclusive custom range in `YYYY-MM-DD` format                                                                                                                              |
| `days`                  | number            | No       | Legacy 1-365 day alias; do not combine with `period`                                                                                                                       |
| `provider`              | string            | No       | `ga4`, `piwik_pro`, `matomo`, `piano`, or `adobe`; defaults to the most recently configured connected provider, then GA4, Piwik PRO, Matomo, Piano, or Adobe in that order |
| `limit`                 | number            | No       | Max sources and landing pages to render (default: 10; values are clamped to 1-50); conversion definitions are not limited                                                  |

### Returns

| Result section                  | Rendered values                                                                                           |
| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Header                          | Brand name, selected period, and provider                                                                 |
| AI-attributed business outcomes | Conversions, AI sessions, AI conversion rate, site conversion rate, measured revenue, and estimated value |
| Conversion definitions          | Label, source type, AI/site conversions, measured revenue, estimated value, and inclusion in totals       |
| Conversions by AI source        | Source, conversions, sessions, conversion rate, measured revenue, and estimated value                     |
| Top conversion pages            | Path, conversions, measured revenue, estimated value, and top source                                      |
| Warnings                        | Data-quality or aggregation warnings that affect interpretation                                           |

<Note>
  When no supported provider is connected, the rendered result tells the reader to connect one and omits metric sections. When a provider is connected but the selected period has no included conversions, measured revenue, or estimated value, it renders an empty-period notice and zero-valued outcome metrics. These states are not equivalent.
</Note>

<Note>
  For GA4, this MCP tool currently uses Direct session attribution. The dashboard defaults to Combined attribution, which falls back from an AI session source to an AI first-user source. Align the attribution mode before comparing MCP and dashboard totals.
</Note>

<Note>
  Provider-native measured revenue and configured fixed-value estimates are separate. A fixed value is multiplied by AI conversions and uses the configured estimate currency. Measured revenue remains in the provider currency, which is currently rendered without a currency code. Do not add the two values unless you have independently confirmed that their currencies match.
</Note>

### Example prompts

```
How many configured conversions came from AI referrals last month?
```

```
Compare AI and site conversion rates, keeping measured revenue separate from estimated value.
```

### OAuth scope

Requires: `read:measure`

***

## get\_crawler\_activity

Read retained, site-wide lifecycle aggregates for supported observable AI-specific User-Agent identities such as GPTBot, ClaudeBot, PerplexityBot, and OAI-SearchBot. This tool does not expose raw HTTP logs and does not establish why a request occurred, whether content was indexed, or whether a later answer was caused by that occurrence.

<Note>
  `Google-Extended` is a robots-control token, not a separately observable crawler User-Agent. A robots.txt rule for that token does not create an occurrence in Crawler Analytics.
</Note>

### Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands` |

### Returns

| Field                | Description                                                                            |
| -------------------- | -------------------------------------------------------------------------------------- |
| `connected`          | Whether the integration is active, not disabled, and has at least one active API key   |
| `lifecycle`          | Integration state: `PENDING`, `ACTIVE`, `PAUSED`, `DISABLED`, or `null`                |
| `health`             | Current integration health value, or `null` when unavailable                           |
| `crawlers[]`         | Retained per-bot aggregate: `bot`, `firstSeen`, `lastSeen`, and lifetime `occurrences` |
| `totalBotsSeen`      | Number of distinct recognized AI crawlers in the retained aggregate                    |
| `hasObservations`    | Whether at least one recognized crawler observation is retained                        |
| `dataStatus`         | `observed` when crawler observations exist; otherwise `not_measured`                   |
| `rawEventsAvailable` | Always `false`; raw request events are not returned or retained for this tool          |

<Note>
  `firstSeen`, `lastSeen`, and `occurrences` describe retained aggregates, not a queryable raw-log history. Treat them as observation evidence only, without inferring indexing, model training, citations, or causality.
</Note>

### Example prompts

```
Which crawler identities are present in my retained activity aggregate?
```

```
What are ClaudeBot's first and last observed timestamps?
```

### OAuth scope

Requires: `read:measure`

***

## get\_page\_performance

Per-page observed AI crawler occurrences, with lifecycle state and top supported crawler identities for each rendered page. Complements `get_crawler_activity` with a page-level retained-rollup view.

<Info>
  This tool requires an active Business, Enterprise, or Agency Business plan, or an explicit Crawler Analytics feature override, in addition to `read:measure` and access to a live brand.
</Info>

### Parameters

| Parameter               | Type              | Required | Description                                                                                                                                        |
| ----------------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brandId`               | string            | Yes      | The brand ID from `list_brands`                                                                                                                    |
| `period`                | integer or string | No       | Numeric 1-30, `"all"`, or `"custom"`; default: 30 days; numeric periods and `"all"` end on the previous UTC day, and `"all"` means exactly 30 days |
| `startDate` / `endDate` | string            | No       | Inclusive custom range in `YYYY-MM-DD` format, maximum 30 days; an older valid range can have no retained page rollups                             |
| `days`                  | number            | No       | Legacy 1-30 day alias; do not combine with `period`                                                                                                |
| `limit`                 | number            | No       | Max non-neglected pages to return (1-100, default: 20)                                                                                             |

### Returns

| Result section   | Rendered values                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Header           | Brand name, selected period, and daily-rollup scope                                                              |
| Headline         | Observed occurrences, durable page-identity inventory, and supported crawler identities seen                     |
| Coverage caveats | Incomplete ingestion, unverified continuity, or at-least-once delivery warnings when applicable                  |
| Current pages    | Page label, lifecycle state, selected-period occurrences, last observed date, and up to 5 top crawler identities |
| Neglected pages  | Up to 10 page identities, last observed date, and lifetime occurrence count                                      |

<Note>
  The headline's page count is the durable page-identity inventory before `limit`, including neglected identities and identities without an occurrence in the selected period. It is not `pages.length` or the number of pages carrying the displayed occurrences.
</Note>

<Note>
  The current-page query first selects up to `limit` identities by selected-period occurrences, then removes neglected identities, so the rendered table can contain fewer than `limit` rows. The neglected table comes from a separate query ordered by oldest `lastSeenAt` and can be non-empty even when the selected period has no rollup.
</Note>

<Note>
  Crawler Analytics must be active, not disabled, and have an active non-revoked key to be connected. No HTTP events are retained or returned. Sensitive-looking or overlong paths can be pseudonymized; do not reconstruct or link them, and expect no title for those rows.
</Note>

### Example prompts

```
Which pages have the most observed AI crawler occurrences in the retained period?
```

### OAuth scope

Requires: `read:measure`

***

## Related pages

Each tool above mirrors a dashboard page in the **Measure** section:

* [Google Search Console](/documentation/measure/google-search-console): `get_search_console_metrics`
* [Bing Webmaster Tools](/documentation/measure/bing-webmaster): `get_bing_metrics`
* [Referrer Analytics](/documentation/measure/referrer-analytics): `get_referrer_analytics`
* [AI Revenue](/documentation/measure/ai-revenue): `get_ai_revenue`
* [Crawler Analytics](/documentation/measure/crawler-analytics): `get_crawler_activity`
* [Page Performance](/documentation/measure/page-performance): `get_page_performance`


# Performance tools
Source: https://docs.qwairy.co/mcp/tools/performance

Tools to analyze your brand's GEO performance and topic-level metrics.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative global evidence-filter contract. Those shared parameters apply in addition to the tool-specific parameters shown below.
</Note>

## get\_brand\_performance

Get mention rate, source rate, share of voice, and sentiment for one brand in a defined evidence scope.

### Parameters

| Parameter            | Type              | Required | Description                                                                |
| -------------------- | ----------------- | -------- | -------------------------------------------------------------------------- |
| `brandId`            | string            | Yes      | The brand ID from `list_brands`                                            |
| `period`             | integer or string | No       | Rolling days (1-3650), `"all"`, or `"custom"` with dates; default: 30 days |
| `startDate`          | string            | No       | Inclusive start date (`YYYY-MM-DD`); provide with `endDate`                |
| `endDate`            | string            | No       | Inclusive end date (`YYYY-MM-DD`); provide with `startDate`                |
| `provider`           | string            | No       | Filter by AI provider (e.g., "openai", "anthropic", "perplexity")          |
| `providers`          | string\[]         | No       | AI provider or model IDs; values are ORed                                  |
| `topic` / `topicId`  | string            | No       | Single-topic aliases using a UUID returned by `list_topics`                |
| `topicIds`           | string\[]         | No       | Topic UUIDs; values are ORed                                               |
| `tag` / `tagId`      | string            | No       | Single-tag aliases using a UUID returned by `list_tags`                    |
| `tagIds`             | string\[]         | No       | Tag UUIDs; values are ORed                                                 |
| `funnelStages`       | string\[]         | No       | Any of `TOFU`, `MOFU`, and `BOFU`; values are ORed                         |
| `competitorDomainId` | string            | No       | SELF competitor-domain UUID returned by `get_competitors`                  |

<Note>
  If no date parameters are provided, the last 30 days are analyzed. Custom `startDate` and `endDate` take precedence over `period`. Topic and tag can be combined with either window and with a provider filter.
</Note>

### Returns

| Field                 | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `brand`               | Brand ID, name, and domain                                                        |
| `appliedFilters`      | Resolved evidence window and taxonomy filters used for the result                 |
| `period`              | Inclusive analyzed start and end dates                                            |
| `scores.mentionRate`  | SELF-mentioned responses divided by responses mentioning any SELF or DIRECT brand |
| `scores.sourceRate`   | SELF-citing responses divided by responses citing any SELF or DIRECT brand        |
| `scores.shareOfVoice` | SELF mention facts divided by all SELF + DIRECT mention facts                     |
| `scores.sentiment`    | Average SELF sentiment score (0-100)                                              |
| `scoreDetails`        | Numerator and denominator for mention rate, source rate, and share of voice       |
| `methodology`         | Prompt, provider, and response counts inside the filtered evidence scope          |

### Example output

```markdown theme={null}
## GEO Performance: Acme Corp

Period: 2026-07-24 to 2026-08-23

### Key metrics
- Mention Rate: 45% (72 / 160 relevant responses)
- Source Rate: 28% (42 / 150 citable responses)
- Share of Voice: 38% (152 / 400 brand mentions)
- Sentiment: 78/100

### Methodology
- 156 monitored prompts
- 8 AI providers
- 2,340 total responses analyzed
```

### Example prompts

```
What's my GEO score?
```

```
Show me performance for the last 30 days
```

```
How does my brand perform on ChatGPT?
```

```
Compare my performance this month vs last month
```

```
Show my share of voice for this tag over the last 30 days
```

### OAuth scope

Requires: `read:visibility`

***

## get\_visibility\_trend

Get the brand's AI visibility as a time series. Returns daily (or weekly) data points so you can see how mention rate, sentiment, and position move over time, plus a computed trend direction (up / down / stable).

### Parameters

| Parameter | Type              | Required | Description                                    |
| --------- | ----------------- | -------- | ---------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`                |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days    |
| `groupBy` | string            | No       | Group data points by `day` (default) or `week` |

### Returns

| Field                    | Description                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `period` / `periodLabel` | The analyzed window (e.g. `30d`, "Last 30 days")                                                                                                                         |
| `groupBy`                | Whether points are grouped by day or week                                                                                                                                |
| `dataPoints[]`           | Per point: `date`, `totalAnswers`, `brandMentions`, `sourceCitations`, `visibilityRate` (%), `avgSentiment` (0-100, null if none), `avgPosition` (null if not mentioned) |
| `trend`                  | `direction` (up/down/stable), `change`, and a short `description` (first half vs second half of the period)                                                              |
| `summary`                | `totalAnswers`, `totalBrandMentions`, `avgVisibility` (%)                                                                                                                |

### Example prompts

```
How has my visibility changed over the last month?
```

```
Show me my weekly visibility trend
```

### OAuth scope

Requires: `read:visibility`

***

## get\_sentiment\_trend

Get the brand's sentiment as a daily time series, with average position and mention rate per day. Use it to spot when AI perception of the brand shifts.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |

### Returns

| Field                    | Description                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `period` / `periodLabel` | The analyzed window                                                                                                              |
| `dataPoints[]`           | Per day: `date`, `avgSentiment` (0-100, null if none), `avgPosition` (null if not mentioned), `totalAnswers`, `brandMentionRate` |
| `summary`                | `avgSentiment` (0-100), `totalAnswers`, `brandMentionRate` over the whole period                                                 |

### Example prompts

```
Is sentiment toward my brand improving or declining?
```

```
Show me my daily sentiment for the last 90 days
```

### OAuth scope

Requires: `read:topics`

***

## get\_provider\_breakdown

Get visibility metrics broken down by AI provider (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok, etc.). Use it to see which engines the brand is winning or losing on.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |

### Returns

| Field                    | Description                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `period` / `periodLabel` | The analyzed window                                                                                                                                          |
| `providers[]`            | Per provider: `provider`, `totalAnswers`, `brandMentions`, `visibilityRate` (%), `avgSentiment` (0-100, null if none), `avgPosition` (null if not mentioned) |
| `summary`                | `totalProviders`, `totalAnswers`, `totalBrandMentions`, `overallVisibility` (%)                                                                              |

### Example prompts

```
Which AI provider mentions my brand the most?
```

```
Compare my visibility across ChatGPT, Claude, and Perplexity
```

### OAuth scope

Requires: `read:visibility`

***

## get\_keyword\_triggers

Identify which keywords and question types most often trigger brand mentions in AI answers. Returns a trigger rate (% of answers containing that keyword that mention the brand) per keyword and per question type.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |
| `limit`   | number            | No       | Max keywords to return (default: 10)        |

### Returns

| Field                    | Description                                                                   |
| ------------------------ | ----------------------------------------------------------------------------- |
| `period` / `periodLabel` | The analyzed window                                                           |
| `keywords[]`             | Per keyword: `keyword`, `totalAnswers`, `brandMentions`, `triggerRate` (%)    |
| `questionTypes[]`        | Per question type: `type`, `totalAnswers`, `brandMentions`, `triggerRate` (%) |
| `insights`               | `bestPerforming`, `needsImprovement`, `totalKeywords`, `avgTriggerRate`       |

### Example prompts

```
Which keywords trigger my brand most often in AI answers?
```

```
What question types am I weakest on?
```

### OAuth scope

Requires: `read:visibility`

***

## get\_topics

Get performance breakdown by topic/keyword to identify strengths and opportunities.

<Note>
  This performance view returns topics with answers in the selected period. Use `list_topics` for the exhaustive configured topic catalog, including topics without recent answers.
</Note>

### Parameters

| Parameter   | Type              | Required | Description                                 |
| ----------- | ----------------- | -------- | ------------------------------------------- |
| `brandId`   | string            | Yes      | The brand ID                                |
| `period`    | integer or string | No       | Global evidence window; defaults to 30 days |
| `startDate` | string            | No       | Start date (YYYY-MM-DD)                     |
| `endDate`   | string            | No       | End date (YYYY-MM-DD)                       |
| `limit`     | number            | No       | Max topics to return (default: 20)          |

### Returns

| Field          | Type   | Description                         |
| -------------- | ------ | ----------------------------------- |
| `id`           | string | Topic/keyword ID                    |
| `text`         | string | Topic name                          |
| `score`        | number | Overall topic score (0-100)         |
| `mentionRate`  | number | % of responses mentioning brand     |
| `sourceRate`   | number | % of responses citing brand         |
| `shareOfVoice` | number | Brand vs competitors for this topic |
| `promptsCount` | number | Number of prompts for this topic    |

### Example output

```markdown theme={null}
## Performance by topic

| Topic | Score | Mention Rate | Source Rate | Share of Voice | Prompts |
|-------|-------|--------------|-------------|----------------|---------|
| Project Management | 78 | 52% | 34% | 42% | 45 |
| Team Collaboration | 71 | 45% | 28% | 38% | 32 |
| Workflow Automation | 65 | 38% | 22% | 31% | 28 |
| Time Tracking | 58 | 32% | 18% | 25% | 21 |
```

### Example prompts

```
Which topics perform best for my brand?
```

```
Where am I weakest in AI visibility?
```

```
Show me performance by keyword
```

### OAuth scope

Requires: `read:topics`


# Pitch Audit tools
Source: https://docs.qwairy.co/mcp/tools/pitch-audits

Read agency Pitch Audits and co-competitor reports through MCP.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

Pitch Audit tools expose agency pre-sales reports to MCP clients. They are read-only: neither tool creates, confirms, retries, or changes an audit.

## list\_pitch\_audits

List Pitch Audits across the agency workspaces accessible to the connected user.

### Parameters

| Parameter | Type   | Required | Description                                                                      |
| --------- | ------ | -------- | -------------------------------------------------------------------------------- |
| `teamId`  | string | No       | Restrict the list to one accessible agency workspace                             |
| `status`  | string | No       | `PENDING`, `RUNNING`, `RECOVERING`, `AWAITING_PROMPTS`, `COMPLETED`, or `FAILED` |
| `limit`   | number | No       | Max audits, default 20 and maximum 100                                           |
| `offset`  | number | No       | Pagination offset, default 0                                                     |

The result includes the audit ID, prospect, status, scores, prompt count, competitors, selected AI models, timestamps, and workspace.

## get\_pitch\_audit

Read the full report for one Pitch Audit.

### Parameters

| Parameter                   | Type    | Required | Description                                                            |
| --------------------------- | ------- | -------- | ---------------------------------------------------------------------- |
| `auditId`                   | string  | Yes      | Audit ID returned by `list_pitch_audits`                               |
| `subjectId`                 | string  | No       | Competitor report subject. Omit for the original prospect              |
| `includeAnswers`            | boolean | No       | Include full AI answer text. Defaults to false to keep context bounded |
| `includeCoCompetitorScores` | boolean | No       | Add full score summaries to every co-competitor row. Defaults to false |

The report includes the scored competitor and source analyses, detected insights, recommendations, `availableSubjects`, and `coCompetitors`. Full AI answers are added only when `includeAnswers` is true.

To retrieve the complete co-competitor list and compare their scores in one call:

```json theme={null}
{
  "auditId": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
  "includeCoCompetitorScores": true
}
```

Read `audit.coCompetitors[].scores`. Keep the expansion disabled when you only need the lighter co-occurrence metrics.

### Open a co-competitor report

Every `coCompetitors` row returns a `subjectId`. Reuse it with the same audit:

```json theme={null}
{
  "auditId": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
  "subjectId": "rival.example"
}
```

For the original prospect, omit `subjectId` or pass `self`.

### Example prompts

```text theme={null}
List the completed Pitch Audits in my agency workspace.
```

```text theme={null}
Open the latest Pitch Audit, identify its strongest co-competitor, then load that co-competitor's report.
```

### OAuth scope

Both tools require `read:pitch-audits`.

<Note>
  Existing MCP connections must reconnect and authorize the new scope before these tools appear.
</Note>


# Prompt and response tools
Source: https://docs.qwairy.co/mcp/tools/responses

Tools to browse monitored prompts and analyze AI responses in detail.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## get\_prompts

List monitored prompts (queries) for a brand.

### Parameters

| Parameter | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `brandId` | string | Yes      | The brand ID                                  |
| `status`  | string | No       | Filter: `PENDING`, `IN_PROGRESS`, `COMPLETED` |
| `topic`   | string | No       | Filter by topic ID from `list_topics`         |
| `tag`     | string | No       | Filter by tag ID from `list_tags`             |
| `limit`   | number | No       | Max prompts (default: 50)                     |
| `offset`  | number | No       | Pagination offset                             |

### Returns

| Field                | Type    | Description                                    |
| -------------------- | ------- | ---------------------------------------------- |
| `id`                 | string  | Prompt ID                                      |
| `text`               | string  | The prompt text                                |
| `type`               | string  | Funnel stage: `TOFU`, `MOFU`, `BOFU`           |
| `topic`              | object  | Assigned topic ID and label, or `null`         |
| `tags`               | array   | Assigned tag IDs, labels, and colors           |
| `monitoringEnabled`  | boolean | Whether scheduled monitoring is enabled        |
| `frequency`          | string  | Effective monitoring frequency                 |
| `frequencyInherited` | boolean | Whether frequency comes from the brand default |
| `boostCount`         | number  | Responses requested per model and run          |
| `status`             | string  | Processing status                              |
| `lastGenerationDate` | string  | Last time responses were generated             |
| `answersCount`       | number  | Total response count                           |

### Example output

```markdown theme={null}
## Monitored Prompts

Showing 3 of 156 prompts

### 1. "best project management software 2025"
   - ID: prompt-abc-123
   - Status: COMPLETED
   - Type: TOFU
   - Topic: Project Management (ID: topic-123)
   - Tags: Priority (ID: tag-456)
   - Monitoring: enabled, weekly (brand default), boost ×2
   - Answers: 48
   - Last checked: 2025-01-28

### 2. "Acme Corp vs Northstar Work"
   - ID: prompt-def-456
   - Status: COMPLETED
   - Type: BOFU
   - Answers: 32
   - Last checked: 2025-01-28

### 3. "how to improve team productivity"
   - ID: prompt-ghi-789
   - Status: COMPLETED
   - Type: TOFU
   - Answers: 56
   - Last checked: 2025-01-27
```

### Example prompts

```
What prompts am I monitoring?
```

```
Show me my BOFU queries
```

```
List prompts with the "pricing" tag
```

### OAuth scope

Requires: `read:prompts`

***

## get\_prompt\_answers

Get AI responses for a specific prompt across all providers.

### Parameters

| Parameter  | Type   | Required | Description                        |
| ---------- | ------ | -------- | ---------------------------------- |
| `brandId`  | string | Yes      | The brand ID                       |
| `promptId` | string | Yes      | The prompt ID (from `get_prompts`) |
| `provider` | string | No       | Filter by AI provider              |
| `limit`    | number | No       | Max answers (default: 20)          |

### Returns

| Field            | Type    | Description                          |
| ---------------- | ------- | ------------------------------------ |
| `id`             | string  | Answer ID                            |
| `text`           | string  | Response preview (first 500 chars)   |
| `provider`       | string  | AI provider name                     |
| `modelId`        | string  | Specific model used                  |
| `createdAt`      | string  | Response date                        |
| `sentiment`      | number  | Sentiment score (if brand mentioned) |
| `brandMentioned` | boolean | Whether brand appears                |

### Example output

```markdown theme={null}
## AI Responses for: "best project management software 2025"

Found 8 responses

### 1. ChatGPT (GPT-5)
Date: 2025-01-28
Brand mentioned: Yes
Sentiment: 82/100

Preview: "For project management in 2025, several excellent options stand out. **Acme Corp** offers robust features for team collaboration..."

### 2. Perplexity Pro
Date: 2025-01-28
Brand mentioned: No

Preview: "The top project management tools include Northstar Work, TaskHarbor, and Acme Corp. Each offers different collaboration features..."

### 3. Claude (Sonnet)
Date: 2025-01-27
Brand mentioned: Yes
Sentiment: 79/100

Preview: "Based on recent reviews, I'd recommend considering **Acme Corp** for enterprise teams that need..."
```

### Example prompts

```
How do AI providers answer "best project management software"?
```

```
Show me ChatGPT's response to my pricing query
```

```
Compare how different AIs respond to this prompt
```

### OAuth scope

Requires: `read:prompts`

***

## get\_answers

Browse and filter all AI responses for a brand.

### Parameters

| Parameter   | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `brandId`   | string | Yes      | The brand ID              |
| `provider`  | string | No       | Filter by AI provider     |
| `topic`     | string | No       | Filter by topic ID        |
| `tag`       | string | No       | Filter by tag ID          |
| `startDate` | string | No       | Start date (YYYY-MM-DD)   |
| `endDate`   | string | No       | End date (YYYY-MM-DD)     |
| `limit`     | number | No       | Max answers (default: 50) |
| `offset`    | number | No       | Pagination offset         |

### Returns

| Field            | Type    | Description                   |
| ---------------- | ------- | ----------------------------- |
| `id`             | string  | Answer ID                     |
| `promptText`     | string  | The prompt that was asked     |
| `provider`       | string  | AI provider name              |
| `createdAt`      | string  | Response date                 |
| `brandMentioned` | boolean | Whether brand appears         |
| `sourceCited`    | boolean | Whether brand domain is cited |

### Example output

```markdown theme={null}
## AI responses

Showing 10 of 2,340 responses

| Date | Provider | Prompt | Brand | Source |
|------|----------|--------|-------|--------|
| 2025-01-28 | ChatGPT | best project management so... | Yes | Yes |
| 2025-01-28 | Perplexity | top collaboration tools | No | No |
| 2025-01-28 | Claude | Acme Corp review | Yes | Yes |
| 2025-01-27 | Gemini | workflow automation soft... | Yes | No |
```

### Example prompts

```
Show me responses from this week
```

```
Find responses where my brand was mentioned
```

```
List Perplexity responses from January
```

### OAuth scope

Requires: `read:answers`

***

## get\_answer\_details

Get full details of a specific AI response including text, competitors, and sources.

### Parameters

| Parameter  | Type   | Required | Description                      |
| ---------- | ------ | -------- | -------------------------------- |
| `brandId`  | string | Yes      | The brand ID                     |
| `answerId` | string | Yes      | The answer ID (from other tools) |

### Returns

| Section     | Description                                        |
| ----------- | -------------------------------------------------- |
| Response    | Full text, provider, model, date                   |
| Prompt      | Original prompt text and type                      |
| Competitors | All brands mentioned with position and sentiment   |
| Sources     | All URLs cited with domain and position            |
| Enrichment  | AI-extracted topic, keywords, summary, answer type |

### Example output

```markdown theme={null}
## AI response details

**Prompt:** "best project management software 2025"
**Provider:** ChatGPT (GPT-5)
**Date:** 2025-01-28

### Response
For project management in 2025, several options stand out. **Acme Corp** offers team collaboration features including real-time editing, Gantt charts, and automated workflows. Other contenders in this synthetic sample include Northstar Work for visual project tracking and TaskHarbor for task management...

### Analysis
- Topic: Project Management Software
- Type: Comparison
- Keywords: project management, collaboration, Gantt charts, workflows

**Summary:** Comparison of project management tools highlighting Acme Corp's collaboration features.

### Competitors mentioned
1. **Northstar Work** #1 - DIRECT (sentiment: 78/100)
2. **Acme Corp** #2 - SELF (sentiment: 82/100)
3. **TaskHarbor** #3 - DIRECT (sentiment: 75/100)

### Sources cited
1. reviews.example (#1)
   https://reviews.example/project-management
2. acme.example [YOUR SITE] (#2)
   https://www.acme.example/features
3. software-guide.example (#3)
   https://software-guide.example/project-management
```

### Example prompts

```
Show me the full details of that response
```

```
What sources were cited in that ChatGPT answer?
```

```
Who was mentioned in that response?
```

### OAuth scope

Requires: `read:answers`


# Source tools
Source: https://docs.qwairy.co/mcp/tools/sources

Tools to analyze which domains and URLs AI providers cite as sources.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## get\_source\_domains

Get domains that AI cites as sources, ranked by mention frequency.

### Parameters

| Parameter | Type    | Required | Description                                             |
| --------- | ------- | -------- | ------------------------------------------------------- |
| `brandId` | string  | Yes      | The brand ID                                            |
| `domain`  | string  | No       | Search by partial domain name                           |
| `type`    | string  | No       | Filter by source type (see below)                       |
| `isSelf`  | boolean | No       | Filter to only your domain (`true`) or others (`false`) |
| `limit`   | number  | No       | Max domains (default: 50)                               |

### Source types

| Type            | Description                            |
| --------------- | -------------------------------------- |
| `INSTITUTIONAL` | Government, org sites (.gov, .org)     |
| `COMMERCIAL`    | Business/product sites                 |
| `MEDIA`         | News and media outlets                 |
| `BLOG`          | Blog content                           |
| `FORUM`         | Forums and communities (Reddit, Quora) |
| `SOCIAL`        | Social media platforms                 |
| `EDUCATIONAL`   | Educational institutions (.edu)        |
| `OTHER`         | Uncategorized                          |

### Returns

| Field                    | Type    | Description                                                       |
| ------------------------ | ------- | ----------------------------------------------------------------- |
| `id`                     | string  | Source domain ID                                                  |
| `domain`                 | string  | The domain name                                                   |
| `name`                   | string  | Display name (if known)                                           |
| `type`                   | string  | Source type                                                       |
| `mentions`               | number  | Total citation count                                              |
| `avgPosition`            | number  | Average position in source lists                                  |
| `aiSourceAuthorityScore` | number  | Qwairy Source Authority score (0-100), or `null` when unavailable |
| `isSelf`                 | boolean | Whether this is your domain                                       |
| `hasBacklink`            | boolean | Whether backlink opportunity exists                               |

### Example output

```markdown theme={null}
## Source domains cited by AI

| Domain | Type | Mentions | Avg Position | AI Authority | Self | Backlink |
|--------|------|----------|--------------|--------------|------|----------|
| reviews.example | COMMERCIAL | 234 | 1.8 | 87.4 | No | Yes |
| acme.example | COMMERCIAL | 198 | 2.3 | 82.1 | Yes | - |
| software-guide.example | COMMERCIAL | 156 | 2.5 | 78.6 | No | No |
| techcrunch.com | MEDIA | 89 | 3.1 | 72.3 | No | No |
| reddit.com | FORUM | 67 | 4.2 | 68.9 | No | No |
| wikipedia.org | INSTITUTIONAL | 45 | 2.8 | 74.5 | No | No |
```

### Example prompts

```
Which sources do AI providers cite most often?
```

```
Is my domain being cited as a source?
```

```
Show me media sources only
```

```
What forums are being cited for my topics?
```

<Tip>
  Domains with `hasBacklink: true` have known backlink marketplace opportunities. Consider these for outreach.
</Tip>

<Note>
  `aiSourceAuthorityScore` is Qwairy's proprietary score based only on how AI providers cite a domain across monitored prompts. It does not use backlinks or external SEO authority metrics.
</Note>

### OAuth scope

Requires: `read:sources`

***

## get\_source\_urls

Get specific URLs that AI cites as sources, with citation frequency.

### Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `brandId` | string | Yes      | The brand ID              |
| `domain`  | string | No       | Filter by specific domain |
| `limit`   | number | No       | Max URLs (default: 50)    |

### Returns

| Field         | Type   | Description                      |
| ------------- | ------ | -------------------------------- |
| `url`         | string | The full URL                     |
| `title`       | string | Page title (if available)        |
| `domain`      | string | The domain                       |
| `mentions`    | number | Number of times cited            |
| `avgPosition` | number | Average position in source lists |

### Example output

```markdown theme={null}
## Source URLs cited by AI

### 1. reviews.example
URL: https://reviews.example/project-management
Title: Best Project Management Software 2025
Mentions: 89
Avg Position: 1.5

### 2. acme.example
URL: https://www.acme.example/features
Title: Acme Corp Features
Mentions: 72
Avg Position: 2.1

### 3. software-guide.example
URL: https://software-guide.example/project-management
Title: Project Management Software Reviews
Mentions: 56
Avg Position: 2.3

### 4. acme.example
URL: https://www.acme.example/blog/productivity-guide
Title: The Ultimate Productivity Guide
Mentions: 34
Avg Position: 3.4
```

### Example prompts

```
What specific pages are AI providers citing?
```

```
Which of my pages get cited most?
```

```
Show me URLs from wikipedia.org that are being cited
```

```
What Reddit threads are being cited?
```

<Note>
  Use the `domain` filter to drill down into a specific source. For example, filter by your own domain to see which of your pages AI trusts most.
</Note>

### OAuth scope

Requires: `read:sources`

***

## get\_source\_trends

Track which source domains are gaining or losing citations in AI answers. The tool compares the selected period with the immediately preceding period of the same length, returns a daily or weekly timeline for the leading sources, and shows the current source-type mix.

### Parameters

| Parameter  | Type              | Required | Description                                              |
| ---------- | ----------------- | -------- | -------------------------------------------------------- |
| `brandId`  | string            | Yes      | The brand ID from `list_brands`                          |
| `period`   | integer or string | No       | Global evidence window; defaults to 30 days              |
| `groupBy`  | string            | No       | Timeline granularity: `day` or `week` (default: `day`)   |
| `provider` | string            | No       | Filter by normalized AI provider                         |
| `topicId`  | string            | No       | Filter by topic ID from `list_topics`                    |
| `tagId`    | string            | No       | Filter by tag ID from `list_tags`                        |
| `limit`    | number            | No       | Max source domains in the timeline (default: 5, max: 10) |

### Returns

| Field           | Description                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| `summary`       | Total citations and distinct source domains in the selected period                                    |
| `sources[]`     | Leading domains with source type, current citations, previous-period citations, and percentage change |
| `timeline[]`    | Daily or weekly citations and average citation position for each leading source                       |
| `sourceTypes[]` | Citation count and share for each source type                                                         |

When a source has citations in the selected period but none in the previous period, `changePercent` is `null` rather than an invented growth percentage.

### Example prompts

```
Which sources are gaining or losing citations this month?
```

```
Show weekly source trends for ChatGPT only
```

```
How has the source-type mix changed around this topic?
```

### OAuth scope

Requires: `read:sources`

***

## get\_backlink\_opportunities

Prioritized backlink and outreach targets: cited domains where competitors appear but your brand does not, ranked by opportunity, with marketplace pricing and domain rating when available. Use it to plan link-building and digital-PR outreach.

### Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands` |
| `limit`   | number | No       | Max opportunities to return     |

### Returns

| Field             | Description                                                                                                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `summary`         | `total`, `veryHigh`, `high` opportunity counts                                                                                                                                                                     |
| `opportunities[]` | Per domain: `domain`, `name`, `type`, `mentions`, `brandCitedAnswers`, `competitorCitedAnswers`, `distinctCompetitors`, `priority` (`very-high`/`high`/`medium`/`low`), `bestPrice`, `domainRating`, `platforms[]` |

### Example prompts

```
What are my best backlink opportunities right now?
```

```
Which high-authority domains cite competitors but not me?
```

### OAuth scope

Requires: `read:sources`


# Strategic tools
Source: https://docs.qwairy.co/mcp/tools/strategic

Tools for brand perception, technical status, prompt signals, and Action Center recommendations.

<Note>
  See [Filter Compatibility](/mcp/tools/filters) for the authoritative filter contract and the coverage of every MCP tool.
</Note>

## get\_content\_opportunities

Surface content gaps for the brand: monitored questions where competitors are mentioned but the brand is not, monitored questions with low brand visibility, and the top competitor threats. Use it to prioritize content production.

### Parameters

| Parameter | Type              | Required | Description                                 |
| --------- | ----------------- | -------- | ------------------------------------------- |
| `brandId` | string            | Yes      | The brand ID from `list_brands`             |
| `period`  | integer or string | No       | Global evidence window; defaults to 30 days |
| `limit`   | number            | No       | Max opportunities to return (default: 10)   |

### Returns

| Field                      | Description                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `period` / `periodLabel`   | The analyzed window                                                                                                         |
| `missedOpportunities[]`    | Questions where competitors appear but the brand does not: `question`, `keyword`, `competitorsMentioned[]`                  |
| `lowVisibilityQuestions[]` | Questions with under 30% brand visibility: `question`, `keyword`, `type`, `totalAnswers`, `brandMentions`, `visibilityRate` |
| `competitorThreats[]`      | Competitors most often present where the brand is missing: `name`, `mentionsWhereWeMiss`                                    |
| `summary`                  | `totalMissedOpportunities`, `totalLowVisibilityQuestions`, `topThreat`, `actionNeeded`                                      |

### Example prompts

```
Where should I create content to win more AI mentions?
```

```
Which questions am I losing to competitors?
```

### OAuth scope

Requires: `read:visibility`

***

## get\_brand\_perception

Get the latest brand perception snapshot: sentiment, alignment, consistency, factual-alignment scores, and SWOT insights (strengths, weaknesses, opportunities, threats). Returns only the most recent snapshot. For evolution over time, use `get_perception_history`.

### Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands` |

### Returns

| Field                       | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `snapshot.sentimentScore`   | Overall sentiment score                                    |
| `snapshot.alignmentScore`   | Alignment with brand positioning                           |
| `snapshot.consistencyScore` | Consistency across AI providers                            |
| `snapshot.factualAlignment` | Alignment with known brand facts (description, attributes) |
| `strengths[]`               | Brand strengths identified by AI                           |
| `weaknesses[]`              | Areas of improvement                                       |
| `opportunities[]`           | Growth opportunities                                       |
| `threats[]`                 | Potential threats                                          |

### OAuth scope

Requires: `read:visibility`

***

## get\_perception\_history

Get the evolution of the brand's perception snapshots over time: sentiment, alignment, consistency, and factual-alignment scores plus SWOT insights for each historical snapshot. For only the latest snapshot, use `get_brand_perception`.

### Parameters

| Parameter | Type   | Required | Description                                    |
| --------- | ------ | -------- | ---------------------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands`                |
| `limit`   | number | No       | Max snapshots to return (default: 10, max: 20) |

### Returns

| Field            | Description                                                                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `brand`          | `id`, `name`                                                                                                                                                                    |
| `totalSnapshots` | Total snapshots available for the brand                                                                                                                                         |
| `snapshots[]`    | Per snapshot: `month`, `year`, `sentimentScore`, `alignmentScore`, `consistencyScore`, `factualAlignment`, and the `strengths`, `weaknesses`, `opportunities`, `threats` arrays |

### Example prompts

```
How has my brand perception changed over time?
```

```
Show me my sentiment and alignment scores month by month
```

### OAuth scope

Requires: `read:visibility`

***

## get\_technical\_status

Get technical SEO status: AI Readiness Score, robots.txt, llms.txt, sitemap.xml analysis, blocked AI crawlers, and open page issues by severity.

### Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands` |

### Returns

| Field                         | Description                                                 |
| ----------------------------- | ----------------------------------------------------------- |
| `technical.aiReadinessScore`  | AI Readiness Score (0-100), same value as the dashboard     |
| `technical.robotsStatus`      | robots.txt analysis status                                  |
| `technical.llmsStatus`        | llms.txt analysis status                                    |
| `technical.sitemapStatus`     | sitemap.xml analysis status                                 |
| `technical.blockedCrawlers[]` | AI crawlers blocked by robots.txt                           |
| `issues`                      | Open issues count by severity (critical, high, medium, low) |
| `topIssues[]`                 | Most important open issues                                  |

### OAuth scope

Requires: `read:visibility`

***

## get\_prompt\_signals

Get prompt signal analysis: attack/defend/monitor/ignore labels based on Share of Voice and market openness. Identifies which prompts to invest in. Supports period, provider, topic, and tag filters.

### Parameters

| Parameter   | Type              | Required | Description                                               |
| ----------- | ----------------- | -------- | --------------------------------------------------------- |
| `brandId`   | string            | Yes      | The brand ID from `list_brands`                           |
| `period`    | integer or string | No       | Global evidence window; defaults to 30 days               |
| `startDate` | string            | No       | Start date in YYYY-MM-DD format                           |
| `endDate`   | string            | No       | End date in YYYY-MM-DD format                             |
| `providers` | string\[]         | No       | Filter by provider slugs (e.g. `["openai", "anthropic"]`) |
| `topicIds`  | string\[]         | No       | Filter by topic/keyword IDs                               |
| `tagIds`    | string\[]         | No       | Filter by tag IDs                                         |
| `limit`     | number            | No       | Max prompts per category (default: 5)                     |

### Returns

| Field                    | Description                                                                      |
| ------------------------ | -------------------------------------------------------------------------------- |
| `summary.attackCount`    | Prompts where market is open and brand is underrepresented                       |
| `summary.defendCount`    | Prompts where brand has strong position to defend                                |
| `summary.monitorCount`   | Prompts to keep watching                                                         |
| `summary.ignoreCount`    | Low-priority prompts                                                             |
| `summary.avgOpenness`    | Average market openness (0-1)                                                    |
| `summary.visibilityRate` | Percentage of prompts where brand is visible                                     |
| `summary.avgSoV`         | Average Share of Voice across visible prompts                                    |
| `summary.totalPrompts`   | Total prompts analyzed                                                           |
| `topAttackPrompts[]`     | Best attack opportunities: includes `priorityScore`, `visibilityPct`, `quadrant` |
| `topDefendPrompts[]`     | Positions to defend: includes `priorityScore`, `visibilityPct`, `quadrant`       |

### OAuth scope

Requires: `read:prompts`

***

## get\_site\_diagnostics

Per-page site health for the brand's monitored pages: latest technical, content, AEO, and performance scores plus open issue counts by severity, with brand-level averages. Complements `get_technical_status` (brand-wide) with a page-by-page view.

### Parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `brandId` | string | Yes      | The brand ID from `list_brands`             |
| `limit`   | number | No       | Max pages to return (default: 25, max: 100) |

### Returns

| Field     | Description                                                                                                                                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `summary` | `totalPages`, `pagesAudited`, `pagesWithIssues`, `avgTechnicalScore`, `avgContentScore`, `avgAeoScore`, `avgPerformanceScore`                                                                                                 |
| `pages[]` | Per page: `url`, `title`, `technicalScore`, `contentScore`, `aeoScore`, `performanceScore`, `issues` (`critical`/`high`/`medium`/`low`/`total`), `status`, `lastAuditAt`. Sorted worst-first (unaudited, then lowest scores). |

### Example prompts

```
Which of my pages have the worst technical health?
```

```
Show me pages with open critical issues
```

### OAuth scope

Requires: `read:visibility`

***

## get\_actions

Return the Action Center's prioritized recommendation queue: deterministic actions with a 3-tier priority label, a 1-5 demand badge, the quantified "why", the target engine when relevant, effort and a step-by-step checklist.

<Note>
  **Private beta.** The Action Center must be enabled for the team; otherwise the tool returns a `FORBIDDEN` error.
</Note>

### Parameters

| Parameter                   | Type      | Required | Description                                                                                                                                |
| --------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `brandId`                   | string    | Yes      | The brand ID from `list_brands`                                                                                                            |
| `actionId`                  | string    | No       | Fetch one specific action by ID, regardless of status (full context: signals, why, checklist)                                              |
| `status`                    | string    | No       | `SUGGESTED`, `PENDING`, `IN_PROGRESS`, `COMPLETED`, `DISMISSED`, `RESOLVED`. Default: live queue (`SUGGESTED` + `PENDING` + `IN_PROGRESS`) |
| `type`                      | string    | No       | Filter by action type (e.g. `CONTENT_GAP`, `TECHNICAL_FIX`, `SOURCE_OUTREACH`)                                                             |
| `category`                  | string    | No       | `TECHNICAL`, `CONTENT`, `AEO`, `AUTHORITY`, `VISIBILITY`                                                                                   |
| `period`                    | string    | No       | `"1"`, `"7"`, `"14"`, `"30"`, `"all"`, or `"custom"`; omit for the all-time live queue                                                     |
| `periodStart` / `periodEnd` | string    | No       | Inclusive custom range used with `period: "custom"`                                                                                        |
| `providers`                 | string\[] | No       | Evidence provider IDs                                                                                                                      |
| `topicIds`                  | string\[] | No       | Topic UUIDs                                                                                                                                |
| `tagIds`                    | string\[] | No       | Tag UUIDs                                                                                                                                  |
| `funnelStages`              | string\[] | No       | Any of `TOFU`, `MOFU`, and `BOFU`                                                                                                          |
| `limit`                     | number    | No       | Max actions to return (default: 25, max: 100)                                                                                              |

### Returns

| Field       | Description                                                                                                                                                                                                                                                                                                                                             |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `total`     | Total actions matching the filters                                                                                                                                                                                                                                                                                                                      |
| `actions[]` | Prioritized actions: `id`, `type`, `category`, `sourceType` (detector family), `scope` (`ON_SITE` / `OFF_SITE` / `SETUP`), `title`, `description`, `sourceUrl`, `targetProvider`, `forceTier` (`CRITICAL` / `HIGH` / `STANDARD`), `demandBadge` (1-5), `isQuickWin`, `effort`, `status`, `why`, `signals`, `target` (`baseline`, `goal`), `checklist[]` |

### Example prompts

```
What should I work on next to improve my AI visibility?
```

```
Show me the critical actions in my queue
```

### OAuth scope

Requires: `read:visibility`


# Cross-tool MCP workflows
Source: https://docs.qwairy.co/mcp/workflows

Combine read-only Qwairy evidence with authorized analytics, content, reporting, and task-management tools

Many MCP clients can connect to more than one server. Use Qwairy to retrieve authorized monitoring evidence, then pass a scoped summary to another tool for analysis, drafting, reporting, or task management.

<Warning>
  Qwairy MCP tools are read-only, but another connected tool may create, edit, publish, or send data. Review every tool's scopes and destination before authorizing a write, and require confirmation for externally visible actions.
</Warning>

## Preserve the evidence scope

Before combining tools, record:

* the Qwairy `brandId` and owning workspace;
* the exact date range, providers, topics, tags, prompts, and funnel filters;
* the metric definition and denominator returned by the Qwairy tool;
* any missing integration, sampling, retention, or coverage limitation;
* whether the next tool reads data, writes data, or both.

Do not merge metrics with the same name until you have verified their grain, unit, attribution rule, and time zone.

## Compare visibility with connected analytics

Qwairy's [measurement tools](/mcp/tools/measure) can read supported Search Console, Bing, analytics, revenue, and crawler data when the integration and `read:measure` scope are available.

<Steps>
  <Step title="Define the comparison">
    Choose one fixed period, market, provider, prompt cohort, and page set.
  </Step>

  <Step title="Retrieve visibility evidence">
    Query the relevant Qwairy performance, answer, source, or page-presence tool.
  </Step>

  <Step title="Retrieve outcome evidence">
    Use a Qwairy measurement tool first. Connect another authorized analytics server only when it provides a required field that Qwairy does not expose.
  </Step>

  <Step title="Explain the relationship">
    Report timing, attribution, and coverage separately. A correlated change does not establish causation.
  </Step>
</Steps>

Example prompt:

> Compare the pages with SELF citations in Qwairy against observed AI-referral sessions for the same 30-day UTC period. Keep uncited pages, unattributed traffic, and missing analytics coverage separate.

## Prepare a content change

Use Qwairy to form and support a content hypothesis. Use a CMS or repository tool to retrieve the current page and prepare a draft, not to infer a guaranteed outcome.

<Steps>
  <Step title="Inspect the gap">
    Read representative answers, cited sources, query fan-out evidence, and content opportunities for one topic.
  </Step>

  <Step title="Retrieve the current page">
    Ask the authorized content tool for the live or version-controlled source. Confirm that the URL and locale match the evidence.
  </Step>

  <Step title="Draft a bounded change">
    State the factual or structural hypothesis and preserve product review, brand, legal, and accessibility requirements.
  </Step>

  <Step title="Review before publishing">
    Show the diff and require an explicit approval in the system that owns the content.
  </Step>

  <Step title="Measure later">
    Compare an equivalent future monitoring scope without claiming the edit caused any change.
  </Step>
</Steps>

Example prompt:

> Use Qwairy to find one recurring factual question where our page is relevant but our domain is not cited. Retrieve that page from the CMS and draft a factual clarification. Do not publish it; show the evidence, assumptions, and proposed diff for review.

## Create an accountable task

Turn an observed issue into a task only after you have verified the supporting evidence.

Include:

* the Qwairy link or stable identifiers needed to reproduce the scope;
* the observed answer, source, or technical evidence;
* the proposed hypothesis and smallest reversible action;
* an owner, dependencies, and review requirement;
* a follow-up date and the metric or qualitative evidence to inspect;
* a statement that provider output is variable and the outcome is not guaranteed.

Example prompt:

> Review the current Action Center suggestions for this brand. For the highest-priority item with supporting evidence, prepare one task with reproduction steps, scope, owner placeholder, acceptance checks, and a follow-up measurement plan. Ask before creating it.

## Build a reporting artifact

Use a document or spreadsheet tool when stakeholders need a durable record.

1. Retrieve one Qwairy scope at a time.
2. Preserve raw numerators and denominators alongside percentages.
3. Label generated examples and modeled values.
4. Separate observations, interpretations, hypotheses, and decisions.
5. Include the effective date, filters, coverage limits, and data-source links.
6. Confirm the destination and audience before writing data outside Qwairy.

Example prompt:

> Prepare a weekly review from Qwairy for the selected brand. Include scope, numerator and denominator for each metric, three representative answers, changes from the comparable prior period, data limitations, and open hypotheses. Ask me to confirm the destination before creating the document.

## Choose the next tool deliberately

Use a complementary MCP server only when all of the following are true:

* it is operated or approved by the system owner you intend to access;
* its permissions are limited to the workflow's requirements;
* its data destination and retention are acceptable to your organization;
* its output has a documented grain and attribution method;
* any write or external message requires the expected confirmation.

Do not assume that a directory listing, package name, or community connector is current or approved.

## Get started

<CardGroup>
  <Card title="Connect Qwairy" href="/mcp/getting-started">
    Configure the read-only Qwairy server before adding another tool.
  </Card>

  <Card title="Review scopes" href="/mcp/oauth">
    Understand OAuth, Personal Access Tokens, team isolation, and revocation.
  </Card>

  <Card title="Use evidence filters" href="/mcp/tools/filters">
    Keep supported filters and date semantics explicit across calls.
  </Card>

  <Card title="Read measurement data" href="/mcp/tools/measure">
    Check connected analytics availability and coverage before adding another server.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.qwairy.co/updates/changelog

Review the features, improvements, and fixes introduced in each Qwairy release.

## Release history

Each linked page is a historical record of Qwairy at release time. Plans, limits, provider availability, model availability, and interface locations may have changed. Use the current product, API, MCP, or integration documentation to confirm present behavior.

### Versions

* **[Version 1.19](/updates/version-1-19)**: Source Authority, connected analytics, Crawler Analytics, and read-only API and MCP analysis
* **[Version 1.18](/updates/version-1-18)**: Action Center, AI Revenue, MCP access, and AI Crawler Readiness
* **[Version 1.17](/updates/version-1-17)**: Agency workflows, GEO audits, GEO Matrix v2, monitoring frequency, and Social Insights
* **[Version 1.16](/updates/version-1-16)**: Cockpit, navigation, influence analysis, and Act filters
* **[Version 1.15](/updates/version-1-15)**: Competitor comparison, saved filters, GEO Matrix, MCP, exports, and SSO
* **[Version 1.14](/updates/version-1-14)**: Weekly reports, shared links, Looker Studio, REST API endpoints, and prompt management
* **[Version 1.13](/updates/version-1-13)**: Brand Perception, Local Intelligence, and REST API v1
* **[Version 1.12](/updates/version-1-12)**: Crawler Analytics, Referrer Analytics, and Site Diagnostics
* **[Version 1.11](/updates/version-1-11)**: Social Intelligence, Shopping Intelligence, backlink opportunities, and Brand Perception
* **[Version 1.10](/updates/version-1-10)**: Competitor detection, Looker Studio, sentiment analysis, and dark mode
* **[Version 1.9](/updates/version-1-9)**: Insights Platform, Content Opportunities, and Content Studio
* **[Version 1.8](/updates/version-1-8)**: Credit costs, premium models, competitor pages, languages, and period comparison

No standalone release-note pages for versions 1.6 or 1.7 are present in this repository. This index does not infer their contents.

* **[Version 1.5](/updates/version-1-5)**: Monitoring architecture, backlink discovery, provider coverage, performance, and filtering
* **[Version 1.4](/updates/version-1-4)**: Interface, competitor analysis, performance metrics, and calculation changes
* **[Version 1.3](/updates/version-1-3)**: Recommendations, backlink prioritization, technical configuration, and analytics integrations
* **[Version 1.2](/updates/version-1-2)**: Performance dashboard, public site, pricing, and GEO Guide
* **[Version 1.1](/updates/version-1-1)**: Languages, AI Overview, self-service administration, and brand analysis
* **[Version 1.0](/updates/version-1-0)**: Model selection, monitoring schedules, subscriptions, and credits


# Version 1.0
Source: https://docs.qwairy.co/updates/version-1-0

Launch of custom LLM monitoring and simplified credit management.

## New features

### Custom LLM monitoring

Version 1.0 added model selection and scheduling controls for monitoring:

* **Selective model monitoring**: Choose which supported models generate responses for a monitoring prompt
* **Flexible scheduling**: Regenerate responses weekly or monthly, or trigger a manual update
* **Credit allocation**: Limit credit use by selecting only the models required for a monitoring scope

### Simplified credit management

The release introduced self-service subscriptions and monthly credit renewals:

* **Direct subscription**: Subscribe to a paid plan from the Qwairy dashboard
* **Automated renewals**: Receive the plan's monthly credit allocation at renewal
* **Self-service credits**: Replace the manual credit requests used during the private beta

## Improvements

* **Onboarding**: Reduced the number of setup steps for new users
* **Credit visibility**: Added the current credit balance and usage history


# Version 1.1
Source: https://docs.qwairy.co/updates/version-1-1

German and Spanish generation, AI Overview integration, self-service administration, and brand analysis updates.

## New features

### Language support

The release added German and Spanish response generation:

* **German**: Generate and analyze monitored responses in German
* **Spanish**: Generate and analyze monitored responses in Spanish
* **Country selection**: Apply the supported country configurations available for each provider

### AI Overview integration

Google AI Overview became available as a monitored provider:

* **AI Overview generation**: Generate and track your brand's appearance in Google's AI Overview snippets (2 credits per analysis)
* **Provider comparison**: Compare AI Overview observations with ChatGPT, Perplexity, and Claude observations in the same workspace

### Self-service administration

Account and credit administration moved into the product:

* **Credit management**: Add credits from the administration interface
* **Subscription details**: View and manage subscription information

## Improvements

### Brand analysis

* **Competitor detection**: Rebuilt the competitor extraction pipeline
* **Brand profiling**: Updated brand analysis generation
* **OpenAI processing**: Updated source extraction from OpenAI responses

## Bug fixes

* **Analysis reliability**: Fixed analysis job processing and response formatting issues
* **Data consistency**: Improved data handling across all analysis workflows


# Version 1.10
Source: https://docs.qwairy.co/updates/version-1-10

Competitor extraction, Looker Studio integration, sentiment analysis, and dark mode.

## New features

### Competitor detection

Competitors could now be extracted automatically from monitored answers:

* Discover competitors without maintaining a complete manual list
* Detect supported indirect mentions
* Refresh the observed competitor set on each monitoring cycle

**Three detection layers:**

* **Semantic matching**: Detects brands even when paraphrased
* **Domain inference**: Extracts and validates domains from partial mentions
* **Historical patterns**: Learns which brands appear together in your category

### Looker Studio data connector

Connect Qwairy to your existing reporting stack:

* **Visibility scores** by brand, provider, and date
* **Sentiment breakdown** (positive/neutral/negative trends)
* **Share of voice** vs. competitors over time
* **Citation sources** driving your mentions
* **Provider comparison** (ChatGPT vs. Perplexity vs. Claude)

Generate API tokens in Workspace Settings → Integrations.

### Sentiment analysis

Sentiment analysis added context to detected mentions:

* **Tone**: Positive, neutral, negative, or mixed
* **Context**: What aspect is discussed (pricing, features, support)
* **Source weight**: Sources with an authority label shown separately

**Uses:**

* Detect reputation risks early
* Benchmark sentiment vs. competitors
* Compare messaging with recurring positive and negative patterns

### Dark mode

Full dark theme with system preference detection. Toggle manually or let it follow your OS setting.

## Improvements

* **Competitor updates**: Engine runs on every monitoring cycle
* **Data exports**: Download supported datasets with filters applied
* **Visualizations**: Updated sentiment and perception charts


# Version 1.11
Source: https://docs.qwairy.co/updates/version-1-11

Analyze observed social and shopping citations, backlink opportunities, and brand perception.

## New features

### Social intelligence

Monitored answers can cite community, video, and social pages from more than 10 supported platforms:

**Communities:**

* Reddit, Hacker News, Stack Overflow, Quora, Product Hunt, Discord

**Video and social:**

* YouTube, Twitter/X, LinkedIn, TikTok

For each platform, review cited communities and channels, citation counts, average position, and the provider that cited them most often.

Illustrative values:

| Community            | Citations | Avg Position | Top Provider |
| -------------------- | --------- | ------------ | ------------ |
| r/productivity       | 47        | 2.3          | Perplexity   |
| r/saas               | 23        | 4.1          | ChatGPT      |
| YouTube/@TechChannel | 18        | 1.8          | Gemini       |

**Social opportunities**: Identify prompts where competitor domains are cited from social sources and your domain is not.

### Shopping intelligence 2.0

Track the stores cited or named alongside products in monitored answers.

Illustrative pattern:

| Store       | Citation pattern |
| ----------- | ---------------- |
| Amazon      | High presence    |
| Direct site | Low presence     |
| Retailers   | Varies           |

Compare store distribution with your desired purchase paths, then test changes over a consistent monitoring scope.

### Backlink opportunities

Prioritize links from sources observed in monitored citations:

* **Source extraction**: Sources from monitored AI responses analyzed
* **Competitive gaps**: Your presence vs. competitors on each source
* **32+ marketplaces**: Real-time pricing aggregation (Ereferer, Getfluence, WhitePress, etc.)

The release ranked opportunities with three factors:

1. High AI citation frequency
2. Competitor presence, you absent
3. Available at good price

### Brand perception

Track not just visibility, but how AI describes you:

* **Define 5-10 key attributes** you want AI to convey
* **Track alignment**: Which messages land, which are missing
* **Monthly snapshots**: Sentiment score, alignment score, SWOT analysis

If two providers describe the brand differently, use that difference to guide investigation. The observation does not establish a root cause.

## Improvements

* **Technical analysis**: AI Readiness Score (0-100) for robots.txt, llms.txt, and sitemap checks
* **Prompts redesign**: Updated filtering and visibility scores per prompt
* **Persistence Score**: Added response consistency as a separate signal from average visibility


# Version 1.12
Source: https://docs.qwairy.co/updates/version-1-12

Crawler Analytics, Referrer Analytics, and Site Diagnostics add website-level evidence to AI visibility monitoring.

## New features

### Crawler analytics

Track requests from identified AI crawlers in connected server logs:

At this release, the interface grouped more than 20 crawler and policy labels:

* **OpenAI**: GPTBot, ChatGPT-User, OAI-SearchBot
* **Anthropic**: ClaudeBot, Claude-Web
* **Google**: Google-Extended, Googlebot (AI features)
* **Perplexity**: PerplexityBot
* **Meta**: FacebookBot, Meta-ExternalAgent
* **Microsoft**: Bingbot (Copilot), MSNBot
* **Others**: Cohere, Applebot, YandexBot, Bytespider, and more

For each crawler:

* Crawl frequency and trends
* Pages visited
* Comparison to previous periods

**How to interpret the data:**

* A crawl records a request to your site. It does not prove indexing, model training, or use in an answer.
* If crawl volume declines, check the selected period, log collection, robots.txt rules, and site availability.
* Differences by crawler show observed request patterns, not provider preference.

<Warning>
  This historical list mixed observable HTTP User-Agent identities with policy or general-purpose identities. Current Crawler Analytics reports supported observable AI-specific User-Agent identities. `Google-Extended` is a robots-control token, not a crawler User-Agent, and `Googlebot` does not identify a separate AI-feature visit. Use the [current Crawler Analytics guide](/documentation/measure/crawler-analytics) for supported interpretation.
</Warning>

### Referrer analytics

Track traffic from AI conversations (powered by GA4):

| Platform   | Observed event                             |
| ---------- | ------------------------------------------ |
| ChatGPT    | Referral sessions attributed to ChatGPT    |
| Claude     | Referral sessions attributed to Claude     |
| Perplexity | Referral sessions attributed to Perplexity |
| Gemini     | Referral sessions attributed to Gemini     |
| Copilot    | Referral sessions attributed to Copilot    |

Compare periods week over week and month over month. Differences between platforms describe the connected analytics dataset and may not represent every user or visit.

### Site diagnostics

Audit supported pages for AI-readiness across four dimensions:

**Technical score (0-100)**

* Crawlability, robots.txt compliance
* Schema markup, structured data
* Canonical tags, XML sitemap

**Content score (0-100)**

* Readability, heading structure
* Content depth, keyword relevance
* Update frequency, internal linking

**AEO score (0-100)**

* Answer Engine Optimization
* FAQ sections, clear definitions
* Structured answers AI can extract

**Performance score (0-100)**

* PageSpeed Insights integration
* Core Web Vitals, loading speed
* Mobile-friendliness

**Page-level issues:**

* Each issue shows severity, type, and how to fix
* Severity and priority labels for triage

## Improvements

* **Unified Analytics module**: All intelligence in one place
* **Period comparisons**: Week and month trends
* **Export capabilities**: Download supported analytics datasets


# Version 1.13
Source: https://docs.qwairy.co/updates/version-1-13

Brand Perception, Local Intelligence, and REST API v1 expand brand and location analysis.

## New features

### Brand perception

**Compare how monitored providers describe your brand.**

ChatGPT might emphasize your pricing. Claude might focus on features. Perplexity might cite your documentation while Gemini references reviews. Each AI builds a different picture of your brand.

**What the page shows:**

* **Attribute alignment**: Which of your key messages AI actually conveys
* **Provider differences**: How ChatGPT, Claude, Perplexity, and Gemini describe you differently
* **Sentiment breakdown**: Positive, neutral, or negative framing by provider
* **Gap identification**: Configured attributes not detected in the selected answers

Define key brand attributes, select providers, and review which attributes are detected in the selected answers.

### Local intelligence

**Track businesses observed in answers to location-based prompts.**

Illustrative prompts: "Best restaurant near me." "Top hotel in Lyon." "Plumber in Paris 15ème."

These queries can return local recommendations. Local Intelligence records the businesses observed in supported provider answers.

**What the page shows:**

* Which businesses appear most often in the selected answers
* How often competitors are mentioned
* Which platforms recommend which businesses
* Associated sources, prompts, and provider patterns

### REST API v1 (Growth plan)

**Retrieve Qwairy data programmatically.**

Access visibility metrics, competitor data, monitoring results, and source analytics directly from your existing tools.

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://www.qwairy.co/api/v1/brands/{brandId}/visibility
```

**Use cases:**

* AI visibility data in Salesforce
* Weekly Slack digests with GEO metrics
* Executive dashboards combining SEO and AI data
* Automated reporting pipelines

**API features:**

* Team-scoped, revocable tokens
* Rate-limited at 100 requests/minute
* Generate tokens from Team Management > API Access

[Read the API documentation](/developers/introduction).

## Improvements

* **Search intent classification**: Queries in Search Intelligence are now automatically classified by intent (comparison, how-to, buying, etc.)
* **Performance**: Reduced loading and navigation time and updated chart interactions


# Version 1.14
Source: https://docs.qwairy.co/updates/version-1-14

Weekly Reports, Shared Links, Looker Studio v2, and additional REST API endpoints expand reporting options.

## New features

### Weekly report

**Receive a scheduled summary without opening the dashboard.**

Configured reports are emailed each Monday with:

* **Key metrics**: Visibility Score, Share of Voice, Source Citation Rate, Sentiment
* **Week-over-week changes**: What moved and by how much
* **Top competitors**: Who gained or lost visibility
* **Top sources**: Most cited domains across AI engines
* **Recommended actions**: Prioritized next steps based on the week's data

Enable per brand from Workspace > Notifications.

### Shared links

**Share selected dashboard data without requiring the recipient to have an account.**

Generate a public URL for Overview or Brand Perception data. Links use a token, support optional expiration after 7, 30, or 90 days, record views, and can be revoked. You can also send a link by email from the sharing dialog.

**Location:** Workspace > Shared Links

### Looker Studio v2

**Build custom dashboards with connected Qwairy data.**

The connector now exposes 13 data sources:

| Data source           | Included data                                                          |
| --------------------- | ---------------------------------------------------------------------- |
| Overview              | Visibility Score, Share of Voice, Sentiment, score breakdown over time |
| Answers               | Each AI response with provider, position, citations, sentiment         |
| Brands                | Brand names, domains, monitoring status                                |
| Competitors           | Share of Voice per competitor, rankings, evolution                     |
| Keywords              | Topic-level performance and mention rates                              |
| Local Intelligence    | Local business mentions and map pack appearances                       |
| Search Intelligence   | Search queries referencing your brand in AI results                    |
| Shopping Intelligence | Product citations and shopping-related mentions                        |
| Social Intelligence   | Social platform mentions and engagement signals                        |
| Prompts               | Monitoring prompts, providers, generation history                      |
| Source Domains        | Most cited domains, authority, citation frequency                      |
| Source URLs           | Individual URLs cited in AI responses                                  |
| Tags                  | Performance data segmented by custom tags                              |

[Read the Looker Studio documentation](/looker-studio/getting-started).

> Looker Studio requires a Growth plan or higher.

### REST API: new endpoints

**Retrieve Qwairy data from other tools.**

8 new endpoints join the existing API:

* **Keywords**: Filter and export topic-level visibility metrics
* **Local**: Pull local business mentions and map pack data
* **Prompt Evolution**: Track daily mention rate, source rate, and sentiment trends per prompt
* **Search**: Retrieve search queries that cite your brand
* **Shopping**: Access product citation and shopping mention data
* **Social**: Export social platform mentions per provider
* **Source URLs**: List all URLs cited in AI responses for your brand
* **Tags**: Query performance data by custom tag segments

[Read the API documentation](/developers/introduction).

> REST API requires a Growth plan or higher.

### Workspace prompts and bulk actions

**Manage monitoring prompts from a dedicated page.**

Select multiple prompts and apply actions in batch: delete, regenerate, assign tags or topics. Filter by topic, tag, or funnel stage, and edit prompts inline.

**Location:** Workspace > Prompts

## Improvements

* **New AI models**: GPT-5 family (nano, mini, 5, 5.1, 5.2), Claude 4.5 (Haiku, Sonnet, Opus), Gemini 3 (Flash, Pro), Grok 4, and Perplexity Deep Research
* **To Review (Competitors)**: Automatic detection of duplicate competitors, domain issues, and flagging before they enter monitoring
* **Technical module**: AI Readiness Score and Site Diagnostics grouped under a single section
* **Pricing simulator**: Estimate monthly credits before choosing a plan
* **Performance and reliability**: Reduced page-load and filtering time across the dashboard


# Version 1.15
Source: https://docs.qwairy.co/updates/version-1-15

Competitor comparison, saved filters, GEO Matrix, MCP Server, and asynchronous exports.

## New features

### Competitor compare

**Compare 2 to 10 competitors in one view.**

Select your competitors and get five layers of analysis:

* **11-metric comparison table**: Mention Rate, Citation Rate, Share of Voice, Total Mentions, Coverage, Avg Position, Avg Sentiment, Avg Relevance, Source Citations, Source Pages, and Providers. Green/red highlighting for best/worst, period-over-period trends on every cell
* **Brand positioning scatter chart**: Configurable X and Y axes across 11 metrics. Quadrant labels and scales adapt to your selection
* **Competitor overlap matrix**: An asymmetric co-mention heatmap. Each cell answers "When Brand A is mentioned, how often does Brand B appear in the same AI response?" Treat overlap as one competition signal, not proof of market positioning
* **Evolution chart**: Track how competitors move over time across 6 switchable metrics (Mentions, SoV, Coverage, Position, Sentiment, Relevance)
* **Breakdown heatmaps**: 5 dimensions (Providers, Topics, Tags, Funnel, Prompts) with 8 switchable metrics, sorted by your brand's performance by default

### Advanced filters and saved lists

**Keep selected filters while navigating between dashboard pages.**

A unified filter bar now sits at the top of every dashboard page. All filters support multi-select: narrow down to specific providers, topics, tags, and time periods. That selection stays synchronized as you navigate between all dashboard sections.

* **URL sync**: Every filter state is reflected in the URL. Copy it, share it, bookmark it
* **Saved lists**: Name and save a filter combination, then reload it later. Lists persist across sessions and are visible to your workspace
* **Page-specific controls**: Some pages add their own selectors on top of global filters (e.g., the Performance page adds competitor, funnel stage, and prompt selectors)

### GEO Matrix

**Compare scores across topics and providers.**

The GEO Matrix maps topics against AI providers. Each cell shows a color-coded score from 0 to 100, with the color representing the score range.

* **4 views**: Topics, Tags, Funnel Stages, and individual Prompts
* **Cell detail panel**: Click any cell to see score breakdown, competitor positions, cited sources, and trend sparklines
* **Trend indicators**: Week-over-week movement on rows and columns
* **Coverage metrics**: How many providers mention your brand per topic

### MCP server

**Connect a supported MCP client to Qwairy data.**

At release time, the server exposed 17 tools covering brands, scores, competitors, sources, and prompts, secured with OAuth 2.1 and PKCE. For example, a client could ask, "What's my visibility on ChatGPT for enterprise security?" and retrieve stored workspace data.

> Growth plan and above. Setup: Team Management > MCP Server

### Bing Webmaster Tools integration

**Add Bing search performance data to Qwairy.**

Connect a Bing API key, select a verified site, and retrieve queries and pages with clicks, impressions, CTR, and position. Each query is enriched with intent classification and cross-referenced with monitored prompts.

> All plans, including Free.

### Export hub

**Exports now run asynchronously in the background.**

Click "Export" on any page, pick a time range, and both CSV and XLSX files are generated automatically. Track progress in real-time, get an email when ready, and download from the Export Hub for up to 30 days.

> All paid plans. Access from Workspace Settings.

### Enterprise SSO (OIDC)

**Configure Okta, Azure AD, Google Workspace, or any OIDC-compliant IdP from Team Management.**

Add your company domains, verify via DNS TXT record, and team members sign in through your IdP automatically. Just-In-Time provisioning creates new users on first login with the role you define.

> Enterprise plan. Setup: Team Management > SSO

## Improvements

* **PNG export**: Export supported dashboard cards as branded PNG images. Available on more than 15 cards at release time, including the GEO Matrix
* **Shared Links with white label**: Share pages display the workspace logo
* **Competitor detail redesign**: 4 tabs: Overview (stats and proximity), Evolution (daily metrics with trends), Sources (cited domains and pages), Mentions (paginated table)
* **Source detail cockpit**: Rebuilt source detail page with a cockpit layout
* **Overview page redesign**: New 3-tab layout with a dedicated Funnel tab and intent distribution
* **Competitor favorites and ignored list**: Star competitors to prioritize them across selectors. Ignore irrelevant competitors to exclude them from scores
* **Looker Studio v2 connector**: Updated with multi-select filters and new evolution endpoints
* **API v1 improvements**: Multi-select filters, evolution endpoints, Prompt Evolution, and role-based access control
* **Customizable tag colors**: Assign custom colors to tags
* **Onboarding checklist and guided tours**: Step-by-step widget for new users with interactive popover walkthroughs
* **Performance**: Reduced matrix rendering time, cursor-based pagination, updated filter state management, and smaller API payloads


# Version 1.16
Source: https://docs.qwairy.co/updates/version-1-16

Cockpit, navigation, influence analysis, and filters on Act pages were reorganized.

## New features

### Cockpit restructured

The Cockpit section brought three summary and comparison views together:

* **Overview**: Your brand's 5 core KPIs (Mention Rate, Citation Rate, Share of Voice, Sentiment, Coverage), performance by provider, by topic, top sources, and top competitors: all on a single page
* **GEO Matrix**: The topics × providers heatmap previously accessible as a tab on the Overview page is now a standalone page in Cockpit
* **Compare**: Head-to-head competitor comparison with metrics table, positioning map, overlap matrix, evolution chart, and breakdown heatmaps. Previously nested under the Overview tabs, now accessible directly from the sidebar

### Navigation reorganized

**Six sections ordered around the documented workflow.**

The sidebar navigation has been restructured into a clear left-to-right workflow:

1. **Cockpit**: High-level KPIs and strategic views
2. **Monitor**: Prompts, Responses, Competitors, Sources, and Insights
3. **Analyze**: Sentiment and Brand Perception
4. **Act**: Content Opportunities, Backlink Opportunities, Content Studio
5. **Optimize**: Site Readiness, Site Diagnostics
6. **Measure**: Google Search Console, Bing Webmaster, Crawler Analytics, Referrer Analytics, Page Performance

The sequence moves from monitoring and analysis to action, optimization, and measurement.

### Triggering prompts in influence tabs

**See which monitored prompts are associated with a competitor mention or source citation.**

The Competitor Detail and Source Detail pages now include a "Triggering Prompts" section in their Influence tabs. For each competitor or source, you can see the prompts associated with its mention, with provider badges, mention counts, and navigation to prompt detail.

### Competitor logos on source pages

**Identify competitors associated with a source.**

Source detail pages now display competitor logos alongside mention data. When browsing a source domain's influence, you can immediately see which competitors appear on that source without reading through individual mentions.

## Improvements

* **Filters on Act pages**: Content Opportunities and Backlink Opportunities now support global filters: tags, period, and funnel stage. Apply your context once and drill into the gaps that matter most
* **Deep-linking to detail tabs**: Detail sheets (competitors, sources, prompts, responses) now support an `initialTab` URL parameter. Share a link that opens directly to the Influence tab or any other specific view
* **Backlinks tab gated by plan**: The Backlinks tab on Source detail pages is now reserved for paid plans (Starter and above). Free plan users see the core source metrics without the backlink analysis layer
* **Documentation restructured**: Documentation navigation now mirrors the dashboard sections (Cockpit, Monitor, Insights, Analyze, Act, Optimize, Measure)


# Version 1.17
Source: https://docs.qwairy.co/updates/version-1-17

Agency plans, pitch audits, GEO Matrix v2, per-prompt monitoring frequency, Social Insights updates, and broader AI Assistant access.

## New features

### Agency plan: pitch workspaces and directory

**Dedicated spaces for agency prospecting.**

The Agency Plan lets agencies run GEO audits for prospects without mixing them into production monitoring.

* **Pitch workspaces**: pitch brands live separately from your production brands and don't count toward your brand limit
* **PDF export**: generate branded reports to share with prospects
* **Agency directory**: list your agency on qwairy.co with specialties and certification badge
* **Two tiers**: Agency Starter (10 pitches/month) and Agency Pro (50 pitches/month), available as standalone or add-on plans

> **Location:** Sidebar > Agency Dashboard

### GEO audits: competitor reports

**Competitor analysis with PDF export.**

Select a competitor and generate a structured GEO audit from the stored monitored answers:

* GEO Score (0–100): weighted composite of mention rate, position, sentiment, and share of voice
* Provider breakdown with your brand comparison
* Topic analysis with coverage gaps and opportunity areas
* Source citations with brand-on-page status
* AI-generated priority actions

Every audit can be exported as a PDF with cover page, metrics tables, and recommendations.

> **Location:** Cockpit > Reports

### GEO Matrix v2

**Competitor rankings and multi-metric analysis.**

The GEO Matrix received a major upgrade with competitor rankings, sub-metric breakdowns, and a metric selector.

* **Metric selector**: Switch the matrix view between Score, Mention Rate, Share of Voice, Citation Rate, and Sentiment
* **Competitor ranking**: Every cell shows where your brand ranks among direct competitors (`#rank/total · avg X`). Colors reflect competitive position: green (#1), blue (top third), yellow (middle third), orange (bottom third)
* **Detail panel**: Sub-metrics with ranking badges, color-coded progress bars, and top sources filtered to brand and direct competitor domains only
* **Per-provider averages**: Each metric shows the average across all rows for that provider

> **Location:** Cockpit > GEO Matrix

### Monitoring v2: per-prompt frequency and boost mode

**Granular control over monitoring cadence.**

* **Per-prompt frequency**: Set each prompt to Daily, Weekly, or Monthly. Prompts without a custom frequency inherit the brand-level setting
* **Bulk frequency editor**: Update dozens of prompts at once
* **Boost mode**: Generate up to 20 responses per prompt per monitoring run to collect a larger sample
* **Credit estimation**: See estimated credit cost before running a monitoring cycle

> **Location:** Workspace > Monitoring for brand-level settings, or Workspace > Prompts for prompt settings

### Social Insights: platform-first redesign

**Citations grouped by platform with on-page presence detection.**

Social Insights now groups citations by platform (Reddit, YouTube, Hacker News, X, LinkedIn, Quora). Each platform has two sub-views:

* **Communities**: forums, subreddits, channels with citation count, providers, and on-page presence status
* **Citations**: individual AI responses citing social sources

On-page presence shows whether your brand is actually mentioned on the cited page (Present, Partial, Absent, Not checked).

> **Location:** Monitor > Insights > Social Signals

### AI Assistant: access for team members

**The AI assistant became available to all team members.**

Previously restricted to admins, the assistant became available to all team members. Ask AI buttons on competitor pages, source details, and prompt analysis open with relevant context.

## Also in v1.17

* **GEO Matrix API**: New public API endpoint `GET /api/v1/brands/{brandId}/matrix` with scores, sub-metrics, competitor rankings, per-provider averages, and filtering options
* **GEO Matrix in Ask AI**: The AI assistant can now analyze GEO Matrix data and answer questions about topic × provider performance
* **Filter visibility**: Empty states indicate when filters are active and include a reset control. Sidebar counts show filtered and total values


# Version 1.18
Source: https://docs.qwairy.co/updates/version-1-18

AI Revenue and Action Center availability, Starter-plan MCP access, Measure tools, AI Crawler Readiness, and updated premium models.

## New features

### Action Center: from insight to action

**Out of beta, available on every paid plan.**

The Action Center combines selected signals from prompts, answers, sources, competitors, site diagnostics, and search demand into a prioritized action list.

* **Deterministic recommendations**: recommendations are generated deterministically from their input dataset and include their supporting signals
* **Priority score**: every action carries a 0–100 score anchored to a Critical, High, or Standard tier, plus a 1–5 demand signal
* **Quick Wins first**: high-impact, low-effort actions are surfaced up front
* **Guidance and artifacts**: actions include a step-by-step guide and may include an artifact such as a FAQ schema block, outreach email draft, or community engagement plan
* **Post-completion measurement**: completing an action tracks the selected metric for 90 days. A subsequent change is observed, not proof that the action caused it
* Also available programmatically through the **REST API** and the **MCP server**

> **Location:** Cockpit > Action Center

### AI Revenue: three-layer attribution

**Connect AI visibility, traffic, and revenue observations.**

AI Revenue moved from beta into the Measure module with a self-service GA4 setup wizard.

* **Crawler Coverage**: which AI bots crawl your site, how often, on which pages
* **AI-Referred Visits**: sessions arriving from ChatGPT, Perplexity, Gemini, Copilot and other AI sources, pulled live from Google Analytics 4
* **AI-Influenced Revenue**: conversions and revenue already tracked in GA4, segmented by AI-referred traffic

> **Location:** Measure > AI Revenue

### MCP Server available from Starter

**Previously Growth and above.**

At release time, Qwairy's native MCP server became available from the **Starter plan** and exposed more than 40 tools secured with OAuth 2.1.

A new **Measure** tool cluster lets assistants pull off-AI analytics alongside AI visibility data:

* **Search Console and Bing performance**: `get_search_console_metrics`, `get_bing_metrics`
* **AI-referred traffic and revenue**: `get_referrer_analytics`, `get_ai_revenue`
* **Crawler activity and page performance**: `get_crawler_activity`, `get_page_performance`

Plus three tools outside the Measure cluster: **sponsored content** (`get_sponsored_content`), **backlink opportunities** (`get_backlink_opportunities`), and **site diagnostics** (`get_site_diagnostics`).

A new **user-scoped personal access token** lets headless clients such as automation platforms and scripts connect across the teams available to the user with one key. At release time, the REST API remained available from Growth.

> **Setup:** Add `https://mcp.qwairy.co` in your AI client. See [MCP Getting Started](/mcp/getting-started).

### AI Crawler Readiness

**63 known AI crawlers, evaluated against your `robots.txt`.**

At release time, the redesigned readiness view checked `robots.txt` against 63 known AI crawlers associated with providers including ChatGPT, Claude, Gemini, Perplexity, Copilot, and Mistral. For each crawler, the view showed whether access was allowed or blocked, the applicable rule, the crawler purpose, and its priority tier. It also showed the last-seen time from connected server logs.

> **Location:** Optimize > Site Readiness

## Also in v1.18

* **Social Signals refresh**: communities, URLs, prompts, opportunities, and engagement cues in clearer, consolidated views: inspect the prompts behind a cited social URL and preview video/social sources directly from the insight tables
* **Premium model lineup**: Claude, OpenAI, Gemini, Grok, and Mistral models were added in this release, older variants were retired, and premium credit costs were adjusted. Core models remained at 1 credit per query at release time
* **Global search (⌘K)**: jump to any page, prompt, competitor, source, or documentation article from anywhere in your workspace


# Version 1.19
Source: https://docs.qwairy.co/updates/version-1-19

Source Authority, additional analytics providers, Crawler Analytics updates, and read-only MCP and AI Assistant workflows.

## New features

### Source Authority

Source Authority scores each cited domain from 0 to 100 based on its observed influence across the AI answers, providers, topics, and time periods monitored for your brand.

* Compare citation volume with observed AI influence
* Distinguish established patterns from low-confidence signals
* Prioritize source outreach and backlink opportunities in the Action Center
* Inspect Source Authority directly through MCP source profiles

Source Authority is specific to AI citations. It is not a renamed backlink-based Domain Authority or Domain Rating metric.

> **Location:** Monitor > Citation Sources

### Connected Analytics and Crawler Analytics

Qwairy now supports **Matomo**, **Piano Analytics**, **Adobe Analytics**, and **Amplitude** alongside Google Analytics 4 and Piwik Pro. Available referral, conversion, and revenue capabilities reflect the data each provider exposes.

Crawler Analytics has also been rebuilt around observed AI bot activity, requested pages, frequency, HTTP outcomes, freshness, and coverage. Human visits from AI assistants remain separate in Referrer Analytics.

> **Location:** Measure

### Expanded read-only API and MCP analysis

At release time, the MCP server exposed **46 read-only tools**. Version 1.19 added `get_source_trends`, which returns:

* Source domains with the highest observed citation counts or changes compared with the previous equal-length period
* Daily or weekly citation timelines
* Source-type distribution
* Optional provider, topic, and tag filters

`get_query_fan_out` can now focus on one monitored prompt with `promptId`. Source domain discovery also documents its partial-domain search filter.

The same source-trend and prompt fan-out analyses are available in Qwairy's in-app AI Assistant. Requests about AI referral traffic now route to the existing Referrer Analytics tool.

Agency Pitch Audits became available through both REST API and MCP. Agencies can list audits, read a prospect report, compare co-competitor score summaries in one request, and open any derived report using its `subjectId`. These integrations are read-only.

> **References:** [Pitch Audit API](/developers/endpoints/pitch-audits/list), [Pitch Audit MCP tools](/mcp/tools/pitch-audits), and `https://mcp.qwairy.co`

## Also in v1.19

* **AI Revenue configuration** for ecommerce and lead-generation conversion definitions
* **Site Diagnostics refresh controls** for eligible monitored pages
* **Expanded Viewer access** to additional read-only analytics and AI Assistant workflows
* **Agent Skills** with predefined analyses across visibility, sources, content, site, impact, reputation, and help
* **Larger Pitch Audits** with up to 100 prompts in agency and admin creation flows, while keeping 20 as the default
* **Advanced exports** for Brand Perception and Pitch Audit workflows


# Version 1.2
Source: https://docs.qwairy.co/updates/version-1-2

Dashboard redesign, flexible pricing, and the launch of the Qwairy GEO Guide.

## New features

### Performance dashboard redesign

The dashboard received new visualizations, metrics, and responsive layouts:

* **Updated visualizations**: New charts and metrics for reading AI monitoring data
* **Summary views**: Review key changes before opening detailed data
* **Responsive interface**: Review performance on supported screen sizes

### Landing page and brand story

The public site was updated to explain Qwairy's product scope:

* **Product positioning**: Explain the role of AI visibility monitoring
* **Use cases**: Describe how Qwairy fits into marketing and reporting workflows
* **Examples**: Illustrate product workflows across different types of brands

### Flexible pricing

The release introduced a free plan and revised paid tiers:

* **Free plan**: Create an account without a credit card
* **Revised tiers**: Separate plans for individual, team, and enterprise use
* **Product evaluation**: Use the free allocation before selecting a paid tier

### Qwairy GEO Guide

The Qwairy GEO Guide was published with explanatory and task-oriented material:

* **Strategies**: Approaches for investigating and improving AI visibility
* **Industry observations**: Findings drawn from analyzed AI queries
* **Workflows**: Step-by-step implementation guides
* **Guide**: [Open the GEO Guide](https://www.qwairy.co/guide)

## Improvements

* **Loading times**: Reduced dashboard loading time
* **Onboarding**: Reduced the steps from signup to the first analysis
* **Plan comparison**: Updated the information used to compare plans


# Version 1.3
Source: https://docs.qwairy.co/updates/version-1-3

Strategic recommendations, technical optimization tools, and analytics integrations.

## New features

### AI-powered strategic recommendations

The release added recommendations derived from monitored data:

* **Custom visibility strategies**: Get tailored recommendations based on your industry, competitors, and current AI performance
* **LLM-specific tactics**: Targeted approaches for ChatGPT, AI Overview, Perplexity, and other major AI platforms
* **Implementation roadmaps**: Step-by-step action plans with priority rankings and stated impact
* **Competitive gap analysis**: Identify differences between your observations and competitor observations

### Backlink prioritization

Backlink opportunities received ranking and analysis controls:

* **Impact scoring**: Rank backlink opportunities by the signals available at release time
* **Authority mapping**: Compare domain citation frequency and relevance
* **Strategic recommendations**: Get specific outreach targets and messaging suggestions
* **Performance tracking**: Compare AI visibility observations before and after a backlink is added

### Technical configuration tools

The release added tools for reviewing and updating crawler-facing configuration:

* **robots.txt configuration**: Configure access rules for supported AI crawlers
* **llms.txt generation**: Create and maintain this emerging standard to communicate your content intentions to AI systems
* **Technical audit alerts**: Get notified when your site configuration could be limiting AI visibility
* **Configuration suggestions**: Apply supported technical changes from the audit

### LLM analytics integrations

The release connected server-side crawler and traffic observations:

* **Bot detection and analysis**: Identify and track visits from ChatGPT, Claude, Gemini, and other AI crawlers
* **Traffic attribution**: Separate crawler activity from subsequent human referral visits
* **Performance comparison**: Compare AI mentions, website traffic, and conversion data over the same period
* **Server-side integration**: Configure analytics for supported infrastructure

### Google Search Console integration

Google Search Console data became available alongside AI monitoring data:

* **Question-type keyword discovery**: Identify question-shaped GSC queries for further analysis
* **Opportunity mapping**: Find high-potential keywords from your GSC data to monitor on Qwairy
* **Performance comparison**: Spot visibility gaps between traditional search and AI responses
* **Unified dashboard**: View GSC and AI monitoring data side by side

## Improvements

* **Strategy modules**: Updated the analysis inputs used for recommendations
* **Integrations**: Reduced setup steps for GSC and server analytics connections
* **Data visualization**: Updated charts and metrics across the new features

## Bug fixes

* **Integration stability**: Resolved edge cases in third-party data connections
* **Performance**: Reduced loading times for analytics-heavy pages


# Version 1.4
Source: https://docs.qwairy.co/updates/version-1-4

Interface updates, competitor intelligence, and performance improvements.

## New features

### Interface redesign

This release introduced a broad interface update:

* **Queries page**: Updated controls for exploring and analyzing AI queries
* **Answers visualization**: Revised the presentation of AI responses
* **Design system**: Applied consistent components and interaction patterns across the interface
* **Responsive design**: Added layouts for supported screen sizes

### Competitor analysis

Competitor pages added sentiment, relevance, positioning, and trend views:

* **Sentiment analysis per competitor**: Review how each competitor is framed in monitored answers
* **Relevance scoring**: Measure how closely each competitor matches specific query contexts
* **Competitive positioning maps**: Visual representations of where you stand versus competitors in AI responses
* **Trend analysis**: Track sentiment and relevance changes across selected periods

### Performance metrics

The dashboard added new KPI, segmentation, and filtering options:

* **New strategic KPIs**: Metrics designed specifically for GEO success measurement
* **Sentiment-weighted performance scores**: Calculations that include mention context alongside frequency
* **Category-based visibility views**: Organize and analyze your performance by content categories, topics, or business segments
* **Filtering and segmentation**: Narrow the selected dataset by the available dimensions

## Improvements

### Performance and efficiency

* **Application loading**: The release reported page-load improvements of up to 40%
* **Token consumption**: Reduced token use during AI processing
* **Data processing**: Reduced analysis processing time
* **Workflows**: Reduced the number of steps for common tasks

### Performance calculations

* **Sentiment integration**: Performance scores now factor in the emotional context of mentions, not just frequency
* **Weighted metrics**: Scoring that includes relevance, authority, and context signals
* **Trend-aware calculations**: Performance metrics that account for temporal patterns and seasonal variations

## Bug fixes

* **Interface stability**: Resolved edge cases that could cause UI inconsistencies
* **Data synchronization**: Fixed rare issues with real-time data updates
* **Cross-browser compatibility**: Fixed rendering differences across supported browsers


# Version 1.5
Source: https://docs.qwairy.co/updates/version-1-5

New insight, automation, and performance capabilities for monitored AI presence.

## New features

### Monitoring architecture

The monitoring system added domain-level views, dedicated analysis pages, and live updates:

* **Domain-level analysis**: Track performance at the source and competitor domain level
* **Analysis pages**: Review responses, prompts, sources, and competitors in dedicated views
* **Real-time WebSocket updates**: Watch your metrics evolve live without page refreshes
* **Relationship mapping**: Compare DIRECT and INDIRECT competitor relationships

### Backlink discovery

Backlink discovery used observed AI citations to identify and rank source opportunities:

* **Opportunity identification**: Discover backlink prospects from AI-cited sources
* **Integrated outreach workflow**: Built-in notification system to streamline your link-building campaigns
* **Quality scoring**: Prioritize opportunities based on domain authority and relevance metrics
* **Bulk export**: Send opportunity data to other SEO workflows

### Provider and market coverage

The release expanded supported crawlers, countries, providers, and languages:

* **20+ AI crawler detection**: Monitor GPTBot, ClaudeBot, PerplexityBot, and emerging platforms
* **Multi-country intelligence**: Track performance variations across geographic markets
* **Provider-specific analytics**: Compare how monitored providers represent your brand
* **Localized content generation**: Generate content in EN, FR, DE, and ES

## Improvements

### Performance and scalability

* **Data processing**: The release reported a 10-fold improvement after introducing batch processing
* **SQL architecture**: Added indexes to reduce query response time
* **Caching**: Reduced repeated API calls and dashboard load time
* **Pagination**: Added page sizes of 25, 50, 100, and 200 results

### Filtering and analysis

* **Multi-criteria filtering**: Combine time periods, providers, tags, sentiment, and relevance scores
* **Sorting**: Added stable ordering for supported fields
* **Filtered exports**: Download supported datasets with applied filters in CSV or JSON
* **Saved filter presets**: Create and share custom views with your team

### User experience

* **Onboarding flow**: Added interactive tooltips, bulk selections, and default values
* **Loading states**: Added skeleton states throughout the application
* **Responsive design**: Updated layouts from mobile to large desktop displays
* **Accessibility**: Updated keyboard navigation and screen reader support

## Bug fixes

* **Position calculations**: Corrected competitor mention positioning
* **WebSocket stability**: Resolved connection drops and improved real-time data reliability
* **Post-onboarding navigation**: Fixed dashboard navigation after initial setup
* **Provider logo display**: Fixed favicon and logo rendering across the interface


# Version 1.8
Source: https://docs.qwairy.co/updates/version-1-8

More AI models at lower costs, detailed competitor page analysis, expanded language support, and week-over-week tracking.

## New features

### Credit cost reductions

Core models now cost **1 credit per query** (instead of 3):

* ChatGPT, AI Overview, Gemini, Perplexity, Grok, AI Mode, Copilot

The release also changed collection for core models to capture available responses and citations directly.

### Premium models

The following premium models became available at release time:

| Provider   | Models                                                                             |
| ---------- | ---------------------------------------------------------------------------------- |
| OpenAI     | GPT-4o mini, GPT-4o, GPT-4.1, GPT-5 nano, GPT-5 mini, GPT-5                        |
| Anthropic  | Claude Haiku 3.5, Claude Sonnet 3.7, Claude Opus 3, Claude Sonnet 4, Claude Opus 4 |
| Google     | Gemini 2.0 Flash, 2.5 Flash, 2.5 Pro                                               |
| xAI        | Grok 3 mini, Grok 3, Grok 4                                                        |
| Perplexity | Sonar, Sonar Pro                                                                   |
| Mistral    | Small, Medium, Large                                                               |
| DeepSeek   | Chat, Reasoner                                                                     |

### Competitor page analysis

Click any competitor to see their **top-performing pages**:

* Most cited content across prompts
* Breakdown by LLM model
* Whether they rank as a source or brand mention
* Content structure patterns observed among cited pages

Use these observations to compare competitor topics, cited pages, and content structure. They do not establish why a provider selected a page.

### Language support

The release added five generation languages:

* Italian 🇮🇹
* Dutch 🇳🇱
* Portuguese 🇵🇹
* Swedish 🇸🇪
* Polish 🇵🇱

### Week-over-week comparison

Compare brand visibility week over week in the dashboard. A change after an optimization is an observation, not proof that the optimization caused it.

## Improvements

* **Source classification**: Detection of source relationships (COMPETITOR, AUTHORITY, INSPIRATION, REFERENCE)
* **Response collection**: Direct collection for core models
* **Credit use**: Reduced credit cost for the listed core models


# Version 1.9
Source: https://docs.qwairy.co/updates/version-1-9

Insights Platform, Content Opportunities, and Content Studio connect monitoring data with content workflows.

## New features

### Insights platform

Two modules summarize product and search observations from monitored data:

**Shopping Intelligence**

* Discover which products AI recommends
* See how AI describes your features vs. your marketing
* Identify gaps by product tier

**Search Intelligence**

* Track query fan-outs: 10 core prompts → 200+ discovered queries
* Find opportunities where competitors haven't positioned content
* Map related queries into topic clusters

### Content opportunities

Gap analysis identifies prompts and sources for further content research:

**Dual gap analysis:**

* **Brand Gap (0-100%)**: Where competitors appear without you
* **Source Gap (0-100%)**: When AI cites sources but not yours

Each generated opportunity includes:

* Exact competitor sources (URLs, titles, positioning)
* Provider breakdown (which AI platforms show this gap)
* Numeric priority scoring
* Brief creation

### Content studio

AI-powered content generation from 7 intelligence sources:

1. Content Opportunities
2. Search Intelligence
3. Google Search Console
4. Monitored Topics
5. Citation Sources
6. Competitor URLs
7. Any External URL

**Four-stage workflow:**

1. Configuration (type, length, persona, language)
2. Outline generation (H2/H3 hierarchy, section targets)
3. Content generation (with built-in fact-checker)
4. Metadata optimization (SEO titles, meta descriptions)

**Source classification:**

* COMPETITOR: compare topics and structure
* AUTHORITY: review as a potential supporting source
* INSPIRATION: review for structure
* REFERENCE: check facts and claims against the source

## Improvements

* **Data-derived recommendations**: Recommendations calculated from monitored performance data
* **Fact-checking step**: Checks drafts against the sources available to the workflow
* **15+ languages**: Content generation in supported target languages


# Did my latest marketing campaign improve my AI visibility?
Source: https://docs.qwairy.co/use-cases/campaigns/campaign-impact-on-ai-visibility

Compare stable pre-campaign and post-campaign cohorts, then report observed changes without attributing them to the campaign.

## Direct answer

Use **Cockpit > Overview** to compare a stable prompt, provider, model, topic, and competitor cohort before and after the campaign. Add answer-level evidence and record any concurrent changes. Describe movement as associated with the campaign period unless you have a separate causal design.

## Data required

Use campaign start and end dates, unchanged configured prompts, providers and models, topics or tags, SELF/DIRECT classifications, stored answers and citations, comparable periods, and a log of content, PR, product, competitor, and monitoring changes.

## Workflow

<Steps>
  <Step title="Define the baseline">
    Choose a pre-campaign period and record the exact prompt, provider, model, topic, geography, and competitor configuration.
  </Step>

  <Step title="Mark the campaign window">
    Record launch, publication, distribution, and end dates. Note which pages, claims, and audience topics the campaign targeted.
  </Step>

  <Step title="Compare the stable cohort">
    Review Mention Rate, Citation Rate, Share of Voice, Coverage, sentiment, and representative answers only where they answer the campaign question.
  </Step>

  <Step title="Audit alternative explanations">
    Check model, prompt, source, competitor, product, and tracking changes before interpreting the difference.
  </Step>
</Steps>

## Interpretation

Product Mention Rate, Citation Rate, Share of Voice, and Coverage use distinct units and denominators; retain their documented definitions. A post-campaign increase is temporal association. It does not establish that the campaign caused provider outputs to change.

## Possible next actions

* If movement is concentrated in targeted topics, test the hypothesis with additional comparable runs before extending the campaign.
* If citations change without SELF mentions, inspect the answers and cited URLs rather than calling the campaign successful.
* If no change is observed, verify cohort stability and source availability before revising the campaign.

## Limitations

Provider outputs, models, web access, sources, competitors, and monitoring configuration can change during the comparison. Qwairy observes selected stored answers and cannot isolate campaign causality or guarantee a response timeline.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export the comparison cohort.
  </Card>

  <Card title="Performance Overview" href="/looker-studio/sources/performance-overview">
    Build a period comparison from documented data.
  </Card>

  <Card title="Monitoring" href="/documentation/workspace/monitoring">
    Review the configured prompt set.
  </Card>

  <Card title="Visibility over time" href="/use-cases/visibility/how-has-my-visibility-changed">
    Apply stable-cohort comparison rules.
  </Card>

  <Card title="Content pickup observations" href="/use-cases/campaigns/how-fast-ai-picks-up-content">
    Track crawler and citation events separately.
  </Card>

  <Card title="Share of Voice" href="/use-cases/visibility/what-is-my-share-of-voice">
    Use the product occurrence formula.
  </Card>

  <Card title="Automated reporting" href="/use-cases/reporting/automated-geo-reporting">
    Create a repeatable reporting workflow.
  </Card>
</CardGroup>


# How quickly do AI models pick up new content I publish?
Source: https://docs.qwairy.co/use-cases/campaigns/how-fast-ai-picks-up-content

Track publication, the first retained crawler observation, recorded citations, and answer changes as separate milestones without claiming model ingestion.

## Direct answer

Qwairy cannot directly measure when a model ingests or learns a page. You can record publication time, compare it with a page identity's retained `firstSeenAt`, check whether the URL later appears as a citation, and review relevant stored answers. Report each milestone separately.

## Data required

Use the final public URL, publication timestamp, deployment and update log, reconstructible normalized paths, retained first and last observed times, daily occurrence rollups, coverage state, stored answers, citation URLs, configured prompts, providers and models, topics, and run dates.

## Workflow

<Steps>
  <Step title="Record the release">
    Save the canonical URL, publication time, content scope, sitemap or internal-link state, and the prompt cohort relevant to the page.
  </Step>

  <Step title="Check the first retained crawler observation">
    In Crawler Analytics, find the reconstructible page identity and review `firstSeenAt`, `lastSeenAt`, occurrence rollups, status-code groups, and coverage. `firstSeenAt` is the first retained HTTP 2xx page observation, not a raw-event sequence.
  </Step>

  <Step title="Check recorded citations">
    In Source Explorer, look for the published URL in comparable stored-answer runs. Keep citation presence separate from SELF mentions.
  </Step>

  <Step title="Review answer changes">
    Read relevant answers before and after publication and document any changes with the same provider, model, prompt, and topic filters.
  </Step>
</Steps>

## Interpretation

The interval to the first retained crawler observation, first recorded citation, and first relevant answer change are different measures. None proves indexing, training, or causation. A citation URL can appear without a SELF mention, and a SELF mention can appear without citing the page.

## Possible next actions

* If no page observation is retained, check coverage, discoverability, and access configuration before changing the content.
* If crawling is observed without citations, test whether the page addresses the monitored audience need with verifiable evidence.
* If an answer changes before a citation appears, investigate other sources and model changes rather than attributing it to the page.

## Limitations

There is no universal or guaranteed pickup timeline. `firstSeenAt` is durable but Crawler Analytics does not retain raw request events; page rollups retain 30 analytic days. Visibility also depends on supported User-Agent identification, delivery coverage, provider behavior, and source availability.

## Related pages

<CardGroup>
  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Report URL-level milestones.
  </Card>

  <Card title="Crawler Analytics" href="/documentation/measure/crawler-analytics">
    Review retained crawler observations and coverage.
  </Card>

  <Card title="Crawler configuration guide" href="https://www.qwairy.co/guides/complete-guide-to-robots-txt-and-llms-txt-for-ai-crawlers">
    Read additional technical guidance.
  </Card>

  <Card title="Campaign impact" href="/use-cases/campaigns/campaign-impact-on-ai-visibility">
    Compare stable campaign cohorts.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/sources/pages-with-most-ai-citations">
    Review recorded citation URLs.
  </Card>

  <Card title="Prioritize providers" href="/use-cases/setup/which-providers-to-prioritize">
    Choose the provider cohort to monitor.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Run an evidence-led publishing experiment.
  </Card>
</CardGroup>


# Where do my brand and a specific competitor overlap in AI recommendations?
Source: https://docs.qwairy.co/use-cases/competitors/brand-and-competitor-overlap

Compare co-appearance, SELF-only, competitor-only, and absent cases for one DIRECT competitor in a fixed scope.

## Direct answer

Choose one DIRECT competitor and compare answers or prompts where both brands appear, only your brand appears, only the competitor appears, or neither appears. State the unit before calculating overlap, then read the answers to determine whether co-appearance is a genuine recommendation.

## Data required

* Completed answers for a fixed prompt, provider, model, market, and period scope
* Correct SELF and selected DIRECT competitor classifications
* Mention detections for both brands
* A chosen unit: answers or distinct answered prompts
* Full answer text and exposed citations

## Workflow

1. Confirm that the selected brand is classified as a DIRECT competitor.
2. In **Cockpit > Compare**, apply the competitor and analysis filters.
3. Export or inspect the underlying records and assign each unit to both, SELF-only, competitor-only, or neither.
4. In **Cockpit > GEO Matrix**, locate the topics and prompts where the pattern is concentrated.
5. Read the matching answers in **Monitor > Response Analysis** to distinguish recommendation, comparison, criticism, and incidental mention.
6. Repeat for another period only with the same unit, prompt cohort, and competitor classification.

## Interpretation

Answer-level overlap and prompt-level overlap are not interchangeable. A prompt can have separate answers where each brand appears without any single answer containing both.

Product Share of Voice counts SELF and DIRECT mention occurrences; it does not measure co-appearance. Product Mention Rate is response-level and also does not provide an overlap cohort by itself.

## Possible next actions

* Test content that addresses a criterion recurring in competitor-only answers.
* Investigate a provider or topic where co-appearance differs from the rest of the dataset.
* Correct competitor aliases or relationships when detections are incomplete.
* Track the same overlap cohorts after a positioning experiment.

These actions test hypotheses and do not guarantee recommendation changes.

## Limitations

* Co-appearance does not mean the brands are equally recommended.
* Mention detection can be affected by aliases and ambiguous names.
* Small cohorts can change sharply between runs.
* Qwairy observations do not represent every provider interaction.

## Related pages

* [Compare competitors](/documentation/cockpit/compare)
* [Identify observed competitors](/use-cases/competitors/who-are-my-biggest-competitors)
* [Compare competitor sources](/use-cases/competitors/sources-cited-for-competitors-not-me)


# How do competitors rank vs my brand at each funnel stage?
Source: https://docs.qwairy.co/use-cases/competitors/competitors-by-funnel-stage

Compare SELF and DIRECT competitor observations by funnel stage with stable assignments, filters, and metric units.

## Direct answer

Use **Cockpit > Compare** with one funnel stage at a time. Compare a defined metric and its raw components, then inspect the prompts and answers behind the difference. No single metric represents rank across the full funnel.

## Data required

* Answered prompts with consistent funnel-stage assignments
* Correct SELF and DIRECT competitor classifications
* A fixed provider, model, country, language, topic, tag, and period scope
* Raw components for Mention Rate, Share of Voice, Coverage, and Avg Position
* Full answers contributing to each stage

## Workflow

1. In **Workspace > Prompts**, review funnel-stage assignments and unassigned prompts.
2. In **Cockpit > Compare**, select one stage and one metric.
3. Record the SELF and DIRECT competitor values with their numerators, denominators, or eligible counts.
4. Repeat for the remaining stages without changing other filters.
5. Use **Cockpit > GEO Matrix** and **Monitor > Prompt Tracking** to locate the contributing prompts.
6. Read those answers in **Monitor > Response Analysis** to verify recommendation context.

## Interpretation

Share of Voice is occurrence-level, Mention Rate is response-level, Coverage is prompt-level, and Avg Position is conditional on recorded positions. Each can produce a different ordering.

Define rank as the selected metric within the selected stage. Do not average these metrics together or treat a small stage sample as equivalent to a larger one.

## Possible next actions

* Test whether one decision criterion explains a competitor advantage at a specific stage.
* Correct inconsistent funnel assignments before changing content.
* Investigate provider or topic concentration behind the aggregate.
* Track a fixed funnel cohort after an experiment.

Treat any expected movement as a hypothesis.

## Limitations

* Funnel stages depend on your taxonomy.
* DIRECT competitor configuration affects eligible metrics.
* Answer volumes can differ between stages and providers.
* Observed rank does not establish market share, revenue impact, or causality.

## Related pages

* [Compare competitors](/documentation/cockpit/compare)
* [Locate funnel gaps](/use-cases/funnel/losing-to-competitors-by-funnel)
* [Assess purchase-intent presence](/use-cases/funnel/brand-in-purchase-intent)


# Which competitors outperform me on specific AI providers?
Source: https://docs.qwairy.co/use-cases/competitors/competitors-outperform-me-by-provider

Compare SELF and DIRECT competitor metrics by provider using matched prompts, models, samples, and answer context.

## Direct answer

Filter **Cockpit > Compare** to one provider and model at a time. Define outperform using a specific metric, preserve a matched prompt cohort, and trace the result to answers before ranking competitors.

## Data required

* Matched answered prompts across the providers or models being compared
* Correct SELF and DIRECT competitor classifications
* Fixed country, language, topic, tag, funnel, and period filters
* Raw components for the selected metric
* Representative answers and exposed citations

## Workflow

1. In **Cockpit > Compare**, select one provider, model, and metric.
2. Confirm comparable completed-answer and answered-prompt counts.
3. Record SELF and DIRECT competitor values with raw components.
4. Repeat for another provider without changing the remaining filters.
5. In **Cockpit > GEO Matrix**, locate topic and prompt cells driving the gap.
6. Read the underlying answers in **Monitor > Response Analysis** and inspect exposed sources when relevant.

## Interpretation

Product Share of Voice counts mention occurrences. Product Mention Rate is response-level. Product Coverage is prompt-level. Avg Position is conditional on recorded mention positions.

A competitor can outperform on one metric and not another. A provider with a smaller or different prompt sample is not directly comparable. State the provider, model, metric, filters, and unit with every conclusion.

## Possible next actions

* Test whether a provider-specific content or evidence gap persists on matched prompts.
* Investigate one topic or model rather than applying a broad competitive response.
* Review aliases and DIRECT relationships when denominator components look incomplete.
* Collect additional comparable answers before acting on a small sample.

These actions test hypotheses; they do not reveal or control private provider logic.

## Limitations

* Provider output varies between runs and models.
* Competitor classification affects eligible product metrics.
* Unequal samples can reverse rankings.
* Observed mentions do not establish recommendation quality or commercial performance.

## Related pages

* [Compare competitors](/documentation/cockpit/compare)
* [Compare provider scores](/use-cases/providers/different-scores-across-providers)
* [Identify observed competitors](/use-cases/competitors/who-are-my-biggest-competitors)


# Is a new competitor emerging that I should be aware of?
Source: https://docs.qwairy.co/use-cases/competitors/new-competitor-emerging

Detect sustained changes in observed competitor mentions across matched periods, then verify aliases, prompts, and context.

## Direct answer

Treat a brand as a candidate emerging competitor only when its observed presence increases across comparable prompts and periods. Verify aliases and answer context before adding or changing its competitor relationship. One mention is not a trend.

## Data required

* Competitor mentions from matched current and prior windows
* A fixed prompt, provider, model, country, language, topic, and funnel scope
* Mention occurrences, distinct answered prompts, and answer counts
* Known aliases and current competitor relationships
* Full answers where the candidate appears

## Workflow

1. In **Monitor > Competitor Mentions**, identify brands newly present or increasing in the selected scope.
2. Compare equal windows using the same prompt cohort and monitoring configuration.
3. Check whether the change appears across distinct prompts, topics, and providers rather than repeated mentions in one answer.
4. Read the matching answers in **Monitor > Response Analysis** to confirm that the entity is a relevant alternative.
5. Review aliases, subsidiaries, and ambiguous names.
6. If appropriate, classify the brand for future comparison and mark the date of that configuration change.

## Interpretation

Use both occurrence-level volume and prompt-level breadth. Repeated occurrences in one answer do not show broad emergence. A newly classified DIRECT competitor changes the eligible denominator for Product Mention Rate and Share of Voice, so trend continuity must be annotated.

Describe the result as an observed increase in the monitored dataset, not market entry or market-share growth.

## Possible next actions

* Add a candidate to a watchlist or DIRECT comparison as a reversible monitoring hypothesis.
* Test whether the pattern persists in another matched period.
* Investigate the topics and criteria where the candidate appears.
* Correct entity aliases before changing competitive strategy.

## Limitations

* Prompt or monitoring changes can create artificial emergence.
* Provider output can vary between runs.
* Entity detection can merge or split similarly named brands.
* Qwairy observations do not establish company growth, revenue, or market share.

## Related pages

* [Monitor competitor mentions](/documentation/monitor/competitor-mentions)
* [Identify observed competitors](/use-cases/competitors/who-are-my-biggest-competitors)
* [Track visibility changes](/use-cases/visibility/how-has-my-visibility-changed)


# How does my brand's sentiment compare to competitors?
Source: https://docs.qwairy.co/use-cases/competitors/sentiment-vs-competitors

Compare detected sentiment for SELF and competitor mentions using matched prompts, eligible counts, and full answer context.

## Direct answer

Compare sentiment only within the same prompt, provider, model, market, and time scope. Pair each aggregate with its eligible mention count and read the answers. Detected AI sentiment is not customer sentiment or factual accuracy.

## Data required

* Completed answers with SELF and competitor mentions
* Correct entity aliases and competitor relationships
* Detected sentiment values and eligible mention counts
* Fixed provider, model, country, language, topic, tag, funnel, and period filters
* Full answer text for contextual review

## Workflow

1. In **Analyze > Sentiment**, set a fixed analysis scope and inspect the SELF distribution.
2. In **Cockpit > Compare**, select the same scope and compare competitor sentiment.
3. Record each value with its eligible mention count.
4. Separate topics, prompts, or providers that contribute most to the difference.
5. Read positive, negative, mixed, and neutral cases in **Monitor > Response Analysis**.
6. Verify whether the language describes the brand, a product, an incident, or a quoted source.

## Interpretation

Sentiment summarizes detected language around eligible mentions. A difference can reflect prompt mix, small samples, or one repeated narrative. It does not show what users believe.

Pair sentiment with Mention Rate or Coverage. A favorable sentiment value from a small set of SELF mentions can coexist with broad brand absence. Do not rank brands without showing eligible counts.

## Possible next actions

* Test whether a negative pattern is concentrated in one factual claim or topic.
* Correct inaccurate public information with a clear authoritative source.
* Investigate provider-specific wording before changing positioning.
* Track a matched answer cohort after a corrective update.

These actions test associations and do not guarantee a sentiment change.

## Limitations

* Automated sentiment can miss nuance, conditional language, irony, and mixed evaluations.
* Competitors may have different eligible mention volumes.
* Answer variability can move small samples sharply.
* Sentiment does not measure recommendation, citation, reputation, or revenue.

## Related pages

* [Analyze sentiment](/documentation/analyze/sentiment-analysis)
* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Review negative topic sentiment](/use-cases/reputation/negative-sentiment-on-topics)


# Which sources are cited for my competitors but not for me?
Source: https://docs.qwairy.co/use-cases/competitors/sources-cited-for-competitors-not-me

Build answer-level competitor and SELF source cohorts to find domains or URLs observed only with competitor mentions.

## Direct answer

Compare exposed source domains and URLs within answers that mention a selected DIRECT competitor and answers that mention your brand. Use the same filters and state whether the comparison is answer-level, domain-level, or URL-level.

## Data required

* Completed answers in a fixed scope
* SELF and selected DIRECT competitor mention detections
* Exposed citation domains and URLs for those answers
* Correct SELF and DIRECT source classifications
* Full answer text and source context

## Workflow

1. In **Cockpit > Compare**, select one DIRECT competitor and a fixed analysis scope.
2. In **Monitor > Response Analysis**, identify competitor-mentioned and SELF-mentioned answer cohorts.
3. In **Monitor > Source Explorer** or an export, list the domains and URLs cited within each cohort.
4. Calculate competitor-only, shared, and SELF-only sets at one declared unit.
5. Read the answers to confirm that a competitor-only source is relevant to the recommendation or claim.
6. Review redirects, syndicated copies, subdomains, and duplicate URLs before prioritizing a source.

## Interpretation

A source cited in a competitor-mentioned answer is associated with that answer; it is not necessarily cited as evidence for the competitor. Product Citation Rate uses answers citing SELF sources over answers citing SELF or DIRECT sources and does not directly provide this cohort overlap.

Domain-level and URL-level gaps answer different questions. Keep citation frequency, answer count, and prompt breadth separate.

## Possible next actions

* Test outreach to a relevant independent source when your evidence belongs there.
* Improve a SELF page when the competitor-only source covers a criterion your site does not document.
* Correct a false gap caused by redirects, aliases, or domain classification.
* Track later citations in the same prompt cohort.

Treat backlinks and future citations as hypotheses; placement does not guarantee provider use.

## Limitations

* Qwairy records citations exposed with stored answers, not every source used internally.
* Co-occurrence does not prove that a source caused a competitor mention.
* Source sets can be sparse or unstable across runs.
* Editorial access and backlink feasibility are outside the observed dataset.

## Related pages

* [Explore content sources](/documentation/monitor/content-sources)
* [Review Backlink Opportunities](/documentation/act/backlink-opportunities)
* [Find backlink hypotheses](/use-cases/sources/backlink-opportunities-for-ai)


# What topics do my competitors own that I don't appear in?
Source: https://docs.qwairy.co/use-cases/competitors/topics-competitors-own-without-me

Define topic ownership with an observed metric, then trace competitor-only topic gaps to prompts, answers, and sources.

## Direct answer

Define own before comparing topics. A practical observed definition is a topic where a DIRECT competitor appears across answered prompts and your brand is absent or materially less present under the same scope. Verify prompt-level breadth and answer context.

## Data required

* Answered prompts assigned to stable topics
* Correct SELF and DIRECT competitor classifications
* Fixed provider, model, country, language, tag, funnel, and period filters
* Topic-level Coverage, Mention Rate, Share of Voice, and raw components
* Full answers and exposed sources for gap prompts

## Workflow

1. In **Workspace > Topics**, review unassigned prompts and topic boundaries.
2. In **Cockpit > Compare**, apply one topic at a time and select one comparison metric.
3. Record SELF and DIRECT competitor raw components.
4. In **Cockpit > GEO Matrix**, identify prompts where a competitor appears and SELF does not.
5. Read those answers in **Monitor > Response Analysis** and inspect relevant sources.
6. Review **Act > Content Opportunities** as a source of hypotheses, then validate each opportunity against the answers.

## Interpretation

Coverage is prompt-level, Mention Rate is response-level, and Share of Voice is occurrence-level. A competitor can lead on one and not another. State which metric defines the observed gap.

A topic with little data should not be labeled owned. Competitor presence can be incidental or negative, so inspect the underlying answer before prioritizing work.

## Possible next actions

* Test content for one missing prompt and buyer criterion with verifiable evidence.
* Split or merge a topic when taxonomy design creates the apparent gap.
* Investigate provider-specific gaps separately.
* Track a fixed topic cohort after the experiment.

Treat topic ownership as an operational observation, not a permanent market fact.

## Limitations

* Topic results depend on your prompt taxonomy.
* DIRECT competitor configuration changes eligible metrics.
* Small or uneven samples can exaggerate gaps.
* Observed presence does not prove expertise, preference, or commercial ownership.

## Related pages

* [Use Content Opportunities](/documentation/act/content-opportunities)
* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Plan content from observed gaps](/use-cases/content/what-content-to-create)


# Who are my biggest competitors in AI search results?
Source: https://docs.qwairy.co/use-cases/competitors/who-are-my-biggest-competitors

Identify the most visible observed alternatives by mention volume, prompt breadth, context, and DIRECT competitor relevance.

## Direct answer

Use **Monitor > Competitor Mentions** to find brands that appear in your monitored answers, then define biggest with an explicit metric. Confirm that each brand is a relevant alternative before classifying it as DIRECT.

## Data required

* Completed answers for a fixed prompt and provider scope
* Detected competitor entities, aliases, and mention occurrences
* Distinct answered prompts containing each competitor
* Current SELF, DIRECT, INDIRECT, and ignored relationships
* Full answer text showing competitive context

## Workflow

1. In **Monitor > Competitor Mentions**, set the period, provider, model, country, language, topic, and funnel scope.
2. Compare both mention occurrences and distinct answered-prompt breadth.
3. Read representative answers for the leading entities.
4. Exclude subsidiaries, products, ambiguous names, and unrelated brands that do not represent alternatives.
5. Classify relevant alternatives as DIRECT before using **Cockpit > Compare**.
6. Record the classification date because changing relationships affects Product Mention Rate and Share of Voice denominators.

## Interpretation

The result identifies competitors most present in the selected stored dataset. It does not identify the largest companies or complete market set. Repeated mentions in one answer can raise occurrence volume without broad prompt coverage.

Once competitors are classified as DIRECT, Product Share of Voice compares SELF mention occurrences with SELF plus DIRECT occurrences. Product Mention Rate uses answers with at least one SELF or DIRECT mention as its denominator.

## Possible next actions

* Add a relevant observed brand as DIRECT and monitor it as a reversible hypothesis.
* Merge aliases before ranking entities.
* Investigate the topics and providers where a competitor appears broadly.
* Ignore an entity when answer context shows it is not a competitive alternative.

## Limitations

* Entity detection can merge or split names.
* The monitored prompt set determines which competitors can be observed.
* Provider output varies between runs.
* Competitor presence does not establish market share, customer preference, or revenue.

## Related pages

* [Monitor competitor mentions](/documentation/monitor/competitor-mentions)
* [Compare competitors](/documentation/cockpit/compare)
* [Track a candidate emerging competitor](/use-cases/competitors/new-competitor-emerging)


# How do I turn a content gap into an article that AI models will cite?
Source: https://docs.qwairy.co/use-cases/content/content-gap-to-cited-article

Turn an observed content gap into a publishing experiment, then monitor stored answers and citations without assuming publication will earn coverage.

## Direct answer

Use **Act > Content Opportunities** to select a gap supported by your monitored data. Create accurate content for the underlying audience need, record a baseline, publish it, and then observe later answers and citations. Treat any change as an association to investigate, not proof that the article caused it.

## Data required

You need a stable set of configured prompts, the selected topic and provider filters, stored answers and citation URLs, the candidate page URL, and its publication date. Keep the same filters before and after publication. If you use the REST API, follow the endpoint contract rather than assuming it reproduces product metrics.

## Workflow

<Steps>
  <Step title="Define the observed gap">
    In Content Opportunities, choose a relevant topic where the selected stored answers show limited SELF presence. Read the underlying prompts and answers before deciding that new content is needed.
  </Step>

  <Step title="Review existing sources">
    Inspect Source Explorer and the referenced pages. Identify the user questions, evidence, formats, and source types present in the current dataset without treating them as universal ranking factors.
  </Step>

  <Step title="Create and publish">
    Use Content Studio or your editorial workflow to produce an accurate, useful page. Record the final URL, publication date, ownership, and the monitored prompts used for the baseline.
  </Step>

  <Step title="Observe later runs">
    After enough comparable monitoring runs, review the same prompt, provider, topic, and period filters. Record new SELF mentions and SELF citation URLs separately.
  </Step>
</Steps>

## Interpretation

A recorded citation means that a source URL appears with a stored answer. It does not imply a positive mention, a click, indexing across a provider, or future inclusion. In the product, Citation Rate is answers citing a SELF source divided by answers citing at least one SELF or DIRECT source. The REST source-URL endpoint has its own fields and filters.

## Possible next actions

* If the new page is crawled but not cited, test the hypothesis that its evidence, structure, or relevance does not match the observed need.
* If a different source is repeatedly cited, test whether an accurate first-party resource can address the same question more directly.
* If the gap exists only for one provider, review that provider slice before changing content across the whole site.

## Limitations

Third-party answer and citation behavior can change. Qwairy observes the selected stored dataset; it cannot guarantee that publication will produce a mention or citation. A before-and-after change may also reflect prompt, provider, competitor, or sampling changes.

## Related pages

<CardGroup>
  <Card title="Content Opportunities" href="/documentation/act/content-opportunities">
    Review the product workflow for observed content gaps.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Explore supported MCP workflows and their schemas.
  </Card>

  <Card title="Source URLs API" href="/developers/endpoints/source-urls">
    Read the separate REST contract for source URL data.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Prioritize content hypotheses from observed gaps.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/content/pages-most-cited-by-ai">
    Review citation URLs already present in stored answers.
  </Card>

  <Card title="Keywords for AI research" href="/use-cases/content/keywords-to-target-for-ai">
    Combine planning terms with observed prompt and search data.
  </Card>

  <Card title="Provider mentions" href="/use-cases/visibility/which-providers-mention-my-brand">
    Compare SELF mentions across provider slices.
  </Card>
</CardGroup>


# What keywords should I target to appear in more AI answers?
Source: https://docs.qwairy.co/use-cases/content/keywords-to-target-for-ai

Build a research list from prompts, observed search queries, citations, and GSC data without treating keywords as guaranteed AI targeting signals.

## Direct answer

Use keywords as research labels, not as a promise of inclusion in AI answers. Combine configured prompts, observed Query Fan-Out records, citation-source language, and Google Search Console data to identify audience needs worth testing with content.

## Data required

Use your configured prompts, topics and tags, stored answers, observed Query Fan-Out records, Source Explorer, and connected Google Search Console queries. Keep GSC search queries distinct from Qwairy prompts and from provider-generated web queries.

## Workflow

<Steps>
  <Step title="Collect candidate language">
    Export relevant prompts, observed web queries, source titles, and GSC queries for a defined topic and period.
  </Step>

  <Step title="Group by audience need">
    Cluster terms by the question or decision they represent. Use topics as the primary semantic grouping and tags as reusable secondary labels.
  </Step>

  <Step title="Check current evidence">
    Read the stored answers and cited sources for each group. Note where your brand or first-party sources are present, absent, or represented inaccurately.
  </Step>

  <Step title="Prioritize tests">
    Select terms that are relevant to the business and supported by observed demand or coverage gaps. Define the content change and the metric slice you will monitor.
  </Step>
</Steps>

## Interpretation

A keyword list is a planning artifact. It does not show the exact input a model used or guarantee a citation. Evaluate changes on stable prompt and provider cohorts. Product Mention Rate is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention; it is not a keyword ranking metric.

## Possible next actions

* If GSC demand is present but SELF citations are limited, test content that answers the same audience need with verifiable evidence.
* If Query Fan-Out reveals recurring observed searches, consider adding a representative configured prompt before creating content.
* If one topic contains unrelated intents, split the topic and keep cross-cutting labels as tags.

## Limitations

Query Fan-Out is an observed subset, not an exhaustive list of what people or models search for. GSC and Qwairy measure different surfaces. Correlation between a term, a ranking, and an AI citation does not establish causation.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export the selected dataset for research.
  </Card>

  <Card title="Keyword Performance" href="/looker-studio/sources/keyword-performance">
    Review the Looker Studio source for keyword reporting.
  </Card>

  <Card title="Google Search Console" href="/documentation/measure/google-search-console">
    Understand the connected traditional-search data.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Turn a research list into content hypotheses.
  </Card>

  <Card title="Google rank versus AI presence" href="/use-cases/content/rank-in-google-invisible-in-ai">
    Compare two distinct measurement surfaces.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Run a documented publishing experiment.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/content/pages-most-cited-by-ai">
    Inspect the URLs recorded as citations.
  </Card>
</CardGroup>


# Which of my existing pages are most frequently cited by AI?
Source: https://docs.qwairy.co/use-cases/content/pages-most-cited-by-ai

Rank citation URLs in the selected stored answers, then inspect their prompts, providers, topics, and time periods before drawing conclusions.

## Direct answer

Open **Monitor > Source Explorer** and rank your own source URLs within a defined period and filter set. Then inspect the answers and prompts behind each URL. A high count describes the selected stored dataset; it does not prove page quality, traffic, or future citation behavior.

## Data required

Use stored answers, recorded citation URLs, SELF and DIRECT source classification, configured prompts, providers, topics, tags, and a fixed period. Use Page Performance or GSC only as separate contextual datasets.

## Workflow

<Steps>
  <Step title="Set a comparable scope">
    Choose the period, providers, topics, and prompt set. Keep those filters visible when comparing URLs.
  </Step>

  <Step title="Rank SELF source URLs">
    In Source Explorer, filter to your domains and review citation occurrences and distinct answers. Do not combine these units.
  </Step>

  <Step title="Inspect supporting answers">
    Open representative answers for each leading URL and note the prompt, provider, topic, surrounding claims, and other cited sources.
  </Step>

  <Step title="Compare with page context">
    Review Page Performance or connected GSC data separately to identify pages worth investigating, without merging unlike metrics into a single conclusion.
  </Step>
</Steps>

## Interpretation

A citation is a source URL recorded with an answer; it neither implies a mention nor confirms a click. In the product, Citation Rate is answers citing a SELF source divided by answers citing at least one SELF or DIRECT source. Counts can be concentrated in repeated prompts, providers, or topics, so inspect distribution as well as totals.

## Possible next actions

* If one page appears across several relevant prompt and provider slices, test whether its evidence or format can inform other pages.
* If citation counts come from one narrow prompt group, avoid generalizing the pattern to the whole site.
* If an important page is absent, test whether another first-party page better answers the observed questions.

## Limitations

Qwairy observes citations in selected stored answers, not the complete output of any provider. Citation counts are sensitive to monitoring configuration and period. The REST source-URL endpoint is a separate contract; verify its fields, filters, and units before comparing it with the product.

## Related pages

<CardGroup>
  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Build reporting from the documented Looker Studio source.
  </Card>

  <Card title="Source URLs API" href="/developers/endpoints/source-urls">
    Use the endpoint's documented fields and units.
  </Card>

  <Card title="Source Explorer" href="/documentation/monitor/content-sources">
    Review citation-source behavior in the product.
  </Card>

  <Card title="Visibility over time" href="/use-cases/visibility/how-has-my-visibility-changed">
    Compare stable cohorts across periods.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Test a publishing hypothesis.
  </Card>

  <Card title="Provider mentions" href="/use-cases/visibility/which-providers-mention-my-brand">
    Analyze mentions separately from citations.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Prioritize content using observed evidence.
  </Card>
</CardGroup>


# Which queries do AI models search for where my brand is absent?
Source: https://docs.qwairy.co/use-cases/content/queries-llms-search-without-me

Review observed Query Fan-Out searches and the associated stored answers to find relevant cases without a SELF mention.

## Direct answer

Use **Monitor > Insights > Query Fan-Out** to inspect web queries observed during monitored activity, then open the associated stored answers. Mark a gap only when the audience need is relevant and no SELF mention appears in that selected answer set.

## Data required

You need observed Query Fan-Out records, their associated configured prompts and stored answers, provider, topic or tag, period, and SELF/DIRECT classifications. GSC queries are a separate traditional-search dataset.

## Workflow

<Steps>
  <Step title="Choose a relevant scope">
    Filter to a business-relevant topic, provider set, and period. Exclude observed searches unrelated to your product or audience.
  </Step>

  <Step title="Inspect observed searches">
    Review the recorded web queries and group them by audience need. Do not treat the list as a universal query inventory.
  </Step>

  <Step title="Check the associated answers">
    Read the stored answers and identify whether SELF, DIRECT, or neither is mentioned. Keep mentions separate from citation URLs.
  </Step>

  <Step title="Create a monitoring decision">
    Add a representative configured prompt only when the gap is important enough to track consistently. Record why it was selected.
  </Step>
</Steps>

## Interpretation

Query Fan-Out represents observed web searches, while a prompt is the configured question Qwairy monitors. Product Coverage is distinct answered prompts with at least one SELF mention divided by distinct answered prompts. That metric does not measure the share of all possible web queries.

## Possible next actions

* If several observed searches express the same unmet need, test one representative prompt before expanding the monitoring set.
* If DIRECT brands appear but SELF does not, inspect their cited sources and positioning as hypotheses for further research.
* If a query is relevant but unsupported by your existing content, evaluate a content experiment with a documented baseline.

## Limitations

Observed Query Fan-Out data is partial and provider-dependent. Absence in selected stored answers does not mean the brand is absent from every answer or search. Adding prompts changes the monitored dataset and can affect later aggregate comparisons.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export a filtered dataset for review.
  </Card>

  <Card title="Search Insights" href="/looker-studio/sources/search-insights">
    Report on the documented search-insights source.
  </Card>

  <Card title="Query Fan-Out" href="/documentation/monitor/insights/query-fan-out">
    Understand observed web query data.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Turn a relevant gap into a content hypothesis.
  </Card>

  <Card title="Keywords for AI research" href="/use-cases/content/keywords-to-target-for-ai">
    Build a research vocabulary without conflating units.
  </Card>

  <Card title="Visibility over time" href="/use-cases/visibility/how-has-my-visibility-changed">
    Compare stable monitored cohorts.
  </Card>
</CardGroup>


# Are there topics where I rank well in Google but am invisible in AI?
Source: https://docs.qwairy.co/use-cases/content/rank-in-google-invisible-in-ai

Compare connected GSC data with Qwairy's stored answers and citations while keeping the two measurement surfaces separate.

## Direct answer

Yes, the two datasets can diverge. Use connected Google Search Console data to identify strong traditional-search pages or queries, then examine the corresponding Qwairy prompts, stored answers, SELF mentions, and citation URLs. The comparison identifies investigation candidates, not a causal relationship.

## Data required

Use a fixed GSC period and property, relevant pages and search queries, a matched Qwairy topic or prompt set, stored answers, providers, SELF/DIRECT classifications, and citation URLs. Document how you matched a GSC query to a Qwairy prompt.

## Workflow

<Steps>
  <Step title="Select the GSC cohort">
    Choose pages or queries with meaningful impressions or positions for a defined period. Record the property, country, device, and other available filters.
  </Step>

  <Step title="Match the monitored topic">
    Map the search intent to existing configured prompts. Do not rename GSC queries as prompts or assume a one-to-one match.
  </Step>

  <Step title="Inspect Qwairy evidence">
    Review stored answers, SELF mentions, and SELF citation URLs for the same topic and comparable period.
  </Step>

  <Step title="Classify the divergence">
    Separate cases with no SELF mention, a SELF mention without a citation, and a citation to another page. Each suggests a different hypothesis.
  </Step>
</Steps>

## Interpretation

GSC ranking and Qwairy visibility measure different systems. In the product, Mention Rate is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. Citation Rate uses answers citing SELF over answers citing at least one SELF or DIRECT source. Neither is a Google ranking measure.

## Possible next actions

* If a ranking page is not cited, test whether a different page better answers the monitored prompt.
* If SELF is mentioned without a SELF source, test a clearer first-party evidence page for the observed need.
* If the divergence is isolated to one provider, review that provider's stored answers before making site-wide changes.

## Limitations

A Google ranking does not cause an AI mention or citation, and an AI citation does not predict a Google ranking. Connected GSC and Qwairy datasets can differ in geography, period, sampling, and intent. Preserve those differences in any report.

## Related pages

<CardGroup>
  <Card title="Google Search Console" href="/documentation/measure/google-search-console">
    Review the connected traditional-search dataset.
  </Card>

  <Card title="Search Insights" href="/looker-studio/sources/search-insights">
    Build a cross-surface report with documented units.
  </Card>

  <Card title="GEO guide" href="https://www.qwairy.co/guides/complete-guide-to-generative-engine-optimization">
    Read additional background on generative engine optimization.
  </Card>

  <Card title="Keywords for AI research" href="/use-cases/content/keywords-to-target-for-ai">
    Develop research terms from distinct datasets.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Prioritize a content experiment.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/content/pages-most-cited-by-ai">
    Inspect citation URLs in stored answers.
  </Card>

  <Card title="Traffic by AI platform" href="/use-cases/impact/traffic-from-each-ai-platform">
    Analyze observed referral traffic separately.
  </Card>
</CardGroup>


# What content should I create to improve my AI visibility?
Source: https://docs.qwairy.co/use-cases/content/what-content-to-create

Prioritize content hypotheses from relevant prompt gaps, stored answers, observed searches, and cited sources, without promising visibility gains.

## Direct answer

Start with a relevant audience question that your current first-party content does not answer well. Use **Act > Content Opportunities**, Query Fan-Out, stored answers, and Source Explorer to document the gap, then prioritize a content experiment based on business relevance and available evidence.

## Data required

Use configured prompts, topics and tags, stored answers, SELF/DIRECT mentions, citation URLs, observed Query Fan-Out records, current first-party pages, and a stable baseline period. Add product or subject-matter evidence before drafting.

## Workflow

<Steps>
  <Step title="Confirm the audience need">
    Read the underlying prompts and answers. Exclude gaps that are outside your positioning or cannot be supported accurately.
  </Step>

  <Step title="Review the current source set">
    Inspect cited pages and existing first-party content. Identify missing evidence, scope, or format without assuming a universal citation pattern.
  </Step>

  <Step title="Define the content hypothesis">
    State the audience question, intended page, evidence owner, and the prompt and provider cohort you will observe after publication.
  </Step>

  <Step title="Publish and monitor">
    Create the page in Content Studio or your editorial system, record the URL and date, and compare later runs using the same cohort.
  </Step>
</Steps>

## Interpretation

Prioritization should combine business relevance, observed coverage gaps, and the ability to publish accurate evidence. A recorded citation is a URL associated with a stored answer; it does not guarantee positive portrayal, referral traffic, or continued inclusion.

## Possible next actions

* If a gap reflects an unanswered factual question, test a maintained reference page with primary evidence.
* If competitors are cited for comparisons, test an accurate comparison page that states scope and limitations.
* If the need is already covered by a strong page, test updating or consolidating it before creating another URL.

## Limitations

No content format, keyword, or publishing cadence guarantees a mention or citation. Qwairy observes a selected prompt and provider dataset, not all possible answers. Changes after publication may have other causes, so retain the baseline and note concurrent work.

## Related pages

<CardGroup>
  <Card title="Content Opportunities" href="/documentation/act/content-opportunities">
    Review observed opportunities in the product.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Use supported MCP workflows with their documented schemas.
  </Card>

  <Card title="GEO guide" href="https://www.qwairy.co/guides/complete-guide-to-generative-engine-optimization">
    Read additional content-planning guidance.
  </Card>

  <Card title="Queries without SELF" href="/use-cases/content/queries-llms-search-without-me">
    Review relevant observed search gaps.
  </Card>

  <Card title="Keywords for AI research" href="/use-cases/content/keywords-to-target-for-ai">
    Build a research list from distinct data sources.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Run a documented publishing experiment.
  </Card>

  <Card title="Google rank versus AI presence" href="/use-cases/content/rank-in-google-invisible-in-ai">
    Investigate cross-surface divergence.
  </Card>
</CardGroup>


# Does AI recommend my brand in the comparison/consideration phase?
Source: https://docs.qwairy.co/use-cases/funnel/brand-in-consideration-phase

Filter consideration-stage prompts and inspect whether observed answers include, compare, or recommend your brand.

## Direct answer

Filter to prompts assigned to the consideration or MOFU stage, then inspect both presence metrics and the full answers. A SELF mention does not by itself mean that the provider recommends your brand.

## Data required

* Answered prompts consistently assigned to the consideration or MOFU stage
* SELF and DIRECT competitor classifications
* A fixed provider, model, country, language, topic, tag, and period scope
* Mention Rate, Coverage, Share of Voice, and raw components
* Answer text showing comparison criteria and recommendation context

## Workflow

1. In **Workspace > Prompts**, review the funnel-stage assignments for comparison and evaluation prompts.
2. In **Cockpit > GEO Matrix**, filter to the consideration or MOFU stage and record Coverage and Mention Rate.
3. In **Cockpit > Compare**, use the same filter to review Share of Voice and DIRECT competitor presence.
4. In **Monitor > Prompt Tracking**, locate prompts where your brand is absent or appears inconsistently.
5. Read those answers in **Monitor > Response Analysis** and classify the context as included, compared, recommended, discouraged, or incidental.
6. Compare providers or topics only with matched prompt and answer coverage.

## Interpretation

Product Coverage is prompt-level, while Product Mention Rate is response-level. Product Share of Voice counts mention occurrences. None of these metrics alone measures recommendation.

Use answer context to determine whether your brand is genuinely considered and which criteria are applied. A high aggregate can be driven by repeated mentions in a narrow set of prompts.

## Possible next actions

* Test whether a comparison page addresses a recurring criterion with verifiable evidence.
* Investigate a topic where your brand is mentioned but not shortlisted.
* Correct outdated claims found in observed answers or exposed sources.
* Track a fixed consideration-stage cohort after a positioning change.

Treat each action as a hypothesis; providers control future outputs.

## Limitations

* Funnel stages reflect your prompt taxonomy and require consistent judgment.
* Recommendation context cannot be inferred from mention counts alone.
* Provider and model output can vary between runs.
* The monitored prompt set does not represent every consideration journey.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Compare competitors](/documentation/cockpit/compare)
* [Assess purchase-intent presence](/use-cases/funnel/brand-in-purchase-intent)


# Is my brand present in AI responses for purchase-intent queries?
Source: https://docs.qwairy.co/use-cases/funnel/brand-in-purchase-intent

Filter purchase-intent prompts and verify brand presence, recommendation context, competitors, and exposed sources.

## Direct answer

Filter to prompts assigned to the purchase-intent or BOFU stage. Measure SELF presence, then read the answers to determine whether the brand is recommended, compared, excluded, or merely named.

## Data required

* Answered prompts consistently assigned to the purchase-intent or BOFU stage
* SELF and DIRECT competitor classifications
* A fixed provider, model, country, language, topic, tag, and period scope
* Coverage, Mention Rate, Share of Voice, position, and raw eligible counts
* Full answer text and exposed citations

## Workflow

1. In **Workspace > Prompts**, confirm that purchase-intent prompts ask for a concrete decision without forcing your brand into the wording.
2. In **Cockpit > GEO Matrix**, apply the purchase-intent or BOFU filter.
3. Record Coverage and Mention Rate with their prompt-level and response-level denominators.
4. In **Cockpit > Compare**, inspect DIRECT competitors and Share of Voice under the same scope.
5. Read missing and present cases in **Monitor > Response Analysis** to verify recommendation context.
6. Review exposed sources in **Monitor > Source Explorer** when an answer relies on outdated or unsupported facts.

## Interpretation

Presence is not purchase intent, endorsement, or conversion. Product Coverage shows the share of distinct answered prompts with at least one SELF mention. Product Mention Rate shows SELF-mentioned answers among answers with a SELF or DIRECT mention.

Avg Position, when available, is conditional on recorded SELF positions and excludes absences. Pair it with Coverage so a better average cannot hide disappearing mentions.

## Possible next actions

* Test whether a product or pricing page clearly supports a recurring selection criterion.
* Correct factual gaps found in decision-stage answers.
* Investigate provider-specific absence before changing broad positioning.
* Track the same purchase-intent prompt cohort after a page update.

Treat expected visibility or recommendation changes as hypotheses.

## Limitations

* Funnel-stage assignments are editorial, not observed user intent.
* A monitored prompt is not evidence of real purchase demand.
* AI recommendation does not prove traffic or conversion.
* Providers can change answers and citations between runs.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Compare consideration-stage presence](/use-cases/funnel/brand-in-consideration-phase)
* [Locate funnel competitor gaps](/use-cases/funnel/losing-to-competitors-by-funnel)


# Where in the funnel am I losing to competitors?
Source: https://docs.qwairy.co/use-cases/funnel/losing-to-competitors-by-funnel

Compare SELF and DIRECT competitor observations by funnel stage with matched prompts, answers, and metric units.

## Direct answer

Use **Cockpit > Compare** with one funnel stage at a time. Identify where DIRECT competitors have more observed presence, then trace the difference to prompts and answers. Define what losing means before ranking stages.

## Data required

* Answered prompts with consistent funnel-stage assignments
* Correct SELF and DIRECT competitor relationships
* Matched provider, model, country, language, topic, tag, and period filters
* Mention Rate, Coverage, Share of Voice, position, and their raw components
* Full answers for the prompts contributing to each gap

## Workflow

1. In **Workspace > Prompts**, review missing or inconsistent funnel-stage assignments.
2. In **Cockpit > Compare**, select a funnel stage and one metric.
3. Record the SELF and DIRECT competitor values with their raw counts.
4. Repeat for the other stages without changing the remaining filters.
5. In **Cockpit > GEO Matrix**, locate the topic and prompt cells behind the largest observed difference.
6. Read those answers in **Monitor > Response Analysis** to check recommendation context and relevance.

## Interpretation

Product Share of Voice is occurrence-level, Product Mention Rate is response-level, and Product Coverage is prompt-level. They can identify different stages as the largest gap. Do not combine them without an approved method.

A stage with a small answer sample may show a large percentage difference. A competitor mention can be negative or incidental, so answer context determines whether the observed gap is strategically relevant.

## Possible next actions

* Test a content change against the specific prompt and decision criterion behind the gap.
* Improve funnel-stage assignments when taxonomy quality explains the difference.
* Investigate one provider or topic instead of applying a site-wide response.
* Track the same prompt cohort after the experiment.

These actions test hypotheses and do not guarantee future provider behavior.

## Limitations

* Funnel-stage assignment depends on your taxonomy.
* Competitor metrics depend on DIRECT relationship configuration.
* Unequal samples can distort stage comparisons.
* Visibility differences do not establish commercial loss or causality.

## Related pages

* [Compare competitors](/documentation/cockpit/compare)
* [Compare competitors by funnel stage](/use-cases/competitors/competitors-by-funnel-stage)
* [Measure Share of Voice](/use-cases/visibility/what-is-my-share-of-voice)


# How visible is my brand at the top of the funnel in AI search?
Source: https://docs.qwairy.co/use-cases/funnel/visibility-top-of-funnel

Filter awareness-stage prompts and compare prompt Coverage, response-level Mention Rate, and answer relevance.

## Direct answer

Filter to prompts assigned to the awareness or TOFU stage. Use Coverage to see how broadly your brand appears across answered prompts, Mention Rate to assess eligible answers, and answer text to decide whether the mention is relevant.

## Data required

* Answered prompts consistently assigned to the awareness or TOFU stage
* SELF and DIRECT competitor classifications
* A fixed provider, model, country, language, topic, tag, and period scope
* Coverage and Mention Rate raw components
* Representative answers with and without SELF mentions

## Workflow

1. In **Workspace > Prompts**, verify that awareness prompts are category-neutral and informational.
2. In **Cockpit > GEO Matrix**, apply the awareness or TOFU filter and record Coverage and Mention Rate.
3. Compare topics and providers one at a time while preserving the rest of the scope.
4. In **Monitor > Prompt Tracking**, identify prompts driving presence or absence.
5. Read the matching answers in **Monitor > Response Analysis** to check whether the brand belongs in the context.
6. Compare with consideration-stage results only after matching prompt volume and answer coverage.

## Interpretation

Product Coverage is prompt-level: distinct answered prompts with at least one SELF mention divided by distinct answered prompts. Product Mention Rate is response-level: answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention.

Low brand presence can be expected for broad educational prompts where naming vendors is not relevant. High presence can also be incidental. Use prompt intent and answer context before calling either result strong or weak.

## Possible next actions

* Test educational content that answers a recurring category question with verifiable evidence.
* Remove or rewrite an awareness prompt that does not match the category decision you intend to study.
* Investigate a topic-specific absence before expanding the prompt set.
* Track a fixed awareness cohort after the experiment.

Treat each expected metric change as a hypothesis.

## Limitations

* Awareness-stage labels depend on your prompt taxonomy.
* The monitored prompt set does not measure all discovery behavior.
* Presence does not imply trust, citation, or future purchase.
* Provider output can vary between runs.

## Related pages

* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Assess consideration-stage presence](/use-cases/funnel/brand-in-consideration-phase)
* [Assess overall AI visibility](/use-cases/visibility/how-visible-is-my-brand-in-ai)


# How do I build an executive report on AI visibility performance?
Source: https://docs.qwairy.co/use-cases/impact/build-executive-report

Build a concise report from stable Qwairy cohorts, explicit metric definitions, observed changes, limitations, and accountable next actions.

## Direct answer

Start with the decisions the report should support. Select a small set of product metrics, traffic observations, and qualitative findings; document every filter and denominator; then use Exports, Looker Studio, or Shared Links to present a reproducible view.

## Data required

Use a fixed reporting period, stable prompt cohort, providers and models, topics or tags, SELF/DIRECT classifications, stored answers and citations, any connected traffic data, and the previous comparable period. Record the source and formula for every metric.

## Workflow

<Steps>
  <Step title="Define the audience and decision">
    State whether the report supports brand monitoring, content prioritization, technical work, or commercial measurement. Exclude metrics that do not inform that decision.
  </Step>

  <Step title="Freeze the cohort">
    Record prompts, providers, models, topics, geography, and period. Note changes from the comparison period.
  </Step>

  <Step title="Build the evidence set">
    Combine product metrics with representative answers and separate traffic observations. Use Exports or documented Looker Studio sources.
  </Step>

  <Step title="Write the narrative">
    Report what changed, where it changed, material limitations, and a short list of owners and testable next actions.
  </Step>
</Steps>

## Interpretation

Product metrics must retain their exact numerator, denominator, filters, and unit. Mentions, citations, Share of Voice, Coverage, sentiment, crawler occurrences, and referral sessions answer different questions. A change in one should not be described as causing a change in another.

## Possible next actions

* If one metric moves sharply, test whether the prompt, provider, model, or competitor mix changed before assigning an owner.
* If an executive question lacks a valid measure, label it as an open question instead of substituting a proxy.
* If recurring reporting is needed, test a Looker Studio or API workflow with documented field mappings.

## Limitations

Qwairy observes configured prompts and stored provider outputs. Results are not exhaustive and can change with models, sources, and monitoring configuration. The REST API is a separate contract; verify endpoint fields and formulas before combining API and product data.

## Related pages

<CardGroup>
  <Card title="Looker Studio setup" href="/looker-studio/getting-started">
    Connect documented data sources for reporting.
  </Card>

  <Card title="REST API" href="/developers/introduction">
    Review API authentication, resources, and contracts.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered product view.
  </Card>

  <Card title="KPIs for GEO" href="/use-cases/impact/kpis-for-geo-success">
    Choose metrics with explicit definitions.
  </Card>

  <Card title="ROI comparison" href="/use-cases/impact/roi-geo-vs-traditional-seo">
    Build an assumption-led commercial view.
  </Card>
</CardGroup>


# Is AI visibility actually driving traffic to my website?
Source: https://docs.qwairy.co/use-cases/impact/is-ai-driving-traffic

Compare observed AI referral sessions with visibility data while keeping referral attribution, correlation, and causation distinct.

## Direct answer

Use **Measure > Referrer Analytics** to identify sessions whose recorded referrer is classified as an AI platform. Compare those observations with visibility metrics on aligned periods, but do not claim that a mention or citation caused the visit unless you have a separate attribution design.

## Data required

Use connected analytics or referrer data, AI-platform classification, landing page, session date, relevant conversions if available, and a comparable Qwairy prompt, provider, topic, and period cohort. Preserve the traffic source's own attribution rules.

## Workflow

<Steps>
  <Step title="Validate the traffic source">
    Confirm the analytics connection, property, timezone, consent configuration, and the referrer classification used by Referrer Analytics.
  </Step>

  <Step title="Review observed AI referrals">
    Compare sessions by platform, landing page, and period. Keep direct, unknown, or missing referrers outside the AI-referral total unless your source explicitly classifies them.
  </Step>

  <Step title="Align visibility context">
    Review mentions and citations for a comparable period and provider set. Do not merge answer counts with session counts.
  </Step>

  <Step title="Inspect outcomes separately">
    Where connected data supports it, compare engagement or conversion measures for AI-referred sessions using the analytics system's definitions.
  </Step>
</Steps>

## Interpretation

An AI referral session is traffic with a recognized referrer under the connected analytics rules. It is not equivalent to a SELF mention or citation in a stored answer. Similar movement across the two datasets is correlation and may justify further investigation.

## Possible next actions

* If AI referrals rise on a specific page, test which external referrer and landing-page experience are associated with the change.
* If citations are observed without recognized traffic, verify whether the cited URL is clickable and whether referrer data is available.
* If traffic is material but conversions are unknown, test a privacy-compliant attribution setup before estimating business value.

## Limitations

Referrer data can be absent, stripped, grouped, or affected by consent and analytics configuration. Qwairy cannot observe every user journey or prove which answer generated a visit. The REST performance endpoint is not a traffic endpoint and uses its own contract.

## Related pages

<CardGroup>
  <Card title="Referrer Analytics" href="/documentation/measure/referrer-analytics">
    Review observed AI referral traffic in the product.
  </Card>

  <Card title="Performance Overview" href="/looker-studio/sources/performance-overview">
    Build a report with documented dimensions.
  </Card>

  <Card title="Performance API" href="/developers/endpoints/performance">
    Read the separate REST performance contract.
  </Card>

  <Card title="Traffic by platform" href="/use-cases/impact/traffic-from-each-ai-platform">
    Break down recognized AI referrers.
  </Card>

  <Card title="Traffic by page" href="/use-cases/impact/pages-with-most-ai-traffic">
    Compare AI-referred landing pages.
  </Card>

  <Card title="KPIs for GEO" href="/use-cases/impact/kpis-for-geo-success">
    Keep visibility and traffic metrics distinct.
  </Card>

  <Card title="ROI comparison" href="/use-cases/impact/roi-geo-vs-traditional-seo">
    Add explicit value and cost assumptions.
  </Card>
</CardGroup>


# What KPIs should I track to measure GEO success?
Source: https://docs.qwairy.co/use-cases/impact/kpis-for-geo-success

Choose product visibility, answer quality, traffic, and business metrics with explicit formulas, cohorts, and limitations.

## Direct answer

Track only metrics tied to a decision. For visibility, use Qwairy's product definitions exactly. Add answer-level evidence, observed AI referral traffic, or business outcomes as separate layers rather than combining them into an undocumented score.

## Data required

Define the brand classifications, DIRECT competitors, prompt cohort, providers and models, topics or tags, period, stored answers and citations, and any connected traffic or conversion source. Record every numerator, denominator, filter, and unit.

## Workflow

<Steps>
  <Step title="Define the objective">
    Choose whether you are measuring brand presence, source presence, competitive occurrence, prompt coverage, narrative quality, traffic, or commercial outcomes.
  </Step>

  <Step title="Select the metric set">
    Use the smallest set that covers the objective and add representative stored answers for context.
  </Step>

  <Step title="Freeze the cohort">
    Record prompt, provider, model, topic, geography, and period filters. Keep comparison periods comparable.
  </Step>

  <Step title="Set review rules">
    Assign an owner, cadence, data-quality checks, and the decision each metric can trigger. Use your own baseline instead of a universal threshold.
  </Step>
</Steps>

## Interpretation

Product **Mention Rate** is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. **Citation Rate** is answers citing a SELF source divided by answers citing at least one SELF or DIRECT source. **Share of Voice** is SELF mention occurrences divided by SELF plus DIRECT occurrences. **Coverage** is distinct answered prompts with at least one SELF mention divided by distinct answered prompts.

## Possible next actions

* If Coverage changes, test whether the answered-prompt cohort changed before interpreting brand performance.
* If Mention Rate and Citation Rate diverge, inspect answers because a mention and a citation do not imply one another.
* If referral sessions move independently of visibility metrics, investigate attribution and page-level context rather than forcing a single explanation.

## Limitations

No universal KPI threshold defines success across brands, markets, or prompt sets. Product formulas must not be reused for the REST API without verification; REST performance coverage is answers with a SELF mention divided by all returned answers. Traffic and business outcomes use their source systems' definitions.

## Related pages

<CardGroup>
  <Card title="Performance Overview" href="/looker-studio/sources/performance-overview">
    Build a KPI report from documented data.
  </Card>

  <Card title="Overview" href="/documentation/cockpit/performance-dashboard">
    Review product visibility metrics.
  </Card>

  <Card title="Qwairy videos" href="https://www.youtube.com/@TryQwairy">
    Browse product education videos.
  </Card>

  <Card title="Brand visibility" href="/use-cases/visibility/how-visible-is-my-brand-in-ai">
    Apply product visibility definitions.
  </Card>

  <Card title="Executive report" href="/use-cases/impact/build-executive-report">
    Present a reproducible metric narrative.
  </Card>

  <Card title="ROI comparison" href="/use-cases/impact/roi-geo-vs-traditional-seo">
    Connect measured outcomes to explicit assumptions.
  </Card>
</CardGroup>


# Which of my pages receive the most AI-driven traffic?
Source: https://docs.qwairy.co/use-cases/impact/pages-with-most-ai-traffic

Rank landing pages by observed sessions from recognized AI referrers, then review page context and attribution limitations.

## Direct answer

Use **Measure > Page Performance** or Referrer Analytics to rank landing pages by sessions whose referrer is classified as an AI platform. Keep the selected period, property, and traffic unit visible, and analyze citations as a separate dataset.

## Data required

Use connected analytics or referrer records, AI-platform classification, landing-page URL, session date, engagement or conversion fields if available, and URL normalization rules. For context, use separate Qwairy citation and crawler records.

## Workflow

<Steps>
  <Step title="Validate the connection">
    Confirm the analytics property, timezone, consent setup, URL normalization, and selected traffic unit.
  </Step>

  <Step title="Rank landing pages">
    Choose a period and sort pages by observed AI-referred sessions. Separate totals, users, and conversions rather than treating them as interchangeable.
  </Step>

  <Step title="Inspect platform mix">
    Review which recognized AI referrers are associated with each landing page and whether one source dominates the total.
  </Step>

  <Step title="Add page context">
    Compare citation URLs, crawler observations, and page purpose separately to form hypotheses about the traffic pattern.
  </Step>
</Steps>

## Interpretation

A leading page is a frequent landing page for recognized AI referrals in the selected analytics dataset. It is not necessarily the most cited page, the best-converting page, or the page that caused the referral. A recorded citation does not confirm a click.

## Possible next actions

* If a high-traffic page has weak engagement, test whether its content and call to action match the incoming audience need.
* If a strategic page receives no recognized AI referrals, verify URL grouping and referrer availability before changing content.
* If one platform dominates, test platform-specific landing-page and answer context rather than generalizing across providers.

## Limitations

Referrers may be missing or stripped, and analytics settings can change counts. URL parameters, redirects, and canonicalization can split page totals. Qwairy observes only connected data and cannot reconstruct every AI-assisted visit.

## Related pages

<CardGroup>
  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Analyze URL-level data using the documented source.
  </Card>

  <Card title="Page Performance" href="/documentation/measure/page-performance">
    Review per-page product context.
  </Card>

  <Card title="Exports" href="/documentation/workspace/exports">
    Export the filtered dataset.
  </Card>

  <Card title="Websites influencing answers" href="/use-cases/sources/which-websites-influence-ai">
    Analyze recorded citations separately.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/sources/pages-with-most-ai-citations">
    Compare citation URL observations.
  </Card>

  <Card title="Is AI driving traffic?" href="/use-cases/impact/is-ai-driving-traffic">
    Assess referral traffic and attribution.
  </Card>
</CardGroup>


# How do I calculate the ROI of my GEO efforts compared to traditional SEO?
Source: https://docs.qwairy.co/use-cases/impact/roi-geo-vs-traditional-seo

Compare channel costs and measured outcomes using explicit attribution rules, shared value assumptions, and sensitivity ranges.

## Direct answer

Create two transparent investment models rather than inferring value from visibility alone. For each channel, use measured costs and outcomes from the relevant analytics or business system. Apply the same conversion-value rules, show unattributed traffic separately, and present a range when assumptions are uncertain.

## Data required

Use GEO and SEO labor, tooling, content, and distribution costs; connected AI-referral and GSC or organic-traffic data; conversion events; approved value per outcome; period; attribution model; and known data gaps. Keep visibility metrics as leading indicators, not revenue.

## Workflow

<Steps>
  <Step title="Define comparable scope">
    Choose the period, markets, content, and cost categories included for each channel. Document shared work instead of double-counting it.
  </Step>

  <Step title="Measure outcomes">
    Use recognized AI-referral outcomes for GEO and the agreed organic-search source for SEO. Preserve each source system's attribution rules.
  </Step>

  <Step title="Apply value assumptions">
    Multiply validated outcomes by an approved value per outcome where appropriate. Calculate ROI as attributed value minus cost, divided by cost, and show sensitivity to uncertain inputs.
  </Step>

  <Step title="Explain the comparison">
    Separate measured value, modeled value, unattributed activity, visibility indicators, and non-financial benefits.
  </Step>
</Steps>

## Interpretation

A modeled ROI is conditional on attribution and value assumptions. Mention Rate, Citation Rate, Share of Voice, and Coverage do not have an inherent monetary value. A difference between GEO and SEO ROI does not prove that moving budget will reproduce the same return.

## Possible next actions

* If AI-referral conversions are too sparse, test a longer observation period or report cost and leading indicators without inventing revenue.
* If channels share content costs, test multiple allocation methods and show how they change the comparison.
* If unattributed journeys are material, improve privacy-compliant measurement before making a budget decision.

## Limitations

AI and organic journeys can overlap, referrers can be missing, and attribution models can assign different credit to the same conversion. The analysis is decision support, not a causal experiment or forecast. Report assumptions and uncertainty alongside the result.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export Qwairy data for a controlled model.
  </Card>

  <Card title="Google Search Console" href="/documentation/measure/google-search-console">
    Use the connected traditional-search dataset.
  </Card>

  <Card title="GEO guide" href="https://www.qwairy.co/guides/complete-guide-to-generative-engine-optimization">
    Read additional background on GEO.
  </Card>

  <Card title="Is AI driving traffic?" href="/use-cases/impact/is-ai-driving-traffic">
    Validate observed AI referral data first.
  </Card>

  <Card title="KPIs for GEO" href="/use-cases/impact/kpis-for-geo-success">
    Choose leading and outcome indicators.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Frame content work as testable hypotheses.
  </Card>
</CardGroup>


# How much traffic am I getting from each AI platform?
Source: https://docs.qwairy.co/use-cases/impact/traffic-from-each-ai-platform

Break down observed sessions by recognized AI referrer while documenting attribution rules, missing referrers, and the selected traffic unit.

## Direct answer

Open **Measure > Referrer Analytics**, select a period, and group observed sessions by recognized AI referrer. Report the analytics property, traffic unit, and platform-classification rules. Keep provider visibility metrics separate from referral traffic.

## Data required

Use the connected analytics property, timezone, period, referrer URL or source classification, session or user unit, landing page, and optional engagement or conversion fields. Use Qwairy provider and model data only as separate context.

## Workflow

<Steps>
  <Step title="Confirm tracking scope">
    Verify the property, consent configuration, timezone, and the definition of the traffic unit.
  </Step>

  <Step title="Review the platform breakdown">
    Group recognized AI referrers by platform and retain unknown, direct, and unclassified traffic as separate categories.
  </Step>

  <Step title="Inspect pages and outcomes">
    For each platform, review landing pages and available engagement or conversion measures using the analytics source's definitions.
  </Step>

  <Step title="Compare periods carefully">
    Use aligned periods and note classification or tracking changes before interpreting movement.
  </Step>
</Steps>

## Interpretation

The platform breakdown describes recognized referrers, not all visits influenced by an AI product. A traffic platform and a monitored answer provider may use related names but remain different datasets. Provider mention or citation metrics cannot be substituted for referral sessions.

## Possible next actions

* If a platform's traffic changes, test whether the shift is concentrated on a landing page or coincides with tracking changes.
* If unclassified traffic is material, review the referrer rules before assigning it to a platform.
* If one platform sends engaged visits, test relevant page experiences while keeping the result observational.

## Limitations

Browsers, apps, redirects, and privacy controls can remove or alter referrer data. Platform classifications can evolve. The REST performance endpoint measures returned-answer performance under its own contract; it does not provide the same referral-traffic breakdown.

## Related pages

<CardGroup>
  <Card title="Performance Overview" href="/looker-studio/sources/performance-overview">
    Build a platform report from documented sources.
  </Card>

  <Card title="Referrer Analytics" href="/documentation/measure/referrer-analytics">
    Review recognized AI referral traffic.
  </Card>

  <Card title="Performance API" href="/developers/endpoints/performance">
    Read the separate REST performance definition.
  </Card>

  <Card title="Is AI driving traffic?" href="/use-cases/impact/is-ai-driving-traffic">
    Assess traffic attribution and correlation.
  </Card>

  <Card title="Brand visibility" href="/use-cases/visibility/how-visible-is-my-brand-in-ai">
    Analyze product visibility separately.
  </Card>

  <Card title="Provider mentions" href="/use-cases/visibility/which-providers-mention-my-brand">
    Compare stored-answer mentions by provider.
  </Card>
</CardGroup>


# Use cases
Source: https://docs.qwairy.co/use-cases/index

Choose a Qwairy workflow by the question you need to answer, the evidence available, and the decision you need to make

Use these guides when your task crosses several Qwairy features. Each guide identifies the data to use, the workflow to follow, and the limits to consider before you act.

<Note>
  Qwairy reports observed answers, citations, referrals, and crawler activity. A change after an action is evidence for investigation, not proof that the action caused it.
</Note>

## Start monitoring

Define a stable scope before you compare providers or time periods.

<CardGroup>
  <Card title="Choose monitored prompts" href="/use-cases/setup/monitoring-right-prompts">
    Build a prompt set around the decisions and audiences you need to observe.
  </Card>

  <Card title="Organize prompts" href="/use-cases/setup/organize-prompts-tags-topics">
    Use topics and tags to create reusable analysis segments.
  </Card>

  <Card title="Choose providers" href="/use-cases/setup/which-providers-to-prioritize">
    Compare provider relevance and available monitoring coverage.
  </Card>
</CardGroup>

## Understand visibility

Separate mentions, citations, share of voice, coverage, and position before interpreting a result.

<CardGroup>
  <Card title="Assess brand visibility" href="/use-cases/visibility/how-visible-is-my-brand-in-ai">
    Read the main visibility metrics for one consistent scope.
  </Card>

  <Card title="Compare providers" href="/use-cases/visibility/which-providers-mention-my-brand">
    Find where observed answer patterns differ by provider.
  </Card>

  <Card title="Track change over time" href="/use-cases/visibility/how-has-my-visibility-changed">
    Compare equivalent periods and investigate changes in the underlying answers.
  </Card>

  <Card title="Separate mentions and citations" href="/use-cases/visibility/cited-with-link-vs-just-mentioned">
    Diagnose whether the brand appears, its domain is cited, or both.
  </Card>
</CardGroup>

## Compare competitors

Use the same prompts, providers, and period for every brand in a comparison.

<CardGroup>
  <Card title="Identify observed competitors" href="/use-cases/competitors/who-are-my-biggest-competitors">
    See which configured competitors occur most often in the selected answers.
  </Card>

  <Card title="Find provider-specific gaps" href="/use-cases/competitors/competitors-outperform-me-by-provider">
    Compare brand and competitor evidence by provider.
  </Card>

  <Card title="Find topic gaps" href="/use-cases/competitors/topics-competitors-own-without-me">
    Locate topics where competitor mentions occur without a SELF mention.
  </Card>

  <Card title="Compare cited sources" href="/use-cases/competitors/sources-cited-for-competitors-not-me">
    Review sources associated with competitor citations but not your domain.
  </Card>
</CardGroup>

## Improve content and reputation

Turn observed gaps into hypotheses, then verify future changes with the same monitoring scope.

<CardGroup>
  <Card title="Prioritize content opportunities" href="/use-cases/content/what-content-to-create">
    Connect missing coverage and source evidence to a content backlog.
  </Card>

  <Card title="Review influential sources" href="/use-cases/sources/which-websites-influence-ai">
    Inspect the domains cited in answers about your market.
  </Card>

  <Card title="Audit brand perception" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Compare recurring themes with the underlying stored answers.
  </Card>

  <Card title="Investigate inaccurate information" href="/use-cases/reputation/correct-ai-misinformation">
    Document the claim, its sources, and the evidence you can correct or clarify.
  </Card>
</CardGroup>

## Measure impact

Combine visibility evidence with connected analytics instead of treating visibility as a traffic or revenue proxy.

<CardGroup>
  <Card title="Measure AI referrals" href="/use-cases/impact/is-ai-driving-traffic">
    Review traffic attributed to supported AI referrers.
  </Card>

  <Card title="Build an executive report" href="/use-cases/impact/build-executive-report">
    Report scope, trends, evidence, and limitations together.
  </Card>

  <Card title="Evaluate a campaign window" href="/use-cases/campaigns/campaign-impact-on-ai-visibility">
    Compare equivalent periods without claiming causal attribution.
  </Card>

  <Card title="Automate reporting" href="/use-cases/reporting/automated-geo-reporting">
    Choose between exports, Looker Studio, the REST API, and MCP.
  </Card>
</CardGroup>

## Technical and industry playbooks

Apply the same evidence rules to crawler observations and specialized result types.

<CardGroup>
  <Card title="Review crawler access" href="/use-cases/technical/site-optimized-for-ai-crawlers">
    Check technical files and observed crawler activity as separate signals.
  </Card>

  <Card title="Compare crawling and citations" href="/use-cases/technical/pages-crawled-but-never-cited">
    Identify pages with crawler observations but no citation in the selected answer data.
  </Card>

  <Card title="Analyze shopping results" href="/use-cases/industry/products-in-ai-shopping">
    Review observed product appearances and cited evidence.
  </Card>

  <Card title="Analyze local results" href="/use-cases/industry/local-near-me-in-ai">
    Compare local result evidence by prompt and provider.
  </Card>
</CardGroup>

Browse the complete library in the sidebar, including funnel, provider, source, reporting, reputation, technical, and industry workflows.


# How do I improve my brand's positioning in B2B evaluation prompts?
Source: https://docs.qwairy.co/use-cases/industry/b2b-evaluation-positioning

Compare brand narratives in selected B2B evaluation answers, verify the evidence, and test positioning or content changes.

## Direct answer

Monitor configured prompts that reflect your buyers' evaluation questions, then use **Cockpit > Compare**, stored answers, and Source Explorer to identify where SELF and DIRECT brands are described differently. Verify the pattern before testing a positioning, content, or source-distribution change.

## Data required

Use configured evaluation prompts, topics and tags, provider and model, period, stored answers, SELF/DIRECT classifications, sentiment or perception themes, citation URLs, and approved product positioning and evidence.

## Workflow

<Steps>
  <Step title="Define the evaluation cohort">
    Choose prompts tied to real B2B decisions, such as requirements, alternatives, trade-offs, implementation, and pricing. Record audience and stage as metadata.
  </Step>

  <Step title="Compare observed narratives">
    Review SELF and DIRECT occurrences in Compare and read the associated answers. Separate presence, rank order, claims, sentiment, and citations.
  </Step>

  <Step title="Verify important differences">
    Check claims against approved product facts and inspect recorded sources. Do not infer why a provider produced the difference from the output alone.
  </Step>

  <Step title="Select one test">
    Choose a material, supportable gap and define the content, positioning, or distribution hypothesis plus the cohort you will monitor.
  </Step>
</Steps>

## Interpretation

Product Share of Voice is SELF mention occurrences divided by SELF plus DIRECT occurrences. It measures competitive occurrence in the selected answers, not preference, pipeline, or purchase intent. Narrative analysis must stay linked to its prompts, providers, models, and period.

## Possible next actions

* If SELF is absent from a relevant comparison, test an evidence-led page addressing the buyer's decision criteria.
* If an inaccurate weakness recurs, verify its sources and test a correction workflow.
* If the gap appears only at one evaluation stage, focus the hypothesis there rather than changing all messaging.

## Limitations

Configured prompts approximate selected buyer questions; they do not represent every procurement process. Provider outputs can vary and do not predict purchase decisions. A later change in answers does not prove that your intervention caused it.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export the evaluation cohort.
  </Card>

  <Card title="Competitor Metrics" href="/looker-studio/sources/competitor-metrics">
    Build documented competitor reporting.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered comparison.
  </Card>

  <Card title="Consideration-stage presence" href="/use-cases/funnel/brand-in-consideration-phase">
    Review brand presence during consideration.
  </Card>

  <Card title="SaaS best-tools answers" href="/use-cases/industry/saas-in-best-tools-responses">
    Analyze recommendation-list prompts.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/content/pages-most-cited-by-ai">
    Inspect citation URLs supporting answers.
  </Card>
</CardGroup>


# Does AI recommend my business for local or 'near me' searches?
Source: https://docs.qwairy.co/use-cases/industry/local-near-me-in-ai

Review observed local results and stored answers for defined locations, providers, and prompts without claiming complete market coverage.

## Direct answer

Use **Monitor > Insights > Local Businesses** with location-specific configured prompts. Review whether your business appears, how its details are represented, and which DIRECT businesses appear in the same selected results. Verify material details against your current business records.

## Data required

Use configured local prompts, location and radius or market scope where available, provider and model, run date, observed local-result records, stored answers, SELF/DIRECT classification, business name, address, phone, website, and approved location data.

## Workflow

<Steps>
  <Step title="Define the local scope">
    Choose the locations, audience need, and prompts that matter. Avoid combining cities or service areas with different competitive conditions.
  </Step>

  <Step title="Review observed results">
    Inspect Local Businesses and the associated answers for SELF and DIRECT presence, position where available, and displayed business details.
  </Step>

  <Step title="Verify business information">
    Compare observed name, address, phone, website, category, and availability claims with the approved current record.
  </Step>

  <Step title="Compare stable cohorts">
    Repeat the same location, prompt, provider, and model filters before interpreting changes.
  </Step>
</Steps>

## Interpretation

Presence in an observed local result shows that the business appeared in that selected run. It does not guarantee a recommendation to every user, a map ranking, or a visit. Missing or inconsistent details are investigation signals, not proof of their source.

## Possible next actions

* If business details are inaccurate, test corrections in authoritative owned listings and public pages.
* If SELF is absent while relevant DIRECT businesses appear, inspect their recorded source and category context before choosing a local-content hypothesis.
* If results vary by location, test location-specific evidence rather than applying one conclusion to every market.

## Limitations

Local outputs can depend on location, personalization, data providers, model version, and time. Qwairy observes selected runs only. The REST local endpoint is a separate contract; verify its fields, filters, and units before comparing it with the product.

## Related pages

<CardGroup>
  <Card title="Local Insights" href="/looker-studio/sources/local-insights">
    Build location reporting from the documented source.
  </Card>

  <Card title="Local Businesses" href="/documentation/monitor/insights/local-intelligence">
    Review observed local results in the product.
  </Card>

  <Card title="Local API" href="/developers/endpoints/local">
    Read the separate REST local-data contract.
  </Card>

  <Card title="Products in AI shopping" href="/use-cases/industry/products-in-ai-shopping">
    Review observed commerce results separately.
  </Card>

  <Card title="Top-of-funnel visibility" href="/use-cases/funnel/visibility-top-of-funnel">
    Analyze early-stage brand presence.
  </Card>

  <Card title="Websites influencing answers" href="/use-cases/sources/which-websites-influence-ai">
    Inspect recorded sources without inferring causation.
  </Card>
</CardGroup>


# Are my products showing up in AI shopping recommendations?
Source: https://docs.qwairy.co/use-cases/industry/products-in-ai-shopping

Review observed Shopping Results and associated answers for product presence, details, providers, and prompts.

## Direct answer

Use **Monitor > Insights > Shopping Results** to inspect product records observed for relevant configured prompts. Check SELF and DIRECT product presence, displayed details, source URLs, provider, model, and date. Verify pricing and availability against your current product source.

## Data required

Use configured shopping prompts, provider and model, run date, observed Shopping Results, associated stored answers, SELF/DIRECT classification, product identifiers, displayed price and availability where present, source URL, and approved catalog data.

## Workflow

<Steps>
  <Step title="Define the product cohort">
    Choose product categories, markets, and prompts that reflect the shopping decisions you want to monitor.
  </Step>

  <Step title="Review observed results">
    Inspect SELF and DIRECT products, their displayed attributes, source URLs, provider, model, and run date.
  </Step>

  <Step title="Verify volatile details">
    Compare price, availability, specifications, and product identity with the current approved catalog. Mark stale, missing, or mismatched values.
  </Step>

  <Step title="Track comparable runs">
    Use the same prompt, market, provider, and model cohort to observe later presence and data changes.
  </Step>
</Steps>

## Interpretation

An observed Shopping Result is a recorded result for a selected run. It does not prove universal availability, recommendation quality, purchase intent, or sales. Product presence and brand mentions in the associated answer are separate observations.

## Possible next actions

* If displayed product data is stale, test a correction in the authoritative catalog or product page.
* If DIRECT products appear but SELF does not, inspect relevance, category mapping, and recorded sources before forming a content hypothesis.
* If presence varies by market or provider, keep follow-up tests scoped to that slice.

## Limitations

Shopping outputs, prices, availability, and sources can change quickly and may depend on market context. Qwairy cannot guarantee inclusion or freshness. The REST shopping endpoint follows its own schema and may not reproduce product UI aggregations.

## Related pages

<CardGroup>
  <Card title="Shopping Insights" href="/looker-studio/sources/shopping-insights">
    Build reporting from the documented shopping source.
  </Card>

  <Card title="Shopping Results" href="/documentation/monitor/insights/shopping-intelligence">
    Review observed product results in the product.
  </Card>

  <Card title="Shopping API" href="/developers/endpoints/shopping">
    Read the separate REST shopping contract.
  </Card>

  <Card title="Purchase-intent presence" href="/use-cases/funnel/brand-in-purchase-intent">
    Review brand presence in purchase-oriented prompts.
  </Card>

  <Card title="Software pros, cons, and pricing" href="/use-cases/industry/software-pros-cons-pricing">
    Verify narrative and commercial details.
  </Card>

  <Card title="Top-of-funnel visibility" href="/use-cases/funnel/visibility-top-of-funnel">
    Analyze early-stage presence separately.
  </Card>
</CardGroup>


# Is my SaaS product listed in AI 'best tools for X' responses?
Source: https://docs.qwairy.co/use-cases/industry/saas-in-best-tools-responses

Monitor recommendation-list prompts and compare SELF and DIRECT occurrences, claims, and citations in selected stored answers.

## Direct answer

Create prompts that represent relevant 'best tools' decisions, then review **Monitor > Response Analysis** and **Cockpit > Compare**. Record whether SELF appears, which DIRECT products appear, how each is described, and which source URLs are cited.

## Data required

Use a stable set of configured prompts, provider and model, period, topic or tag, stored answers, SELF/DIRECT classifications, mention occurrences, ordering where present, sentiment or claims, and citation URLs.

## Workflow

<Steps>
  <Step title="Define relevant prompts">
    Choose audience, use case, constraints, and market context. Avoid broad list prompts that do not match your product.
  </Step>

  <Step title="Review answer-level presence">
    Read each stored answer and record SELF and DIRECT occurrences separately from rank or recommendation language.
  </Step>

  <Step title="Compare narratives and sources">
    Identify recurring selection criteria, product claims, omissions, and citation URLs. Verify factual claims against approved sources.
  </Step>

  <Step title="Monitor the stable cohort">
    Repeat the same prompt and provider/model cohort and report distributions rather than a single answer.
  </Step>
</Steps>

## Interpretation

Product Share of Voice is SELF mention occurrences divided by SELF plus DIRECT occurrences. It does not measure list position, preference, or conversion. Inclusion in a stored answer is one observation and does not guarantee future recommendation.

## Possible next actions

* If SELF is absent from relevant prompts, test content that provides verifiable evidence for the observed selection criteria.
* If a recurring claim is inaccurate, follow the misinformation correction workflow.
* If one DIRECT product dominates occurrences, inspect its cited sources before choosing a distribution hypothesis.

## Limitations

Recommendation lists can change between runs and depend on prompt wording, model, provider, web access, and location. Qwairy observes selected stored answers and cannot infer purchasing behavior or guarantee inclusion.

## Related pages

<CardGroup>
  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Report on answer-level recommendation data.
  </Card>

  <Card title="Analyzing Answers" href="/documentation/monitor/analyzing-answers">
    Review stored answers in context.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Use supported MCP tools and schemas.
  </Card>

  <Card title="Consideration-stage presence" href="/use-cases/funnel/brand-in-consideration-phase">
    Analyze brand presence during consideration.
  </Card>

  <Card title="B2B evaluation positioning" href="/use-cases/industry/b2b-evaluation-positioning">
    Investigate evaluation narratives.
  </Card>

  <Card title="Share of Voice" href="/use-cases/visibility/what-is-my-share-of-voice">
    Apply the product occurrence formula.
  </Card>
</CardGroup>


# What do AI models say about my software's pros, cons, and pricing?
Source: https://docs.qwairy.co/use-cases/industry/software-pros-cons-pricing

Review selected stored answers for recurring product claims and verify volatile pricing or availability details against approved sources.

## Direct answer

Use **Monitor > Response Analysis** to read the exact stored outputs, then use **Analyze > Brand Perception** and **Analyze > Sentiment Analysis** to group recurring pros, cons, and commercial claims. Verify every material product or pricing statement against a current approved source.

## Data required

Use configured evaluation prompts, provider and model, run date, stored answers, topics or tags, perception and sentiment outputs, citation URLs, and dated approved product, packaging, and pricing information.

## Workflow

<Steps>
  <Step title="Choose evaluation prompts">
    Select prompts that ask about fit, trade-offs, capabilities, limitations, and pricing for a defined audience and market.
  </Step>

  <Step title="Read the stored answers">
    Record recurring positive, negative, and conditional claims. Keep factual statements separate from opinions or comparisons.
  </Step>

  <Step title="Verify details">
    Compare product features, limitations, price, currency, billing period, availability, and package names with the approved current source.
  </Step>

  <Step title="Compare providers and runs">
    Check whether material claims recur across providers, models, prompts, and later runs before treating them as a pattern.
  </Step>
</Steps>

## Interpretation

A pro or con is an observed description in selected answers, not an objective verdict. Sentiment classifications can simplify conditional language. Pricing is time- and market-sensitive; always retain the answer date and source context.

## Possible next actions

* If pricing is outdated, test updates to the authoritative pricing source and monitor the same cohort.
* If a valid limitation is framed without context, test clearer positioning about intended fit.
* If an unsupported product claim recurs, inspect citations and follow a factual correction workflow.

## Limitations

Stored answers can vary and may contain outdated or incorrect information. Recorded citation URLs do not prove which source produced a claim. The REST answers endpoint is a separate contract; confirm its fields before comparing it with product analyses.

## Related pages

<CardGroup>
  <Card title="Brand Perception" href="/documentation/analyze/brand-perception">
    Review recurring observed product attributes.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Build reporting from stored answer records.
  </Card>

  <Card title="Answers API" href="/developers/endpoints/answers/list">
    Read the separate REST answers contract.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Read brand narratives in context.
  </Card>

  <Card title="Products in AI shopping" href="/use-cases/industry/products-in-ai-shopping">
    Check observed commerce result details.
  </Card>

  <Card title="Negative sentiment by topic" href="/use-cases/reputation/negative-sentiment-on-topics">
    Analyze negative language in selected topics.
  </Card>
</CardGroup>


# How does Google AI Overview treat my brand compared to traditional Google Search?
Source: https://docs.qwairy.co/use-cases/providers/ai-overview-vs-google-search

Compare observed Google AI Overview answers with Search Console data while keeping their different units separate.

## Direct answer

Treat Google AI Overview monitoring and traditional search performance as two different datasets. Compare matched topics, markets, and time windows for directional patterns, but do not interpret their percentages as the same metric.

## Data required

* Stored answers generated with the Google AI Overview provider or model available in your workspace
* The monitored prompts, country, language, and period for those answers
* Connected Google Search Console queries, pages, impressions, clicks, and average position
* SELF mentions and SELF citation URLs in the AI Overview answers
* A mapping between monitored prompts, search queries, and landing pages

## Workflow

1. In **Cockpit > Overview**, filter to Google AI Overview and record the active model and monitoring scope.
2. Record Product Mention Rate, Citation Rate, Coverage, and their raw components.
3. In **Measure > Google Search Console**, select a comparable country and time window.
4. Map monitored prompts to related Search Console queries by intent. Do not assume a text match means the same user need.
5. In **Monitor > Response Analysis** and **Monitor > Source Explorer**, inspect the AI Overview answers and cited URLs.
6. Compare patterns by topic or page, keeping Qwairy and Search Console metrics in separate columns.

## Interpretation

Qwairy Product Mention Rate and Citation Rate are response-level metrics from stored AI answers. Product Coverage is prompt-level. Search Console impressions, clicks, click-through rate, and average position describe Google Search exposure and traffic.

A page can perform in traditional search and be absent from observed AI citations, or the reverse. That pattern identifies a question to investigate; it does not prove that one surface caused performance on the other.

## Possible next actions

* Test whether adding clear, verifiable information to a relevant landing page is associated with later SELF citations.
* Investigate prompts whose intent is not represented in Search Console queries or site content.
* Check whether country or language differences explain a cross-surface mismatch.
* Track a fixed prompt and query cohort after a page change.

Treat each expected effect as a hypothesis.

## Limitations

* Search Console and Qwairy use different collection methods, units, and denominators.
* Query-to-prompt matching requires judgment.
* AI Overview availability and behavior can vary by model, market, and time.
* Neither dataset establishes causality between search ranking, citation, and brand mention.

## Related pages

* [Use Google Search Console data](/documentation/measure/google-search-console)
* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Explore search insights in Looker Studio](/looker-studio/sources/search-insights)


# Which AI provider gives my brand the best sentiment and positioning?
Source: https://docs.qwairy.co/use-cases/providers/best-provider-for-sentiment

Compare observed sentiment and recorded position across providers using matched answers and explicit eligible samples.

## Direct answer

Identify the highest observed sentiment and earliest recorded position within a matched provider dataset. Do not label a provider permanently best: provider output, model choice, prompt mix, and eligible sample size can change the result.

## Data required

* The same answered prompts across providers or models
* Detected SELF mentions with sentiment values
* Recorded SELF positions and their eligible counts
* A fixed period, country, language, topic, tag, and funnel scope
* Representative answer text from each provider

## Workflow

1. In **Analyze > Sentiment**, set a consistent analysis scope.
2. Compare provider or model sentiment with the number of eligible SELF mentions.
3. In **Cockpit > Overview** or **Cockpit > Compare**, record Avg Position with its eligible position count.
4. Read answers in **Monitor > Response Analysis** to verify tone, claim accuracy, and whether a numeric rank is meaningful.
5. Separate providers with incomplete or materially different answer coverage.
6. Repeat the comparison on important topics rather than relying only on the aggregate.

## Interpretation

Sentiment summarizes detected language around eligible SELF mentions; it is not a fact-check or a measure of user opinion. Avg Position is conditional on SELF mentions with a recorded rank and excludes brand absences.

Always pair sentiment and position with Coverage or Mention Rate. A provider can show favorable sentiment among a small set of mentions while omitting the brand from many answered prompts.

## Possible next actions

* Test whether a negative pattern is concentrated in one topic, prompt, or outdated claim.
* Review the sources cited in unfavorable answers before proposing a correction.
* Compare models within the same provider when their results diverge.
* Track a stable answer cohort after publishing verifiable corrective information.

These actions test explanations and do not guarantee a sentiment or position change.

## Limitations

* Sentiment classification can miss nuance, irony, or mixed evaluations.
* Position is not meaningful for every narrative response.
* Providers may return different answer volumes or formats.
* Observed provider differences do not reveal training data or internal ranking logic.

## Related pages

* [Analyze sentiment](/documentation/analyze/sentiment-analysis)
* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Compare provider scores](/use-cases/providers/different-scores-across-providers)


# Is my brand being included in Perplexity's cited sources?
Source: https://docs.qwairy.co/use-cases/providers/brand-in-perplexity-sources

Filter stored Perplexity answers and source URLs to find observed SELF citations and inspect their context.

## Direct answer

Filter **Monitor > Source Explorer** and **Monitor > Response Analysis** to the relevant Perplexity provider and model. Check whether stored answers cite a SELF URL, then inspect the answer context. A missing citation applies only to the selected observed dataset.

## Data required

* Completed answers for the selected Perplexity provider or model
* Citation domains and URLs classified as SELF or DIRECT
* The corresponding prompts and answer text
* A fixed period, country, language, topic, and tag scope
* Citation Rate numerator and denominator

## Workflow

1. In **Monitor > Source Explorer**, apply the Perplexity provider or model filter and the intended analysis scope.
2. Filter to SELF domains or URLs and record the displayed citation counts.
3. In **Monitor > Response Analysis**, open the answers behind those citations.
4. Record whether each cited SELF URL supports the nearby claim and whether the brand is also mentioned.
5. Review answers with no SELF citation to see which sources were returned instead.
6. Compare topics or periods only with matched prompts and completed-answer coverage.

## Interpretation

Product **Citation Rate** is response-level: answers citing a SELF source divided by answers citing at least one SELF or DIRECT source. It does not measure the share of all prompts or all Perplexity activity.

A SELF citation does not imply a SELF mention, positive context, or recommendation. A cited competitor source may support a general claim rather than the competitor's brand.

## Possible next actions

* Test whether a clear, canonical page for a recurring factual claim is associated with later SELF citations.
* Review competitor-cited pages to identify evidence or structure missing from your relevant page.
* Correct outdated or conflicting SELF pages before seeking more citations.
* Track the same prompt cohort after a source-page update.

Treat these as hypotheses; inclusion is controlled by the provider and is not guaranteed.

## Limitations

* Qwairy stores citations exposed with observed answers, not every source used internally.
* Perplexity behavior can vary by model, market, and run.
* Redirects, aliases, and subdomains may require manual SELF classification review.
* Citation co-occurrence does not establish influence or causality.

## Related pages

* [Explore content sources](/documentation/monitor/content-sources)
* [Inspect source URLs in Looker Studio](/looker-studio/sources/source-urls)
* [Find influential observed websites](/use-cases/sources/which-websites-influence-ai)


# Why does my brand score differently across Perplexity, Gemini, and Claude?
Source: https://docs.qwairy.co/use-cases/providers/different-scores-across-providers

Reconcile provider differences by matching prompts and filters, then tracing each metric to its raw answers and denominator.

## Direct answer

Provider metrics can differ because the observed answers, model, source behavior, eligible denominator, or prompt coverage differs. Qwairy can show where the difference occurs, but it cannot reveal a provider's private training data or ranking logic.

## Data required

* Matched answered prompts across the providers or models
* Provider and model identifiers
* Identical period, country, language, topic, tag, and funnel filters
* Raw numerators and denominators for each metric
* Representative answers and citations from each provider

## Workflow

1. In **Cockpit > Overview**, set a fixed scope and compare one metric at a time.
2. Confirm that each provider has comparable completed-answer and answered-prompt counts.
3. In **Cockpit > GEO Matrix**, locate the prompts and topics producing the gap.
4. Separate models within each provider rather than merging them under a family label.
5. Read the underlying answers in **Monitor > Response Analysis** and inspect sources in **Monitor > Source Explorer**.
6. Recalculate the comparison after excluding missing or unmatched observations.

## Interpretation

Product Mention Rate and Citation Rate are response-level and use different eligible answer denominators. Product Coverage is prompt-level. Product Share of Voice counts mention occurrences. A provider can therefore rank differently on each metric without any inconsistency.

Prefer raw components over a blended score when diagnosing a difference. A small denominator can amplify one answer, and missing answers are not brand absences.

## Possible next actions

* Test whether the gap persists on a matched prompt cohort.
* Investigate a topic or model that accounts for most of the difference.
* Review source differences as a possible explanation without treating them as proven causes.
* Adjust monitoring when one provider has incomplete coverage, then collect a comparable sample.

Document the hypothesis and preserve the scope for the next comparison.

## Limitations

* Provider output can vary between runs.
* Provider and model availability can differ by market.
* Qwairy observes outputs and exposed citations, not private provider systems.
* Aggregate scores can hide metric-specific and prompt-specific differences.

## Related pages

* [Read Cockpit Overview](/documentation/cockpit/performance-dashboard)
* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Compare provider sentiment](/use-cases/providers/best-provider-for-sentiment)


# Why does ChatGPT recommend my competitor instead of me?
Source: https://docs.qwairy.co/use-cases/providers/why-chatgpt-recommends-competitor

Trace observed ChatGPT competitor recommendations to matched prompts, answer context, metrics, and cited sources.

## Direct answer

Qwairy can show where a selected ChatGPT model recommends a DIRECT competitor and omits your brand. It cannot prove why the model made that choice. Diagnose the observed prompt, answer wording, eligible metrics, and exposed sources before forming a hypothesis.

## Data required

* Completed answers from the selected ChatGPT model
* The exact prompts and active country, language, topic, tag, funnel, and period filters
* Correct SELF and DIRECT competitor classifications
* Mention occurrences, recorded positions, sentiment, and exposed citations
* Comparable answers where your brand is included

## Workflow

1. In **Cockpit > Compare**, filter to the selected ChatGPT model and a fixed scope.
2. Identify prompts where a DIRECT competitor appears and your brand does not.
3. Open those answers in **Monitor > Response Analysis** and read the full recommendation criteria and caveats.
4. In **Monitor > Source Explorer**, inspect sources exposed with the same answers.
5. Compare with prompts where both brands appear to find differences in intent, evidence, market, or answer format.
6. Check whether the pattern persists across repeated completed answers before acting.

## Interpretation

A competitor mention or earlier recorded position is an observed output, not evidence about private model reasoning. Product Share of Voice counts SELF and DIRECT mention occurrences. Product Mention Rate is response-level and uses answers with at least one SELF or DIRECT mention as its denominator.

Keep recommendation context separate from raw presence. A competitor can be mentioned as an unsuitable option, and a cited competitor domain may support a general fact.

## Possible next actions

* Test a page that answers the recurring selection criterion with verifiable evidence.
* Correct inaccurate or outdated public information found in the observed answer or cited source.
* Investigate whether the pattern is limited to one prompt, model, topic, or market.
* Track the same prompt cohort after a content or positioning change.

These are hypotheses. No content change guarantees future inclusion or recommendation.

## Limitations

* Qwairy does not expose ChatGPT's private training data, weights, or decision process.
* Answers and exposed citations can vary between runs and models.
* Recommendation detection requires context; mention alone is insufficient.
* Monitoring results do not represent all ChatGPT interactions.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Compare competitors](/documentation/cockpit/compare)
* [Explore observed sources](/use-cases/sources/which-websites-influence-ai)


# How do I set up automated GEO reporting for my team?
Source: https://docs.qwairy.co/use-cases/reporting/automated-geo-reporting

Create a repeatable reporting workflow with explicit data contracts, metric definitions, filters, owners, and refresh expectations.

## Direct answer

Choose the reporting surface that fits the audience: a filtered Shared Link, an export, documented Looker Studio sources, or the REST API. Define the cohort and metric formulas before automating delivery, then add freshness and data-quality checks.

## Data required

Use a reporting specification with audience, decisions, prompt cohort, providers and models, topics or tags, period, SELF/DIRECT classifications, metric formulas, source system, refresh expectation, permissions, and owner.

## Workflow

<Steps>
  <Step title="Define the report contract">
    List each metric with its source, numerator, denominator, filters, unit, and intended decision. Separate product, Looker Studio, export, and API contracts.
  </Step>

  <Step title="Choose the delivery surface">
    Use Shared Links for filtered product views, Exports for snapshots, Looker Studio for connected dashboards, or the REST API for a maintained integration.
  </Step>

  <Step title="Build and reconcile">
    Map fields, timezones, brand classifications, URLs, and missing-data states. Compare a sample with the source surface before scheduling use.
  </Step>

  <Step title="Operate the report">
    Assign ownership for access, schema changes, refresh failures, metric definitions, and periodic review of the monitoring cohort.
  </Step>
</Steps>

## Interpretation

A refreshed dashboard is only as current as its underlying connections and run cadence. Product metrics retain their product formulas; REST fields and aggregations follow endpoint documentation. An export is a point-in-time snapshot, while connected reports may update.

## Possible next actions

* If the audience needs investigation, test a Shared Link before building a custom integration.
* If the report requires joined business data, test a documented Looker Studio or warehouse mapping with reconciliation checks.
* If API fields do not match a product card, preserve both definitions instead of renaming one to appear equivalent.

## Limitations

Availability, permissions, retention, refresh timing, and schema can vary by surface and plan. Automation does not remove the need to review data quality or narrative context. Qwairy cannot guarantee third-party dashboard or delivery availability.

## Related pages

<CardGroup>
  <Card title="REST API" href="/developers/introduction">
    Review API authentication and contracts.
  </Card>

  <Card title="Looker Studio setup" href="/looker-studio/getting-started">
    Connect documented Looker Studio sources.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered product view.
  </Card>

  <Card title="Looker Studio or BI" href="/use-cases/reporting/integrate-looker-studio-bi">
    Choose and validate an integration path.
  </Card>

  <Card title="Executive report" href="/use-cases/impact/build-executive-report">
    Design an audience-specific narrative.
  </Card>

  <Card title="Exports" href="/documentation/workspace/exports">
    Create point-in-time datasets.
  </Card>
</CardGroup>


# Which topic + provider combination is my biggest competitive weakness?
Source: https://docs.qwairy.co/use-cases/reporting/biggest-topic-provider-weakness

Use GEO Matrix with one defined metric and stable filters to identify topic-provider cells that warrant answer-level review.

## Direct answer

Open **Cockpit > GEO Matrix**, select the metric and Topics as the row grouping, and review provider columns under a stable scope. Inspect unexpected cells and their underlying answers before calling any combination a weakness.

## Data required

Use the selected product metric with its exact formula, topics, configured prompts, providers, models where applicable, period, active list and filters, SELF/DIRECT classifications, stored answers, and citation URLs.

## Workflow

<Steps>
  <Step title="Choose one metric">
    Select the metric that matches the decision. Do not compare cells whose metric, denominator, or filters differ.
  </Step>

  <Step title="Review the matrix">
    Scan topic rows and provider columns for relative differences. Treat an empty cell as missing usable data until checked.
  </Step>

  <Step title="Inspect candidate cells">
    Open the cell detail and verify answered prompts, competitors, sources, and underlying stored answers.
  </Step>

  <Step title="Prioritize with context">
    Combine the observed gap with business relevance, cohort size, evidence quality, and feasible ownership.
  </Step>
</Steps>

## Interpretation

Each cell applies the selected metric to one topic and provider intersection under active filters. Color is comparative context, not a universal performance threshold. A low cell can reflect limited answered prompts, a changed provider mix, or an actual SELF/DIRECT difference.

## Possible next actions

* If a cell has sparse data, test the monitoring cohort before planning remediation.
* If DIRECT occurrences dominate a well-supported cell, inspect answers and sources to form a competitive hypothesis.
* If an entire topic differs across providers, test whether the prompts and model coverage are comparable.

## Limitations

The matrix represents configured monitoring data, not every topic or provider output. Provider and model changes can affect cells. The REST tags endpoint is a separate contract and does not by itself reproduce the GEO Matrix or its product metric.

## Related pages

<CardGroup>
  <Card title="Tag Performance" href="/looker-studio/sources/tag-performance">
    Build a related report from documented tag data.
  </Card>

  <Card title="Tags API" href="/developers/endpoints/tags/list">
    Read the separate REST tags contract.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share the configured matrix view.
  </Card>

  <Card title="Highest-priority actions" href="/use-cases/reporting/highest-priority-actions">
    Turn verified observations into a work queue.
  </Card>

  <Card title="Brand presence by topic" href="/use-cases/visibility/for-which-topics-does-my-brand-appear">
    Analyze topic-level SELF presence.
  </Card>

  <Card title="Page Performance score" href="/use-cases/reporting/unified-ai-score-per-page">
    Review page-level signals separately.
  </Card>
</CardGroup>


# What are the highest-priority actions to improve my AI visibility?
Source: https://docs.qwairy.co/use-cases/reporting/highest-priority-actions

Validate Action Center suggestions against current evidence, business relevance, effort, dependencies, and measurement before accepting work.

## Direct answer

Use **Cockpit > Action Center** as decision support. Open each suggestion, verify its supporting data and current scope, then prioritize accepted work by business relevance, evidence strength, effort, dependencies, and the metric cohort you can monitor.

## Data required

Use Action Center suggestions and supporting records, the current Strategy context, configured prompts, providers and models, topics or tags, stored answers and citations, Site Readiness findings, Content Opportunities, owners, effort, and dependencies.

## Workflow

<Steps>
  <Step title="Review the suggestion">
    Open its evidence and confirm that the affected prompt, provider, source, page, or technical issue is still in scope.
  </Step>

  <Step title="Validate the hypothesis">
    Read underlying answers or technical findings. Separate observed facts from the proposed explanation and expected outcome.
  </Step>

  <Step title="Prioritize the work">
    Assess business relevance, evidence, reversibility, effort, dependencies, and measurement quality. Accept only work with an accountable owner.
  </Step>

  <Step title="Track and re-evaluate">
    Use the Action plan to record status, then compare later monitoring periods with the same cohort. Record external implementation separately.
  </Step>
</Steps>

## Interpretation

A suggestion is a hypothesis derived from current workspace data. Its order is relative to the configured Strategy and available evidence; it is not a forecast or guarantee. Completion in Action Center records workflow status, not proof of publication or metric impact.

## Possible next actions

* If a verified technical blocker prevents intended access, test the smallest safe correction before dependent content work.
* If a content gap is supported by relevant prompts and answers, test one evidence-led page or update.
* If priorities conflict, revise Strategy context and document the business decision rather than treating the queue as objective truth.

## Limitations

Suggestions can become stale when prompts, providers, competitors, content, or strategy changes. Some actions occur outside Qwairy and require separate evidence. MCP tools follow their own schemas and should not be assumed to mirror the product queue.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export supporting data for review.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Use supported MCP tools and schemas.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered evidence view.
  </Card>

  <Card title="Choose the intervention" href="/use-cases/reporting/prioritize-citations-content-technical">
    Compare content, source, and technical hypotheses.
  </Card>

  <Card title="Plan a monthly sprint" href="/use-cases/reporting/quick-wins-this-month">
    Select bounded tests for the current month.
  </Card>

  <Card title="Topic-provider weakness" href="/use-cases/reporting/biggest-topic-provider-weakness">
    Validate a candidate matrix gap.
  </Card>
</CardGroup>


# Can I integrate Qwairy data into my Looker Studio or BI dashboards?
Source: https://docs.qwairy.co/use-cases/reporting/integrate-looker-studio-bi

Use documented Looker Studio sources, exports, or the REST API, with explicit field mappings and reconciliation checks.

## Direct answer

Yes. Use Qwairy's documented Looker Studio sources for supported dashboard workflows, Exports for point-in-time files, or the REST API for a maintained custom integration. Confirm that your target tool supports the chosen connection and map each metric explicitly.

## Data required

Use the target dashboard requirements, Qwairy source or endpoint documentation, authentication and permissions, field names and types, metric formulas, brand classifications, timezone, refresh expectations, missing-data rules, and a reconciliation sample.

## Workflow

<Steps>
  <Step title="Choose the source">
    Select a Looker Studio data source, export, or REST endpoint based on required fields, freshness, and maintenance capacity.
  </Step>

  <Step title="Map the schema">
    Document dimensions, measures, units, filters, pagination, timezone, SELF/DIRECT semantics, and null handling.
  </Step>

  <Step title="Build a small comparison">
    Create one filtered table and reconcile it with the source product or endpoint response before expanding the dashboard.
  </Step>

  <Step title="Operate the integration">
    Monitor credentials, refreshes, schema changes, row counts, and metric-definition changes with an assigned owner.
  </Step>
</Steps>

## Interpretation

Looker Studio, exports, the product UI, and REST endpoints are separate surfaces. Similar labels can use different scope or formulas. In particular, REST performance Coverage is answers with a SELF mention divided by all returned answers; do not replace it with the product Coverage formula.

## Possible next actions

* If stakeholders need a live product investigation, test a Shared Link before building custom BI.
* If the dashboard joins business outcomes, preserve each source system's attribution and units.
* If reconciliation fails, isolate filters, timezone, pagination, and brand classification before changing formulas.

## Limitations

Supported fields, refresh behavior, quotas, permissions, and target-tool capabilities can vary. An API integration requires ongoing ownership. No connector removes the need to validate data freshness, completeness, and metric semantics.

## Related pages

<CardGroup>
  <Card title="REST API" href="/developers/introduction">
    Review API authentication and resources.
  </Card>

  <Card title="Exports" href="/documentation/workspace/exports">
    Create point-in-time datasets.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share filtered product views.
  </Card>

  <Card title="Automated reporting" href="/use-cases/reporting/automated-geo-reporting">
    Design an operated reporting workflow.
  </Card>

  <Card title="Page Performance score" href="/use-cases/reporting/unified-ai-score-per-page">
    Handle page-level source states and score context.
  </Card>

  <Card title="ROI comparison" href="/use-cases/impact/roi-geo-vs-traditional-seo">
    Join commercial data with explicit assumptions.
  </Card>
</CardGroup>


# How do I prioritize between fixing citations, creating content, and technical SEO?
Source: https://docs.qwairy.co/use-cases/reporting/prioritize-citations-content-technical

Choose the next intervention from verified access, relevance, source, and answer evidence rather than a universal priority order.

## Direct answer

There is no universal order. Start with the observed gap and eliminate prerequisites: fix a verified access problem when it blocks intended public pages; test content when relevant questions lack accurate first-party evidence; investigate source distribution when useful content exists but other domains are recorded instead.

## Data required

Use the configured prompt cohort, stored answers, SELF/DIRECT mentions, citation URLs, Content Opportunities, Source Explorer, Site Readiness and crawler findings, current first-party pages, business relevance, effort, risk, owner, and baseline metrics.

## Workflow

<Steps>
  <Step title="Define the target observation">
    State the prompt, provider, topic, page, and metric slice you want to understand. Avoid a site-wide objective without a cohort.
  </Step>

  <Step title="Check technical prerequisites">
    Verify access, status, directives, canonicalization, and discovery for the relevant public pages. Do not infer indexing from a passing check.
  </Step>

  <Step title="Check content relevance">
    Read the answers and existing pages to determine whether accurate first-party evidence addresses the audience need.
  </Step>

  <Step title="Check source context">
    Inspect recorded citation URLs and ownership. Choose one intervention and define how later observations will be compared.
  </Step>
</Steps>

## Interpretation

Technical access, content relevance, citation URLs, and SELF mentions are different layers. A technical fix can enable access without producing a citation; content can be useful without being cited; a citation can appear without a positive SELF mention.

## Possible next actions

* If a verified blocker affects the target page, test the smallest safe technical correction.
* If no suitable first-party evidence exists, test a focused content creation or update.
* If content and access are sound but DIRECT sources dominate, test a source-distribution or partnership hypothesis without promising citation.

## Limitations

The data cannot identify a single causal lever from correlation alone. Provider behavior and citations can change independently of your work. Effort and business value are organization-specific, so retain the assumptions behind the chosen priority.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export evidence for the decision.
  </Card>

  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Analyze URL-level source data.
  </Card>

  <Card title="Site Readiness" href="/documentation/optimize/site-readiness">
    Review verified technical findings.
  </Card>

  <Card title="Highest-priority actions" href="/use-cases/reporting/highest-priority-actions">
    Validate and organize Action Center suggestions.
  </Card>

  <Card title="Monthly sprint" href="/use-cases/reporting/quick-wins-this-month">
    Plan bounded, measurable tests.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Run a publishing experiment.
  </Card>
</CardGroup>


# What quick wins can I achieve to boost my GEO score this month?
Source: https://docs.qwairy.co/use-cases/reporting/quick-wins-this-month

Build a bounded monthly test plan from verified, reversible opportunities without promising a score change or fixed result window.

## Direct answer

Use **Cockpit > Action Center** to select a small set of well-supported actions that fit the current month. Favor clear ownership, reversible implementation, low dependency risk, and a stable measurement cohort. Define success as completing and learning from the test, not guaranteeing a GEO score increase.

## Data required

Use current Suggestions and Action plan items, supporting answers or technical findings, Strategy context, business relevance, effort, dependencies, owner, implementation evidence, baseline period, and the exact metric or qualitative observation for follow-up.

## Workflow

<Steps>
  <Step title="Create the candidate list">
    Review current suggestions and remove stale, unsupported, out-of-scope, or dependency-blocked items.
  </Step>

  <Step title="Select bounded tests">
    Choose actions that can be implemented and verified safely within the planning period. Separate external delivery from Action Center status.
  </Step>

  <Step title="Define evidence before work">
    Record baseline filters, expected observation, owner, completion evidence, and the date for a later comparable review.
  </Step>

  <Step title="Review the sprint">
    At month end, record what shipped, what was learned, and which observations changed. Carry forward only work that still has evidence and priority.
  </Step>
</Steps>

## Interpretation

A quick win describes bounded execution, not guaranteed external response. The product score or visibility metrics may remain unchanged within the month. Any later movement is an observation that requires stable filters and alternative-explanation checks.

## Possible next actions

* If a low-risk configuration issue is verified, test the smallest correction and confirm production behavior.
* If an important page contains an outdated fact, test a reviewed update and preserve the original evidence.
* If a suggestion lacks a measurable cohort, refine it before accepting it into the sprint.

## Limitations

Providers, models, sources, and monitoring data can change outside your control. Some useful actions require longer observation than one month. Qwairy cannot guarantee that completing an action changes a score, mention, citation, or referral metric.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Preserve the sprint baseline and follow-up data.
  </Card>

  <Card title="Site Readiness" href="/documentation/optimize/site-readiness">
    Review technical findings.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share the scoped evidence view.
  </Card>

  <Card title="Highest-priority actions" href="/use-cases/reporting/highest-priority-actions">
    Validate and rank suggestions.
  </Card>

  <Card title="Choose the intervention" href="/use-cases/reporting/prioritize-citations-content-technical">
    Compare technical, content, and source hypotheses.
  </Card>

  <Card title="Campaign impact" href="/use-cases/campaigns/campaign-impact-on-ai-visibility">
    Compare stable periods without claiming causation.
  </Card>
</CardGroup>


# How do I use Query Fan-Out to discover prompts I should monitor?
Source: https://docs.qwairy.co/use-cases/reporting/search-intelligence-discover-prompts

Turn relevant observed Query Fan-Out searches into configured prompts while preserving the distinction between the two records.

## Direct answer

Open **Monitor > Insights > Query Fan-Out** to review web searches detected during provider answer generation. When an observed query belongs in your monitoring scope, review its wording and add it as a configured prompt with a topic, funnel stage, and tags.

## Data required

Use observed Query Fan-Out records, usages, intent, associated answer and original configured prompt, provider, period, SELF/DIRECT mentions, current prompt inventory, topic taxonomy, funnel stage, tags, business relevance, and monitoring capacity.

## Workflow

<Steps>
  <Step title="Review observed queries">
    Filter to the intended topic and provider scope. Read the associated answer and original prompt before selecting a query.
  </Step>

  <Step title="Check relevance and duplication">
    Confirm that the audience need matters and that an equivalent configured prompt is not already monitored.
  </Step>

  <Step title="Create the prompt">
    Review the wording, then assign its primary topic, funnel stage, and reusable tags before saving.
  </Step>

  <Step title="Establish a baseline">
    Run the new prompt consistently and evaluate its answers separately before merging it into trend reporting.
  </Step>
</Steps>

## Interpretation

A query is a web search detected within provider answer generation; a prompt is the configured question Qwairy monitors. Adding a query creates a prompt for future runs and does not change the answer where the query was first observed. Product Coverage can change when the prompt set changes.

## Possible next actions

* If several queries express one intent, test one representative prompt rather than adding duplicates.
* If a query exposes a relevant content gap, create a separate publishing hypothesis after reviewing the associated answers and sources.
* If a new prompt produces little decision value, test whether it should remain in the monitoring scope.

## Limitations

Query Fan-Out metadata depends on provider output and Qwairy detection. Absence does not prove that no internal query expansion occurred. Expanding the prompt set changes dataset composition, resource use, and later aggregate comparisons.

## Related pages

<CardGroup>
  <Card title="Search Insights" href="/looker-studio/sources/search-insights">
    Report on documented Query Fan-Out data.
  </Card>

  <Card title="Query Fan-Out" href="/documentation/monitor/insights/query-fan-out">
    Review the product workflow and definitions.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Use supported MCP tools and schemas.
  </Card>

  <Card title="Monitoring prompts" href="/use-cases/setup/monitoring-right-prompts">
    Audit the configured prompt set.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Turn a verified gap into a publishing experiment.
  </Card>

  <Card title="Highest-priority actions" href="/use-cases/reporting/highest-priority-actions">
    Compare prompt opportunities with other work.
  </Card>
</CardGroup>


# What is the unified AI performance score for my most important pages?
Source: https://docs.qwairy.co/use-cases/reporting/unified-ai-score-per-page

Use Page Performance to inspect its site-wide percentile score and source breakdown without treating it as an absolute ranking or forecast.

## Direct answer

Open **Measure > Page Performance** and inspect the score breakdown. The score combines site-wide percentiles for AI-answer source mentions (40%), GA4 AI-referral sessions (25%), crawler occurrences (20%), and Google plus Bing clicks (15%). Use it as a relative Qwairy summary, then inspect each source column before prioritizing pages.

## Data required

Use normalized page paths, the current Page Performance scope, source connection states, recorded AI-answer source mentions, GA4 AI-referral sessions, retained crawler occurrences, Google and Bing clicks, and the displayed score breakdown.

## Workflow

<Steps>
  <Step title="Validate source states">
    Confirm which integrations are connected, populated, empty, disconnected, or unavailable. Outside the score, missing data is not an observed zero.
  </Step>

  <Step title="Reconcile page URLs">
    Normalize protocol, hostname, path, parameters, redirects, and canonical variants before comparing page rows.
  </Step>

  <Step title="Inspect the score breakdown">
    Record the four percentile components and whether crawler detail is measured. When it is not measured, the crawler component is `null` and the remaining 80% is normalized to 100%.
  </Step>

  <Step title="Review source columns">
    Sort by the metric relevant to the decision and inspect answer mentions, GA4 referrals, crawler occurrences, and Google plus Bing data as separate evidence.
  </Step>
</Steps>

## Interpretation

The page score is relative to the site's full path dataset, even when a folder filter is active. It is not an absolute quality grade, a search-engine ranking, a forecast, or proof of business impact. Disconnected non-crawler sources currently remain zero-valued in score inputs; their weights are not removed, so pages with different source coverage may not be comparable.

## Possible next actions

* If a page score is unexpected, test URL reconciliation and source-state issues before changing the page.
* If one source column is weak, form a hypothesis specific to that source rather than treating the score as a diagnosis.
* If an important source is unavailable, connect or validate it before using the score for prioritization.

## Limitations

Crawler page detail is limited to 30-day windows and can be bounded. Pseudonymized crawler paths are excluded from cross-source matching. Source coverage, refresh timing, and URL matching can change. The REST source-URLs endpoint is a separate contract and does not return this product score.

## Related pages

<CardGroup>
  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Review documented URL-level reporting.
  </Card>

  <Card title="Page Performance" href="/documentation/measure/page-performance">
    Understand page signals, source states, and score scope.
  </Card>

  <Card title="Source URLs API" href="/developers/endpoints/source-urls">
    Read the separate REST source-URL contract.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/sources/pages-with-most-ai-citations">
    Analyze recorded citation URLs separately.
  </Card>

  <Card title="AI traffic by page" href="/use-cases/impact/pages-with-most-ai-traffic">
    Review recognized AI-referral landing pages.
  </Card>

  <Card title="Content pickup observations" href="/use-cases/campaigns/how-fast-ai-picks-up-content">
    Track publication milestones separately.
  </Card>
</CardGroup>


# Is the AI perception of my brand aligned with our actual positioning?
Source: https://docs.qwairy.co/use-cases/reputation/ai-perception-vs-positioning

Compare themes in selected stored answers with your approved positioning, then investigate gaps without treating model output as market truth.

## Direct answer

Use **Analyze > Brand Perception** and the underlying stored answers to compare observed brand attributes with a current, approved positioning statement. Record alignment and divergence by prompt, provider, topic, and period. Treat the result as a view of the monitored dataset, not a complete measure of market perception.

## Data required

You need approved positioning claims with an owner and review date, a stable configured-prompt set, selected providers and models, stored answers, topics or tags, period, sentiment or perception outputs, and recorded citation URLs.

## Workflow

<Steps>
  <Step title="Define the reference">
    List the positioning attributes you intend to communicate and the evidence that supports each one. Exclude aspirational claims that are not yet true.
  </Step>

  <Step title="Select comparable answers">
    Choose prompts, providers, topics, and a period relevant to those attributes. Keep the cohort stable for later comparisons.
  </Step>

  <Step title="Review perception and evidence">
    Use Brand Perception to identify recurring observed themes, then read representative answers and their citations before classifying a gap.
  </Step>

  <Step title="Document the gap">
    For each attribute, record aligned, missing, contradictory, or unsupported output with the answer and filter context.
  </Step>
</Steps>

## Interpretation

A recurring attribute describes stored answers in the selected cohort. It does not establish what every user, provider, or market participant believes. Provider differences may reflect prompts, models, web access, sources, or sampling; the data alone does not identify the cause.

## Possible next actions

* If an intended attribute is missing, test whether an accurate first-party evidence page would make the positioning easier to verify.
* If an unsupported attribute recurs, investigate the cited sources and your own public copy before choosing a correction.
* If divergence appears in one provider slice, repeat the same prompt cohort before changing the broader positioning strategy.

## Limitations

Brand Perception is an analysis of observed outputs, not an independent reputation survey. Model outputs and source sets can change. The MCP surface follows its own documented tools and schemas; do not assume it returns the same aggregation as the product.

## Related pages

<CardGroup>
  <Card title="Brand Perception" href="/documentation/analyze/brand-perception">
    Review the product analysis and its scope.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Report on stored answers with documented dimensions.
  </Card>

  <Card title="Qwairy MCP" href="/mcp/introduction">
    Use supported MCP tools and schemas.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Read the underlying stored answers.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Form a content hypothesis from a verified gap.
  </Card>

  <Card title="Strengths and weaknesses" href="/use-cases/reputation/strengths-and-weaknesses-in-ai">
    Group recurring observed attributes.
  </Card>

  <Card title="Negative sentiment by topic" href="/use-cases/reputation/negative-sentiment-on-topics">
    Inspect topic-specific sentiment separately.
  </Card>
</CardGroup>


# Do different AI providers describe my brand consistently?
Source: https://docs.qwairy.co/use-cases/reputation/brand-consistency-across-providers

Compare equivalent prompt cohorts across providers and models to identify observed narrative differences without assuming their cause.

## Direct answer

Run the same configured prompts across the providers and models you want to compare, then review the stored answers side by side. Classify recurring claims, sentiment, and omissions. Consistency means similarity within that selected dataset, not agreement across every possible response.

## Data required

Use identical configured prompts, aligned run periods, provider and model identifiers, stored answers, topics or tags, sentiment or perception labels, and citation URLs. Keep the provider family distinct from the selected model.

## Workflow

<Steps>
  <Step title="Create the comparison cohort">
    Choose prompts that can be run meaningfully across the selected providers. Use the same brand, topic, geography, and period filters.
  </Step>

  <Step title="Read answers side by side">
    Compare factual claims, positioning themes, sentiment, SELF and DIRECT mentions, and recorded citations.
  </Step>

  <Step title="Separate stable and isolated patterns">
    Mark themes repeated across several answers separately from one-off wording or provider-specific omissions.
  </Step>

  <Step title="Recheck material differences">
    Repeat important comparisons on later runs and verify factual claims against approved sources before escalating them.
  </Step>
</Steps>

## Interpretation

Differences are observations, not proof that one provider is correct or biased. A provider is a service family; a model is a selectable model within that family. Changes in model, web access, prompt execution, or source availability can affect the comparison.

## Possible next actions

* If a factual discrepancy repeats, test a correction through accurate public source material.
* If one model omits a positioning attribute, investigate the answers and citations before assuming a distribution problem.
* If narratives are broadly consistent but outdated, prioritize updating the authoritative source of the outdated claim.

## Limitations

Stored answers are samples from configured runs. They do not represent every provider output, user context, locale, or future model version. The REST answers endpoint is a separate data contract; confirm its fields and pagination before comparing exports.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export the selected comparison cohort.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Build provider and model comparisons in Looker Studio.
  </Card>

  <Card title="Answers API" href="/developers/endpoints/answers/list">
    Read the separate REST answers contract.
  </Card>

  <Card title="Prioritize providers" href="/use-cases/setup/which-providers-to-prioritize">
    Choose providers relevant to your audience.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Review answer narratives directly.
  </Card>

  <Card title="Why a competitor is recommended" href="/use-cases/providers/why-chatgpt-recommends-competitor">
    Investigate a provider-specific comparison.
  </Card>

  <Card title="Perception versus positioning" href="/use-cases/reputation/ai-perception-vs-positioning">
    Compare observed themes with approved positioning.
  </Card>
</CardGroup>


# How do I correct misinformation that AI is spreading about my brand?
Source: https://docs.qwairy.co/use-cases/reputation/correct-ai-misinformation

Verify inaccurate claims in stored answers, trace available sources, correct authoritative public information, and monitor later outputs.

## Direct answer

First verify the claim against a current authoritative source. Save the stored answer, prompt, provider, model, date, and cited URLs. Correct inaccurate information on sources you control and contact third-party publishers when appropriate, then monitor comparable future runs. Qwairy cannot directly edit a provider's output.

## Data required

You need the exact stored answer, configured prompt, provider and model, run date, citation URLs, an approved factual source, the accountable owner, and a stable monitoring cohort. For sensitive legal or safety claims, involve the appropriate reviewer.

## Workflow

<Steps>
  <Step title="Verify the discrepancy">
    Compare the answer with a dated, approved source of truth. Distinguish false, outdated, ambiguous, and opinion-based statements.
  </Step>

  <Step title="Trace available evidence">
    Inspect recorded citation URLs and relevant public pages. A citation may help locate a source, but it does not prove that the provider derived the claim from it.
  </Step>

  <Step title="Correct authoritative sources">
    Update inaccurate owned content through its normal review process. For third-party content, request a correction with evidence rather than making unsupported attribution claims.
  </Step>

  <Step title="Monitor comparable runs">
    Keep the original prompt and filters, review later stored answers, and record whether the claim persists, changes, or disappears.
  </Step>
</Steps>

## Interpretation

A corrected public page followed by a changed answer is an observed sequence, not proof of causation. A mention and a citation are separate: a claim can mention your brand without citing your domain, and a source URL can be recorded without a brand mention.

## Possible next actions

* If the cited source is outdated, test a correction at that source or publish a dated first-party clarification.
* If no source is recorded, test whether your authoritative fact is easy to find and unambiguous in public materials.
* If the claim varies by provider or model, maintain separate evidence records for each affected cohort.

## Limitations

Providers control their outputs, retrieval, and update timing. No source change guarantees correction or persistence. Qwairy observes selected stored answers only and cannot establish exactly which source or process produced a claim.

## Related pages

<CardGroup>
  <Card title="Analyzing Answers" href="/documentation/monitor/analyzing-answers">
    Review stored answers and available context.
  </Card>

  <Card title="Exports" href="/documentation/workspace/exports">
    Preserve a filtered evidence set.
  </Card>

  <Card title="GEO guide" href="https://www.qwairy.co/guides/complete-guide-to-generative-engine-optimization">
    Read additional background guidance.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Locate material claims in stored answers.
  </Card>

  <Card title="Websites influencing answers" href="/use-cases/sources/which-websites-influence-ai">
    Investigate recorded sources without assuming causation.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Plan an evidence-led content hypothesis.
  </Card>

  <Card title="Perception versus positioning" href="/use-cases/reputation/ai-perception-vs-positioning">
    Track broader narrative alignment.
  </Card>
</CardGroup>


# Is AI generating negative sentiment about my brand on specific topics?
Source: https://docs.qwairy.co/use-cases/reputation/negative-sentiment-on-topics

Filter sentiment by topic, provider, model, and period, then read the underlying stored answers before interpreting a pattern.

## Direct answer

Use **Analyze > Sentiment Analysis** to filter results by topic and inspect the stored answers classified as negative. Confirm that each answer concerns your brand and the intended topic before treating it as a pattern.

## Data required

Use a stable prompt set, primary topics, optional tags, provider and model, period, stored answers, sentiment classifications, SELF/DIRECT mentions, and citation URLs. Keep topic assignment separate from reusable tags.

## Workflow

<Steps>
  <Step title="Choose the topic cohort">
    Select the relevant topic, period, providers, and models. Confirm that the configured prompts actually test the concern.
  </Step>

  <Step title="Review the distribution">
    Compare sentiment categories and answer counts within the selected cohort. Retain the denominator and filters in any report.
  </Step>

  <Step title="Read the underlying answers">
    Inspect representative negative and non-negative answers. Separate factual criticism, trade-offs, unsupported claims, and irrelevant classifications.
  </Step>

  <Step title="Compare related slices">
    Check whether the pattern persists across prompts, providers, models, and later runs without changing several filters at once.
  </Step>
</Steps>

## Interpretation

Sentiment is a classification of observed answer language, not a customer-satisfaction or brand-health score. A higher negative share in one topic can reflect prompt wording, a small answer count, provider mix, or a real recurring narrative. The data supports investigation, not a universal threshold.

## Possible next actions

* If a factual negative claim recurs, verify it and test a correction workflow with authoritative evidence.
* If criticism reflects a genuine trade-off, test clearer positioning about the intended audience and limitations.
* If the result is driven by one prompt, revise the monitoring design only after confirming that the prompt is unrepresentative.

## Limitations

Automated sentiment can misclassify nuance, comparisons, or quoted text. Results cover the selected stored answers only. The REST answers endpoint exposes its own fields; do not assume product sentiment aggregations are reproduced without verification.

## Related pages

<CardGroup>
  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Report on the underlying answer records.
  </Card>

  <Card title="Sentiment Analysis" href="/documentation/analyze/sentiment-analysis">
    Review the product sentiment workflow.
  </Card>

  <Card title="Answers API" href="/developers/endpoints/answers/list">
    Use the documented REST answers contract.
  </Card>

  <Card title="Sentiment after an event" href="/use-cases/reputation/sentiment-after-crisis-or-launch">
    Compare stable cohorts across periods.
  </Card>

  <Card title="Monitoring prompts" href="/use-cases/setup/monitoring-right-prompts">
    Audit whether prompts cover the intended topic.
  </Card>

  <Card title="Correct misinformation" href="/use-cases/reputation/correct-ai-misinformation">
    Address verified factual errors.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Read stored answers in context.
  </Card>
</CardGroup>


# How has AI sentiment changed after a PR crisis or product launch?
Source: https://docs.qwairy.co/use-cases/reputation/sentiment-after-crisis-or-launch

Compare stable pre-event and post-event answer cohorts, then report observed sentiment changes without attributing them to the event.

## Direct answer

Define the event date, freeze a relevant prompt and provider cohort, and compare sentiment distributions before and after the event. Read the underlying answers and report the change as temporal association. The comparison alone cannot show that the crisis or launch caused it.

## Data required

You need the dated event, unchanged configured prompts, topics or tags, providers and models, comparable pre-event and post-event periods, stored answers, sentiment classifications, SELF/DIRECT mentions, and citation URLs.

## Workflow

<Steps>
  <Step title="Define the comparison">
    Record the event date and choose pre-event and post-event periods that use the same monitoring configuration.
  </Step>

  <Step title="Check cohort stability">
    Confirm prompts, topics, providers, models, geography, and run coverage. Note any configuration or model changes.
  </Step>

  <Step title="Compare and inspect">
    Compare sentiment distributions with answer counts, then read representative answers from both periods.
  </Step>

  <Step title="Document alternative explanations">
    Record concurrent announcements, source updates, competitor events, prompt changes, and small sample sizes.
  </Step>
</Steps>

## Interpretation

A difference between periods is an observed change in selected stored answers. It may be associated with the event, but it does not establish causation. Report counts, shares, filters, and examples together; do not label a percentage as good or bad without a stated business baseline.

## Possible next actions

* If a verified factual issue appears after the event, test an authoritative clarification and keep the original comparison cohort.
* If the change occurs only in one provider or prompt, investigate that slice before making a broader reputation decision.
* If answer counts are sparse, extend observation or combine only genuinely comparable runs.

## Limitations

Provider models, retrieval behavior, sources, and monitoring configuration can change between periods. Sentiment classification can miss nuance. A return toward the earlier distribution does not prove that communications or content caused the change.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export comparable pre-event and post-event cohorts.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Build a time-based answer report.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered product view.
  </Card>

  <Card title="Visibility over time" href="/use-cases/visibility/how-has-my-visibility-changed">
    Apply the same cohort discipline to visibility metrics.
  </Card>

  <Card title="Correct misinformation" href="/use-cases/reputation/correct-ai-misinformation">
    Address verified factual discrepancies.
  </Card>

  <Card title="Negative sentiment by topic" href="/use-cases/reputation/negative-sentiment-on-topics">
    Locate the topics behind the observed change.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Read the underlying answers.
  </Card>
</CardGroup>


# What are the strengths and weaknesses AI associates with my brand?
Source: https://docs.qwairy.co/use-cases/reputation/strengths-and-weaknesses-in-ai

Group recurring positive and negative attributes in selected stored answers, then verify their context and evidence before acting.

## Direct answer

Use **Analyze > Brand Perception** to identify recurring attributes, then read the answers that support each theme. Classify an attribute as an observed strength or weakness only for the selected prompts, providers, models, topics, and period.

## Data required

Use stored answers, configured prompts, provider and model, period, topics and tags, perception or sentiment outputs, SELF/DIRECT mentions, citation URLs, and your approved positioning and product facts.

## Workflow

<Steps>
  <Step title="Choose a representative cohort">
    Select prompts that cover the decisions and topics you care about. Avoid mixing unrelated audience needs.
  </Step>

  <Step title="Review recurring attributes">
    Use Brand Perception to locate repeated positive and negative themes. Retain answer counts and filters.
  </Step>

  <Step title="Read and verify">
    Inspect representative answers and citations. Separate supported facts, subjective trade-offs, outdated claims, and classification errors.
  </Step>

  <Step title="Compare with positioning">
    Map each verified theme to an approved positioning attribute and note aligned, missing, or conflicting observations.
  </Step>
</Steps>

## Interpretation

Frequency in stored answers indicates recurrence in the monitored dataset, not objective product quality or broad market opinion. Positive sentiment is not equivalent to a recommendation, and a negative trade-off may be appropriate for an audience outside your positioning.

## Possible next actions

* If a supported strength is absent from important prompts, test clearer evidence or positioning on relevant first-party pages.
* If a weakness is factual and outdated, test the misinformation correction workflow.
* If a weakness is a valid trade-off, test content that explains intended fit rather than trying to suppress it.

## Limitations

Perception and sentiment analyses can simplify nuanced language. Results depend on prompt design, provider and model mix, and the selected period. They do not measure customer experience or predict commercial outcomes.

## Related pages

<CardGroup>
  <Card title="Brand Perception" href="/documentation/analyze/brand-perception">
    Review observed perception themes in the product.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Analyze the supporting answers in Looker Studio.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered review with stakeholders.
  </Card>

  <Card title="What AI says" href="/use-cases/reputation/what-does-ai-say-about-my-brand">
    Read stored answers directly.
  </Card>

  <Card title="Choose what to create" href="/use-cases/content/what-content-to-create">
    Turn a verified gap into a content hypothesis.
  </Card>

  <Card title="Perception versus positioning" href="/use-cases/reputation/ai-perception-vs-positioning">
    Compare themes with approved positioning.
  </Card>

  <Card title="Correct misinformation" href="/use-cases/reputation/correct-ai-misinformation">
    Address verified factual errors.
  </Card>
</CardGroup>


# What does AI actually say about my brand?
Source: https://docs.qwairy.co/use-cases/reputation/what-does-ai-say-about-my-brand

Read selected stored answers and summarize recurring claims, themes, and sentiment with their prompt, provider, model, and period context.

## Direct answer

Open **Monitor > Response Analysis**, filter to your brand and intended scope, and read the stored provider outputs. Summarize recurring claims only after checking the configured prompts, provider and model, topic, date, sentiment, and cited URLs.

## Data required

Use configured prompts, stored answers, provider and model identifiers, run dates, topics and tags, SELF/DIRECT mention classification, sentiment or perception outputs, and citation URLs. Define the review period before exporting or sharing.

## Workflow

<Steps>
  <Step title="Set the review scope">
    Choose the business question, prompt set, providers, models, topics, and period. Avoid combining unrelated cohorts.
  </Step>

  <Step title="Read representative answers">
    Review answers with SELF mentions as well as relevant answers where only DIRECT brands appear. Keep mentions and citations separate.
  </Step>

  <Step title="Code recurring themes">
    Group supported claims, opinions, omissions, and sentiment patterns. Record how many answers support each theme and retain examples.
  </Step>

  <Step title="Verify material claims">
    Compare factual statements with approved sources and flag anything outdated, ambiguous, or unsupported for follow-up.
  </Step>
</Steps>

## Interpretation

A stored answer is one observed provider output for a configured prompt and run. It is not a statement from all users or all models. Product Mention Rate is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention; it does not measure sentiment or citation presence.

## Possible next actions

* If a recurring claim is accurate and relevant, test whether it aligns with intended positioning.
* If a factual claim is wrong, follow a documented correction workflow using authoritative evidence.
* If an important topic has few answers, review the monitoring design before concluding that no narrative exists.

## Limitations

Outputs can vary between runs and model versions. Automated themes and sentiment require review against the original answer. Qwairy observes the selected stored dataset and cannot make exhaustive claims about what AI says everywhere.

## Related pages

<CardGroup>
  <Card title="Exports" href="/documentation/workspace/exports">
    Export the selected answer cohort.
  </Card>

  <Card title="Answer Details" href="/looker-studio/sources/answer-details">
    Create reporting from stored answer records.
  </Card>

  <Card title="Shared Links" href="/documentation/workspace/shared-links">
    Share a filtered product view.
  </Card>

  <Card title="Perception versus positioning" href="/use-cases/reputation/ai-perception-vs-positioning">
    Compare observed themes with approved positioning.
  </Card>

  <Card title="Strengths and weaknesses" href="/use-cases/reputation/strengths-and-weaknesses-in-ai">
    Group recurring observed attributes.
  </Card>

  <Card title="Provider consistency" href="/use-cases/reputation/brand-consistency-across-providers">
    Compare equivalent cohorts across providers and models.
  </Card>

  <Card title="Topics with brand presence" href="/use-cases/visibility/for-which-topics-does-my-brand-appear">
    Analyze SELF presence by topic.
  </Card>
</CardGroup>


# Am I monitoring the right prompts to track my AI visibility?
Source: https://docs.qwairy.co/use-cases/setup/monitoring-right-prompts

Audit whether your monitored prompts cover the topics, audiences, and funnel stages that matter to your analysis.

## Direct answer

A useful prompt set represents the decisions you want to study, not every possible question about your market. Review prompt wording, topic coverage, funnel stages, markets, providers, and models together. There is no universal prompt count that makes the dataset representative.

## Data required

* Your active prompts in **Workspace > Prompts**
* Topic, tag, and funnel-stage assignments for those prompts
* The provider, model, country, language, and monitoring settings in **Workspace > Monitoring**
* Completed answers for a consistent analysis period
* A separate list of the products, audiences, and buyer decisions you intend to monitor

Optional discovery inputs include Google Search Console data and Query Fan-Out records. Query Fan-Out contains web queries observed during provider processing; it is not a measure of user search demand.

## Workflow

1. In **Workspace > Prompts**, remove duplicates and flag prompts that name your brand when the purpose is to measure category discovery.
2. Group the remaining prompts by topic and funnel stage. Compare that structure with the products, audiences, and decisions in your monitoring brief.
3. In **Workspace > Monitoring**, verify that the intended providers, models, countries, languages, and schedule apply to the prompt set.
4. In **Monitor > Prompt Tracking**, apply one scope at a time and inspect prompts with missing answers, no SELF mention, or materially different results across providers.
5. Read the corresponding answers in **Monitor > Response Analysis** before deciding that an absence represents an opportunity.
6. Use Query Fan-Out or connected search data only to propose candidate prompts. Review each candidate for relevance before adding it.

## Interpretation

Product **Coverage** is prompt-level: distinct answered prompts with at least one SELF mention divided by distinct answered prompts. Product **Mention Rate** is answer-level: answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention.

Keep these units separate. A prompt can be covered because one answer mentions your brand while still having a low answer-level Mention Rate across providers or models. A prompt with no SELF mention may expose a meaningful gap, an irrelevant question, or an incomplete sample.

## Possible next actions

* Test whether adding a missing, category-neutral decision prompt changes what you learn about a topic.
* Test whether splitting an ambiguous prompt into clearer intents produces more interpretable answers.
* Pause a prompt as a reversible experiment when its answers consistently fall outside the intended category.
* Add a tag before changing the prompt set when the apparent gap may be a reporting-structure problem.

Treat each action as a hypothesis. Record the prompt-set change so comparisons do not mix different portfolios without explanation.

## Limitations

* Qwairy observes answers generated for your configured prompts; it does not prove that the set represents all user demand.
* Provider and model output can vary between runs.
* Changing prompts, providers, models, countries, or schedules changes the measured population and can break trend comparability.
* Missing answers are not evidence of brand absence.

## Related pages

* [Track prompts](/documentation/monitor/tracking-queries)
* [Organize prompts with topics and tags](/use-cases/setup/organize-prompts-tags-topics)
* [Discover prompt candidates with Search Intelligence](/use-cases/reporting/search-intelligence-discover-prompts)


# How should I organize my prompts with tags, topics, and funnel stages?
Source: https://docs.qwairy.co/use-cases/setup/organize-prompts-tags-topics

Build a stable prompt taxonomy with topics, reusable tags, and funnel stages for consistent filtering and reporting.

## Direct answer

Use a **Topic** as the primary semantic grouping for a prompt. Use **Tags** as reusable labels that can cut across topics, such as audience, product line, or campaign. Use the prompt's funnel stage for buyer-journey analysis. Design these fields around decisions you expect to compare, then keep the names stable.

## Data required

* The current prompt inventory
* The product areas and use cases used by your team
* The audience, market, and campaign dimensions you need to filter
* The funnel-stage convention your team will apply
* An owner for taxonomy changes and a list of accepted names

## Workflow

1. Draft a short topic list where each topic represents one durable business area.
2. In **Workspace > Topics**, create or consolidate those primary groupings.
3. Define tags only for dimensions that need to span topics. Manage them in **Workspace > Tags**.
4. In **Workspace > Prompts**, assign one primary topic, the relevant reusable tags, and a funnel stage to each prompt.
5. Open **Cockpit > GEO Matrix** and **Cockpit > Compare**. Apply each topic, tag, and funnel filter to confirm that the resulting groups answer a real question.
6. Review unassigned prompts and near-duplicate labels before using the taxonomy in exports or Looker Studio.

## Interpretation

A useful taxonomy produces groups that are distinct enough to compare and large enough to inspect in context. A topic with no answered prompts is an empty state, not poor performance. A group with very few answers can change sharply when one answer changes.

When comparing groups, preserve the same period, providers, models, countries, and competitor classification. Product Mention Rate and Citation Rate are answer-level metrics with response-based denominators; Product Coverage is prompt-level. Do not treat those percentages as interchangeable.

## Possible next actions

* Test whether merging duplicate tags makes filtered reports easier to interpret.
* Test whether a broad topic should be split when it contains separate decisions with different answer patterns.
* Add a reusable audience tag when the same segment appears across several topics.
* Document a naming rule before allowing multiple editors to extend the taxonomy.

Treat taxonomy changes as hypotheses about better analysis. Record renames and merges because they can change historical groupings.

## Limitations

* Topic and tag assignments describe your taxonomy; they do not prove market demand or business importance.
* Funnel-stage labels require consistent human judgment.
* Small or uneven groups can produce unstable comparisons.
* Renaming or reassigning prompts can make a trend look different without any underlying answer change.

## Related pages

* [Manage topics](/documentation/workspace/topics)
* [Manage tags](/documentation/workspace/tags)
* [Analyze visibility by topic](/use-cases/visibility/for-which-topics-does-my-brand-appear)


# Which AI providers should I prioritize monitoring and why?
Source: https://docs.qwairy.co/use-cases/setup/which-providers-to-prioritize

Prioritize providers with evidence from visibility, audience relevance, referral traffic, and competitive observations.

## Direct answer

Prioritize providers according to your audience and decision context. Combine Qwairy visibility data with connected referral analytics and competitive observations. Do not infer priority from provider popularity alone, and keep the distinction between a provider family and a specific model.

## Data required

* Completed answers for the same prompts across the providers or models being compared
* Provider-level metrics and raw answer counts from **Cockpit > Overview**
* Referral sessions by source from **Measure > Referrer Analytics**, when an analytics integration is connected
* Your target countries, languages, audiences, and buyer journeys
* Current provider and model settings from **Workspace > Monitoring**

## Workflow

1. In **Cockpit > Overview**, select a fixed period, prompt set, country, and language.
2. Compare providers using both raw answer counts and product metrics. Exclude providers with missing or materially smaller samples from a direct ranking.
3. In **Cockpit > Compare**, inspect whether DIRECT competitors appear differently under the same provider and model filters.
4. If Referrer Analytics is configured, compare observed AI referral sessions with visibility. Keep traffic and visibility as separate measures.
5. Read representative answers in **Monitor > Response Analysis** to understand what each aggregate hides.
6. In **Workspace > Monitoring**, adjust provider or model coverage only after documenting the evidence and expected trade-off.

## Interpretation

Product Mention Rate is response-level: answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. Product Coverage is prompt-level: distinct answered prompts with a SELF mention divided by distinct answered prompts.

A provider can have high Coverage but a lower Mention Rate, or send observed referral traffic despite limited monitored visibility. These are different populations. Referral sessions show visits attributed by the connected analytics source; they do not measure every user interaction with a provider.

## Possible next actions

* Test broader monitoring on a provider that is audience-relevant but has an incomplete answer sample.
* Test whether a low-visibility, observed-traffic provider deserves more prompt coverage.
* Reduce frequency for a low-evidence provider as a reversible credit-allocation experiment.
* Separate models within one provider when model-level behavior is masking meaningful differences.

Treat prioritization as a hypothesis and review it after collecting a comparable dataset.

## Limitations

* Provider and model availability can depend on the current product configuration and market.
* Referrer Analytics requires connected analytics data and only covers attributable visits.
* Unequal prompt, model, country, or time coverage invalidates a simple percentage ranking.
* Visibility, citations, and referral traffic are associated observations; none proves that one caused another.

## Related pages

* [Read Cockpit Overview](/documentation/cockpit/performance-dashboard)
* [Use Referrer Analytics](/documentation/measure/referrer-analytics)
* [Compare provider mentions](/use-cases/visibility/which-providers-mention-my-brand)


# Are AI models citing outdated or inaccurate information about my brand?
Source: https://docs.qwairy.co/use-cases/sources/ai-citing-outdated-info

Compare claims in stored answers with authoritative current evidence, then inspect exposed citations without assuming causality.

## Direct answer

Read the stored answer, identify a specific claim, and compare it with an authoritative current source. Then inspect the citations exposed with that answer. A cited page can be associated with the answer without being the source of the inaccurate claim.

## Data required

* The exact answer text, generation time, provider, and model
* The prompt and active country, language, topic, and period filters
* Exposed citation domains and URLs
* An authoritative, dated record of the correct fact
* Relevant SELF page versions or update dates

## Workflow

1. In **Monitor > Response Analysis**, filter to the relevant provider, model, and prompt.
2. Copy the precise claim that may be inaccurate and record the answer generation time.
3. Verify the claim against an approved current source outside the generated answer.
4. In **Monitor > Source Explorer**, inspect URLs exposed with the same answer.
5. Open the cited pages and determine whether they contain the stale claim, a conflicting claim, or no related claim.
6. Track the same prompt and model after the authoritative information is corrected.

## Interpretation

Classify each case as confirmed inaccurate, potentially outdated, ambiguous, or unsupported. Separate the generated claim from the content of each cited page.

A citation does not prove that the provider used that page for the disputed statement. An answer can contain both accurate and inaccurate claims, and a current source can be cited alongside stale generated text.

## Possible next actions

* Correct an outdated SELF page and expose a clear update date.
* Consolidate conflicting SELF pages around one canonical statement.
* Contact an independent publisher when its page contains a verifiable error.
* Monitor a fixed prompt cohort after the correction.

Treat any expected answer change as a hypothesis; providers control retrieval and generation.

## Limitations

* Qwairy stores exposed citations, not every source used internally.
* Providers may rely on undisclosed or older information.
* A later corrected answer does not prove which action caused the change.
* Historical page content may require a separate archive or change log.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Explore content sources](/documentation/monitor/content-sources)
* [Correct AI misinformation](/use-cases/reputation/correct-ai-misinformation)


# What backlink opportunities exist to boost my brand in AI results?
Source: https://docs.qwairy.co/use-cases/sources/backlink-opportunities-for-ai

Review Backlink Opportunities as source hypotheses, then validate relevance, answer context, and editorial feasibility.

## Direct answer

Use **Act > Backlink Opportunities** to find candidate domains observed in the source dataset. Validate each candidate against the underlying prompts, answers, and pages. A backlink does not guarantee a future citation, mention, or visibility change.

## Data required

* Backlink Opportunity records for the selected scope
* Source domains and URLs exposed with stored answers
* SELF and DIRECT competitor classifications
* The prompts and answers associated with each candidate source
* A relevant SELF page and a legitimate editorial reason for a link

## Workflow

1. In **Act > Backlink Opportunities**, set the intended period and filters.
2. Select a candidate and inspect the observed domain, URL, competitor context, and source frequency.
3. In **Monitor > Source Explorer**, confirm the source appears in relevant answers rather than unrelated prompts.
4. Read those answers in **Monitor > Response Analysis**.
5. Review the candidate page for topical fit, editorial policy, freshness, and whether your evidence adds value.
6. Record outreach or content work separately, then compare later citations on a fixed prompt cohort.

## Interpretation

An opportunity is a candidate for investigation, not an authority score or guaranteed placement. Domain-level frequency can hide that only one URL is relevant. A source cited with a competitor mention is not necessarily cited because of that competitor.

Keep link acquisition, SELF Citation Rate, SELF mentions, and traffic as separate outcomes.

## Possible next actions

* Test outreach where your original evidence directly improves a relevant independent page.
* Improve a SELF resource before asking another publisher to reference it.
* Reject a high-frequency domain when its cited pages do not match your topic.
* Track citation and mention observations after a legitimate placement.

## Limitations

* Qwairy observes exposed citations, not provider retrieval rules.
* Editorial decisions and link durability are outside Qwairy.
* Co-occurrence does not establish that a backlink caused a provider output.
* Provider citations can vary between runs.

## Related pages

* [Use Backlink Opportunities](/documentation/act/backlink-opportunities)
* [Compare competitor-only sources](/use-cases/competitors/sources-cited-for-competitors-not-me)
* [Explore source domains in Looker Studio](/looker-studio/sources/source-domains)


# Which of my website pages get the most AI citations?
Source: https://docs.qwairy.co/use-cases/sources/pages-with-most-ai-citations

Rank observed SELF URLs by citation records, answer breadth, and prompt breadth while preserving the selected scope.

## Direct answer

Filter **Monitor > Source Explorer** to SELF URLs and compare the displayed citation volume. Pair it with distinct answers and prompts where possible, because repeated citations in a narrow cohort can dominate a simple total.

## Data required

* Citation URLs classified as SELF
* Canonical URL, redirect, and subdomain mappings
* Citation counts by URL
* Distinct answers and prompts associated with each URL
* Fixed provider, model, country, language, topic, tag, and period filters

## Workflow

1. In **Monitor > Source Explorer**, set the analysis scope and filter to SELF sources.
2. Switch to URL-level detail and record citation volume for each page.
3. Consolidate equivalent URLs caused by redirects, parameters, protocol, or trailing-slash variants.
4. Open the answers and prompts associated with leading pages.
5. Compare topic and provider distribution so a narrow cluster is not mistaken for broad source use.
6. Repeat for another period only with the same URL mapping and filters.

## Interpretation

URL citation volume is not Product Citation Rate. Product Citation Rate is response-level: answers citing a SELF source divided by answers citing at least one SELF or DIRECT source.

A highly cited page may be cited repeatedly in one topic or may support a generic fact. Citation does not imply a brand mention, positive context, influence, or referral visit.

## Possible next actions

* Test whether maintaining a frequently cited page preserves its relevance in later observations.
* Consolidate duplicate SELF pages when URL fragmentation obscures the canonical source.
* Investigate an important topic where no relevant SELF URL is observed.
* Review cited claims for accuracy and freshness before expanding the page.

Treat future citation changes as hypotheses.

## Limitations

* Qwairy records citations exposed with stored answers.
* URL normalization can split or merge records incorrectly.
* Providers differ in citation behavior.
* Citation volume alone does not measure authority, traffic, or business value.

## Related pages

* [Explore content sources](/documentation/monitor/content-sources)
* [Inspect source URLs in Looker Studio](/looker-studio/sources/source-urls)
* [Compare cited links with mentions](/use-cases/visibility/cited-with-link-vs-just-mentioned)


# Are Reddit threads or forum posts influencing what AI says about my brand?
Source: https://docs.qwairy.co/use-cases/sources/reddit-forums-influencing-ai

Find community sources exposed with stored answers and compare their claims with answer text without inferring influence.

## Direct answer

Use **Monitor > Insights > Social Signals** and **Monitor > Source Explorer** to find Reddit or forum URLs exposed with stored answers. Compare their content with the answer, but describe the relationship as observed citation or co-occurrence, not proven influence.

## Data required

* Stored answers and their exposed community-source URLs
* Provider, model, prompt, country, language, topic, and period filters
* The text and publication or update date of relevant threads
* SELF and competitor mentions in the associated answers
* A current authoritative source for disputed claims

## Workflow

1. In **Monitor > Insights > Social Signals**, set the analysis scope and identify community domains or threads.
2. In **Monitor > Source Explorer**, inspect the corresponding URLs and citation volume.
3. Open associated answers in **Monitor > Response Analysis**.
4. Compare the answer's claims and wording with the thread content.
5. Separate direct citations, loose thematic overlap, and unrelated co-occurrence.
6. Track the same prompt cohort after correcting authoritative information or addressing a recurring issue.

## Interpretation

A cited thread is evidence that the URL was exposed with an observed answer. Similar wording can support a hypothesis, but neither proves that the thread caused the output.

Compare distinct answers, prompts, providers, and topics rather than relying on repeated citations to one thread. Sentiment in a forum is not equivalent to detected sentiment in an AI answer or to customer opinion.

## Possible next actions

* Correct factual errors on channels you control and publish an authoritative reference.
* Respond transparently in a community when participation is appropriate and permitted.
* Investigate a recurring product issue instead of optimizing only for the citation.
* Monitor a fixed cohort to see whether the observed pattern changes.

## Limitations

* Qwairy does not expose every source used by a provider.
* Threads can change, be deleted, or contain mixed viewpoints.
* Platform and community policies govern participation.
* Co-occurrence and wording similarity do not establish causality.

## Related pages

* [Use Social Signals](/documentation/monitor/insights/social-intelligence)
* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Investigate outdated information](/use-cases/sources/ai-citing-outdated-info)


# Which websites influence what AI says about my brand?
Source: https://docs.qwairy.co/use-cases/sources/which-websites-influence-ai

Identify websites exposed with relevant stored answers, then assess citation breadth and context without claiming causality.

## Direct answer

Use **Monitor > Source Explorer** to identify domains and URLs exposed with answers about your brand. Rank observed sources by declared units such as citation volume, distinct answers, or prompt breadth. Qwairy cannot prove that a website influenced the generated text.

## Data required

* Stored answers for a fixed analysis scope
* Exposed source domains and URLs
* SELF and DIRECT source and brand classifications
* Citation volume, distinct answers, and distinct prompts by source
* Full answer and source-page content for contextual review

## Workflow

1. In **Monitor > Source Explorer**, set the period, provider, model, country, language, topic, and tag filters.
2. Compare domains using citation volume and answer or prompt breadth.
3. Drill down to URLs so one relevant page is not generalized to an entire domain.
4. Open the associated answers in **Monitor > Response Analysis**.
5. Check whether the source supports a brand claim, a category fact, a competitor claim, or unrelated context.
6. Repeat with the same scope when comparing topics, providers, or periods.

## Interpretation

Citation volume, answer breadth, and prompt breadth are different units. Product Citation Rate is response-level and uses answers citing SELF sources over answers citing SELF or DIRECT sources; it is not a domain influence score.

Call these observed sources or frequently exposed sources. A citation does not imply a SELF mention, positive context, source authority, or causal influence.

## Possible next actions

* Test whether improving a relevant SELF source changes later observed citations.
* Correct inaccurate claims on a source you control.
* Investigate a third-party page that repeatedly appears with a material factual error.
* Track a fixed prompt cohort after a source update.

Treat any expected provider response as a hypothesis.

## Limitations

* Qwairy stores exposed citations, not complete provider provenance.
* Providers differ in citation behavior and may change between runs.
* URL normalization and redirects can affect source counts.
* Citation co-occurrence cannot establish causality.

## Related pages

* [Explore content sources](/documentation/monitor/content-sources)
* [Inspect source domains in Looker Studio](/looker-studio/sources/source-domains)
* [Find your most cited pages](/use-cases/sources/pages-with-most-ai-citations)


# Which pages are crawled by AI bots but never cited?
Source: https://docs.qwairy.co/use-cases/technical/pages-crawled-but-never-cited

Compare retained crawler page rollups with recorded citation URLs to find investigation candidates without assuming crawl-to-citation causality.

## Direct answer

Compare the last 30 days of page rollups in **Measure > Crawler Analytics** with SELF URLs recorded in **Monitor > Source Explorer** for an aligned period. A page with crawler occurrences and no recorded citation is an investigation candidate, not proof that a provider evaluated and rejected it.

## Data required

Use reconstructible normalized paths, supported crawler identity, daily buckets, first and last observed times, status-code groups, coverage state, stored answers, recorded citation URLs, providers, topics, and configured prompts. Exclude pseudonymized paths from URL matching and document redirects or variants.

## Workflow

<Steps>
  <Step title="Align the datasets">
    Choose comparable periods and normalize protocol, hostname, trailing slash, parameters, redirects, and canonical variants.
  </Step>

  <Step title="Find crawler-only URLs">
    Identify reconstructible pages with selected-period crawler occurrences but no matching SELF citation URL in the selected stored answers.
  </Step>

  <Step title="Check technical context">
    Review response status, access configuration, canonicalization, internal discovery, and the Site Readiness findings for each candidate.
  </Step>

  <Step title="Review content relevance">
    Compare the page with the monitored prompts and sources recorded for those answers. Exclude pages that do not address the observed need.
  </Step>
</Steps>

## Interpretation

A crawler occurrence shows a request retained in an aggregate for a supported User-Agent identity. It does not establish indexing, training, retrieval, or future citation. A citation is a source URL recorded with a stored answer; it does not require an observed occurrence in the connected period.

## Possible next actions

* If URL variants split the data, test canonicalization or reporting normalization before changing content.
* If error-group occurrences recur, test a technical correction and compare later daily rollups.
* If access is healthy but relevance is weak, test a content update against a defined prompt cohort.

## Limitations

Crawler and citation datasets have different coverage, retention, and URL representations. Page rollups retain 30 analytic days, pseudonymized paths cannot be joined, and some provider activity does not expose a supported User-Agent identity. No occurrence frequency guarantees a citation.

## Related pages

<CardGroup>
  <Card title="Crawler Analytics" href="/documentation/measure/crawler-analytics">
    Review observed crawler activity.
  </Card>

  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Compare URL-level data in a documented source.
  </Card>

  <Card title="Content Opportunities" href="/documentation/act/content-opportunities">
    Review observed content gaps.
  </Card>

  <Card title="Gap to article" href="/use-cases/content/content-gap-to-cited-article">
    Run a documented content experiment.
  </Card>

  <Card title="Site optimization" href="/use-cases/technical/site-optimized-for-ai-crawlers">
    Audit technical accessibility.
  </Card>

  <Card title="Pages cited by AI" href="/use-cases/sources/pages-with-most-ai-citations">
    Analyze recorded citation URLs.
  </Card>
</CardGroup>


# Do I have the right robots.txt and llms.txt configuration?
Source: https://docs.qwairy.co/use-cases/technical/robots-txt-llms-txt

Audit published crawler directives against your access policy, Site Readiness, and retained crawler rollups without assuming universal support.

## Direct answer

Use **Optimize > Site Readiness** to inspect the files Qwairy can observe, then compare the result with your intended access policy and retained Crawler Analytics rollups. Validate robots.txt syntax and path scope. Treat llms.txt as an optional published file whose interpretation can vary by consumer.

## Data required

Use the exact public robots.txt and llms.txt URLs, intended allow or disallow policy by path and identity, sitemap locations, production hostname, Site Readiness findings, and Crawler Analytics occurrence, status-group, and coverage aggregates.

## Workflow

<Steps>
  <Step title="Define the policy">
    Decide which public paths should be accessible to each relevant crawler class. Keep private or sensitive content protected by authentication, not crawler directives alone.
  </Step>

  <Step title="Review the published files">
    Inspect robots.txt and llms.txt from the production hostname. Check syntax, path matching, host variants, and referenced URLs.
  </Step>

  <Step title="Run Site Readiness">
    Review reported configuration issues and verify each one against the actual files before changing production behavior.
  </Step>

  <Step title="Compare observed activity">
    Use Crawler Analytics to see whether supported observable User-Agent identities have occurrences on allowed paths and whether error-group occurrences repeat.
  </Step>
</Steps>

## Interpretation

A syntactically valid directive expresses your policy but does not guarantee that every crawler will visit, index, use, or cite a page. llms.txt support and behavior can differ between consumers. Crawler rollups provide observations, not proof of ingestion or model training.

## Possible next actions

* If an intended public path is blocked, test the smallest policy correction after security and content-owner review.
* If host or path variants conflict, test a normalized configuration and verify the published response.
* If configuration is valid but no occurrences appear, investigate discovery and delivery coverage before assuming crawler rejection.

## Limitations

Crawler policies and implementations can change outside Qwairy. robots.txt is not an access-control system, and llms.txt is not a guarantee of use. Configuration changes can expose paths unintentionally, so review production scope before publishing.

## Related pages

<CardGroup>
  <Card title="Crawler configuration guide" href="https://www.qwairy.co/guides/complete-guide-to-robots-txt-and-llms-txt-for-ai-crawlers">
    Read additional configuration guidance.
  </Card>

  <Card title="Site Readiness" href="/documentation/optimize/site-readiness">
    Review the product audit.
  </Card>

  <Card title="Qwairy videos" href="https://www.youtube.com/@TryQwairy">
    Browse product education videos.
  </Card>

  <Card title="Site optimization" href="/use-cases/technical/site-optimized-for-ai-crawlers">
    Review the broader technical workflow.
  </Card>

  <Card title="Crawler occurrences" href="/use-cases/technical/which-ai-crawlers-visit">
    Inspect observed user agents and URLs.
  </Card>

  <Card title="Crawled but not cited" href="/use-cases/technical/pages-crawled-but-never-cited">
    Compare crawler and citation datasets.
  </Card>
</CardGroup>


# Is my website properly optimized for AI crawlers?
Source: https://docs.qwairy.co/use-cases/technical/site-optimized-for-ai-crawlers

Use Site Readiness and observed crawler activity to review accessibility and discovery while avoiding claims about indexing or citations.

## Direct answer

Use **Optimize > Site Readiness** to review public technical signals, then verify findings against your production site and **Measure > Crawler Analytics**. Resolve issues that conflict with your intended access policy. Passing an audit does not guarantee crawling, indexing, use, or citation.

## Data required

Use the production hostname, representative public URLs, robots.txt and optional llms.txt, sitemap and canonical information, response behavior, Site Readiness findings, and retained Crawler Analytics rollups with their coverage state.

## Workflow

<Steps>
  <Step title="Set the intended scope">
    List the public sections that relevant crawlers may access and the sections that must remain protected.
  </Step>

  <Step title="Review Site Readiness">
    Inspect findings for configuration, accessibility, discovery, and page-level diagnostics. Verify each result on the current production URL.
  </Step>

  <Step title="Check observed crawler activity">
    In Crawler Analytics, review supported identities, normalized or pseudonymized paths, first and last observed times, occurrence counts, status-code groups, and coverage warnings.
  </Step>

  <Step title="Prioritize verified issues">
    Address access errors, conflicting directives, broken discovery paths, or duplicate URL handling based on impact and change risk.
  </Step>
</Steps>

## Interpretation

Technical readiness means that the selected public pages appear accessible and discoverable under the checks performed. It does not show that a provider indexed or used the content. Crawler occurrence rollups and recorded citations are independent observations.

## Possible next actions

* If important pages return errors to observed crawlers, test the smallest infrastructure or policy correction.
* If crawling is concentrated on duplicate URLs, test canonical and internal-link normalization.
* If technical access is healthy but citations are absent, investigate prompt relevance and content evidence separately.

## Limitations

Audits are point-in-time checks and cannot represent every crawler implementation. JavaScript execution, regional infrastructure, authentication, rate limits, and third-party behavior can affect access. No technical configuration guarantees an answer mention or citation.

## Related pages

<CardGroup>
  <Card title="Site Readiness" href="/documentation/optimize/site-readiness">
    Review the product audit and findings.
  </Card>

  <Card title="Crawler configuration guide" href="https://www.qwairy.co/guides/complete-guide-to-robots-txt-and-llms-txt-for-ai-crawlers">
    Read additional configuration guidance.
  </Card>

  <Card title="Qwairy videos" href="https://www.youtube.com/@TryQwairy">
    Browse product education videos.
  </Card>

  <Card title="Crawler occurrences" href="/use-cases/technical/which-ai-crawlers-visit">
    Inspect observed crawler activity.
  </Card>

  <Card title="robots.txt and llms.txt" href="/use-cases/technical/robots-txt-llms-txt">
    Audit published crawler directives.
  </Card>

  <Card title="Crawled but not cited" href="/use-cases/technical/pages-crawled-but-never-cited">
    Compare technical and citation observations.
  </Card>
</CardGroup>


# Which AI crawlers are visiting my site and how frequently?
Source: https://docs.qwairy.co/use-cases/technical/which-ai-crawlers-visit

Review retained crawler occurrence rollups by supported User-Agent identity, page, and period without inferring indexing, training, or citations.

## Direct answer

Open **Measure > Crawler Analytics** and filter retained occurrence rollups by supported User-Agent identity, page, state, and period. Report occurrence counts and retained page identities separately. These aggregates show activity accepted from the connected data source, not which AI products ingested or used the content.

## Data required

Use the classified User-Agent identity, normalized or pseudonymized page path, daily buckets, `firstSeenAt`, `lastSeenAt`, lifetime count, selected-period occurrences, status-code groups, production hostname, and coverage state. Keep provider and model names separate from crawler classifications.

## Workflow

<Steps>
  <Step title="Validate collection">
    Confirm the monitored hostname, delivery coverage, analytic timezone, count precision, and classification rules before comparing crawlers.
  </Step>

  <Step title="Review user agents">
    Identify supported observable User-Agent identities and their occurrence counts in the selected period.
  </Step>

  <Step title="Inspect URL distribution">
    Compare retained page identities, occurrence counts, status-code groups, and site sections. Do not reconstruct pseudonymized paths.
  </Step>

  <Step title="Compare periods">
    Use equivalent windows and note site, logging, or classification changes that could affect the totals.
  </Step>
</Steps>

## Interpretation

Occurrence count measures retained classified requests; page identities measure observed 2xx path coverage. Neither indicates indexing, training, retrieval, citation, or user traffic. Qwairy matches User-Agent tokens but does not verify source IP or reverse DNS.

## Possible next actions

* If a crawler has repeated error-group occurrences, test an access or infrastructure correction and compare a later daily rollup.
* If only a narrow site section is visited, test discovery through valid sitemaps and internal links.
* If activity changes abruptly, investigate logging, classification, deployment, and policy changes before attributing it externally.

## Limitations

User-Agent identities can be missing, spoofed, renamed, or unsupported. Daily page rollups retain 30 analytic days; durable first-seen, last-seen, and lifetime counters are not a raw request history. Connected delivery can be partial, so no universal occurrence cadence defines healthy performance.

## Related pages

<CardGroup>
  <Card title="Source URLs in Looker Studio" href="/looker-studio/sources/source-urls">
    Report URL-level observations.
  </Card>

  <Card title="Crawler Analytics" href="/documentation/measure/crawler-analytics">
    Review crawler data in the product.
  </Card>

  <Card title="Crawler configuration guide" href="https://www.qwairy.co/guides/complete-guide-to-robots-txt-and-llms-txt-for-ai-crawlers">
    Read additional configuration guidance.
  </Card>

  <Card title="Site optimization" href="/use-cases/technical/site-optimized-for-ai-crawlers">
    Audit technical accessibility.
  </Card>

  <Card title="robots.txt and llms.txt" href="/use-cases/technical/robots-txt-llms-txt">
    Review crawler directives.
  </Card>

  <Card title="Crawled but not cited" href="/use-cases/technical/pages-crawled-but-never-cited">
    Compare crawler and citation observations.
  </Card>

  <Card title="Brand visibility" href="/use-cases/visibility/how-visible-is-my-brand-in-ai">
    Analyze answer visibility separately.
  </Card>
</CardGroup>


# How often is my brand cited with a link versus just mentioned by name?
Source: https://docs.qwairy.co/use-cases/visibility/cited-with-link-vs-just-mentioned

Separate answers that mention your brand and cite your site from answers that mention the brand without a SELF citation.

## Direct answer

Answer this at the answer level. Build two cohorts within the same filtered dataset: answers with both a SELF mention and a SELF citation, and answers with a SELF mention but no SELF citation. Do not subtract Product Citation Rate from Product Mention Rate because the two metrics use different denominators.

## Data required

* Completed answers for one consistent period and filter scope
* Detected SELF and DIRECT brand mentions
* Citation URLs classified as SELF or DIRECT sources
* The corresponding answer text for context
* Provider, model, country, language, topic, and tag filters

## Workflow

1. Set the intended scope in **Monitor > Response Analysis** and identify answers with a SELF mention.
2. Open those answers and record whether each also contains a citation to a SELF source.
3. Use **Monitor > Source Explorer** to inspect the SELF domains and URLs cited in the same scope.
4. Export answer-level data when you need a reproducible cohort count across many answers.
5. Review the mention and citation context. A linked source may be unrelated to the sentence that mentions your brand.
6. Repeat with the same filters for a comparison period or provider.

## Interpretation

Product **Mention Rate** is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. Product **Citation Rate** is answers citing a SELF source divided by answers citing at least one SELF or DIRECT source. Both are response-level, but their eligible answer populations differ.

For this use case, the most direct unit is therefore a count or proportion among answers with a SELF mention. Keep the numerator and denominator visible. A SELF citation does not imply a positive mention, and a positive mention does not imply a citation.

## Possible next actions

* Test whether a clearly sourced page for a recurring claim is associated with more SELF citations in later comparable answers.
* Review unlinked mentions to identify facts that your site does not currently document with verifiable evidence.
* Test whether consolidating duplicate or outdated pages gives providers a clearer canonical source.
* Investigate a provider-specific gap before making a site-wide change.

These are hypotheses. Compare later observations under the same prompt and provider scope.

## Limitations

* Qwairy records citations returned with stored answers; it does not expose every source used to generate an answer.
* Citation and mention extraction can require manual review for aliases, redirects, and ambiguous domains.
* A co-occurring citation does not prove that the source caused the mention.
* Providers differ in whether and how they expose source links.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Explore content sources](/documentation/monitor/content-sources)
* [Find your most cited pages](/use-cases/sources/pages-with-most-ai-citations)


# For which topics does my brand appear in AI answers?
Source: https://docs.qwairy.co/use-cases/visibility/for-which-topics-does-my-brand-appear

Compare prompt-level Coverage and answer-level Mention Rate across topics while keeping the analysis scope consistent.

## Direct answer

Use topic filters in **Cockpit > GEO Matrix** to find where your brand is observed, then verify the underlying prompts and answers. Compare both prompt-level Coverage and response-level Mention Rate. They answer different questions.

## Data required

* Answered prompts assigned to stable topics
* SELF and DIRECT competitor classifications
* A fixed period, provider or model set, country, and language
* Topic-level raw answer and prompt counts
* Representative answer text for each topic

## Workflow

1. In **Workspace > Topics**, review topic names and prompts with no topic assignment.
2. In **Cockpit > GEO Matrix**, set a consistent period and filter scope, then compare topic rows.
3. For each topic, record Coverage, Mention Rate, and their raw numerators and denominators.
4. In **Monitor > Prompt Tracking**, identify which prompts account for presence or absence within that topic.
5. Read the matching answers in **Monitor > Response Analysis** to distinguish relevant mentions from incidental ones.
6. Use **Cockpit > Compare** with the same topic filter when competitive context is needed.

## Interpretation

Product **Coverage** is distinct answered prompts with at least one SELF mention divided by distinct answered prompts. It is prompt-level. Product **Mention Rate** is answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. It is response-level.

A topic can have broad Coverage because your brand appears at least once for many prompts while still having a lower Mention Rate across answers. Conversely, a narrow topic can show a high rate from a small sample. Inspect counts before ranking topics.

## Possible next actions

* Test content that answers a missing prompt with specific, verifiable evidence.
* Split a broad topic when several distinct buyer decisions are being blended.
* Add a missing category-neutral prompt when the topic is underrepresented in the monitored set.
* Review competitor classification when a DIRECT brand is missing from the denominator.

Treat the expected effect as a hypothesis and compare a stable cohort after the change.

## Limitations

* Topic results depend on your prompt assignments and do not measure the full market.
* Unequal prompt or answer volumes make raw percentages hard to compare.
* Presence does not indicate endorsement, accuracy, or commercial impact.
* Provider output can vary between runs.

## Related pages

* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Manage topics](/documentation/workspace/topics)
* [Find topics competitors cover without you](/use-cases/competitors/topics-competitors-own-without-me)


# How has my brand's AI visibility changed over the last 30/60/90 days?
Source: https://docs.qwairy.co/use-cases/visibility/how-has-my-visibility-changed

Compare visibility over time with fixed filters, explicit metric denominators, and a record of monitoring changes.

## Direct answer

Use the evolution views in **Cockpit > Overview** with a consistent scope, then inspect the answers behind any change. Describe the metric as changing after an event, not because of it, unless you have a separate causal method.

## Data required

* Completed answers in the current and comparison windows
* The same prompt cohort, providers, models, countries, languages, topics, and tags
* Raw numerators and denominators for each metric
* A log of prompt, monitoring, competitor, and site changes
* Representative answers around the observed change

## Workflow

1. In **Cockpit > Overview**, select the current period and note the active filters.
2. Compare with an equal prior window when the interface supports it.
3. Record Mention Rate, Citation Rate, Share of Voice, Coverage, and their raw components separately.
4. In **Cockpit > GEO Matrix**, locate the topics and providers contributing to the change.
5. Read matching answers in **Monitor > Response Analysis** before interpreting an aggregate movement.
6. Check your change log for prompt, model, schedule, country, competitor-classification, or site changes during the same interval.

## Interpretation

Product Mention Rate and Citation Rate are response-level. Product Coverage is prompt-level. Product Share of Voice counts mention occurrences. A change in any one metric does not imply the others changed, and a percentage can move because its denominator changed.

Prefer a fixed prompt cohort for trend analysis. If the cohort changed, show the old and new populations separately or label the discontinuity. Treat changes from small samples as provisional.

## Possible next actions

* Test whether an observed decline is concentrated in one provider, model, topic, or country.
* Review newly absent prompts and the underlying answers before proposing content work.
* Annotate a site release or campaign, then compare a stable cohort in later periods.
* Restore a prior filter or prompt cohort when a configuration change explains the apparent trend.

Each action tests an explanation; it does not establish causality.

## Limitations

* Model updates, retrieval behavior, and answer variability can change output without a brand action.
* Added or removed prompts can create a trend break.
* Stored answers reflect configured monitoring, not all AI interactions.
* Overlapping or unequal time windows can distort comparisons.

## Related pages

* [Read Cockpit Overview](/documentation/cockpit/performance-dashboard)
* [Share a filtered view](/documentation/workspace/shared-links)
* [Assess campaign timing carefully](/use-cases/campaigns/campaign-impact-on-ai-visibility)


# How visible is my brand in AI-powered search engines?
Source: https://docs.qwairy.co/use-cases/visibility/how-visible-is-my-brand-in-ai

Assess brand visibility with response-level rates, prompt-level Coverage, Share of Voice, and the underlying answers.

## Direct answer

There is no single visibility measure for every decision. Start in **Cockpit > Overview**, then combine Mention Rate, Coverage, Share of Voice, Citation Rate, and answer context. Keep each metric's unit and denominator explicit.

## Data required

* Completed answers for a fixed period and filter scope
* SELF and DIRECT brand and source classifications
* Answered-prompt counts
* Mention-occurrence counts
* Provider, model, country, language, topic, tag, and funnel filters

## Workflow

1. Set the analysis scope in **Cockpit > Overview**.
2. Record every headline metric with its numerator and denominator.
3. Use **Cockpit > GEO Matrix** to locate topic and provider differences.
4. Use **Monitor > Prompt Tracking** to identify covered and uncovered prompts.
5. Read representative answers in **Monitor > Response Analysis** to evaluate context, accuracy, and prominence.
6. Repeat only with comparable scopes when benchmarking another period or segment.

## Interpretation

* **Mention Rate**: answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention.
* **Citation Rate**: answers citing a SELF source divided by answers citing at least one SELF or DIRECT source.
* **Share of Voice**: SELF mention occurrences divided by SELF plus DIRECT mention occurrences.
* **Coverage**: distinct answered prompts with at least one SELF mention divided by distinct answered prompts.

Mention Rate and Citation Rate are response-level, Coverage is prompt-level, and Share of Voice is occurrence-level. Do not average or combine them into a new score without an approved methodology.

## Possible next actions

* Test whether a topic with low Coverage needs a better prompt set before proposing content.
* Investigate provider-specific low Mention Rate in the underlying answers.
* Test a source-page improvement when SELF citations are absent for a recurring factual question.
* Review DIRECT competitor classification before acting on Share of Voice.

Treat each expected outcome as a hypothesis and preserve the comparison scope.

## Limitations

* The dataset covers configured prompts and completed answers, not every AI interaction.
* Presence does not imply endorsement, accuracy, or purchase intent.
* Missing or uneven samples can distort cross-provider comparisons.
* Provider output and citations can vary between runs.

## Related pages

* [Read Cockpit Overview](/documentation/cockpit/performance-dashboard)
* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Track visibility changes](/use-cases/visibility/how-has-my-visibility-changed)


# What is my brand's share of voice compared to competitors?
Source: https://docs.qwairy.co/use-cases/visibility/what-is-my-share-of-voice

Measure Product Share of Voice from SELF and DIRECT mention occurrences, then inspect the competitors and answers behind it.

## Direct answer

Product **Share of Voice** is your SELF mention occurrences divided by SELF plus DIRECT mention occurrences in the selected scope. Use it to compare observed mention volume against configured direct competitors, not as a measure of the entire market.

## Data required

* Completed answers for a fixed scope
* Correct SELF and DIRECT competitor classifications
* SELF and DIRECT mention-occurrence counts
* Consistent provider, model, country, language, topic, tag, and period filters
* Answer text for contextual review

## Workflow

1. Review competitor relationships and ensure relevant competitors are classified as DIRECT.
2. In **Cockpit > Overview**, set the analysis scope and record Share of Voice with its raw occurrence counts.
3. In **Cockpit > Compare**, identify which DIRECT competitors contribute most to the denominator.
4. Apply topic, funnel, or provider filters one at a time to locate concentration.
5. Read the matching answers in **Monitor > Response Analysis** to distinguish meaningful recommendations from incidental or repeated mentions.
6. Compare periods only when competitor classifications and filters are unchanged.

## Interpretation

Share of Voice counts occurrences, not answers or prompts. One answer can contribute more than one occurrence. A higher value means your brand accounts for a larger share of observed SELF and DIRECT mention occurrences in that scope.

Do not confuse Share of Voice with Mention Rate. Mention Rate is response-level and uses answers with at least one SELF or DIRECT brand mention as its denominator.

## Possible next actions

* Test whether a weak topic needs content that answers a specific buyer question with verifiable evidence.
* Investigate a competitor that gains occurrences on one provider or model.
* Correct competitor relationships before treating a change as market movement.
* Track a fixed prompt cohort after a campaign or content change.

These actions test associations; they do not prove that content work will increase Share of Voice.

## Limitations

* The denominator includes configured SELF and DIRECT relationships, not every possible competitor.
* Repeated mentions within an answer affect occurrence-level Share of Voice.
* Mention extraction and aliases may require review.
* Share of Voice does not indicate sentiment, accuracy, citation, or conversion.

## Related pages

* [Compare competitors](/documentation/cockpit/compare)
* [Identify your observed competitors](/use-cases/competitors/who-are-my-biggest-competitors)
* [Compare competitors by provider](/use-cases/competitors/competitors-outperform-me-by-provider)


# What position does my brand typically appear in within AI responses?
Source: https://docs.qwairy.co/use-cases/visibility/what-position-does-my-brand-appear

Review recorded brand positions with their eligible mention count, distribution, and answer context.

## Direct answer

Use Avg Position only for SELF mentions with a recorded rank. A lower numeric rank represents an earlier detected position, but the average excludes answers where no eligible SELF position exists. Always pair it with absence and mention metrics.

## Data required

* Completed answers with detected SELF mentions
* Recorded SELF positions greater than zero
* Eligible-position count and distribution
* Answers with no SELF mention
* A fixed provider, model, prompt, country, language, and period scope

## Workflow

1. Set a consistent scope in **Cockpit > Overview** or **Cockpit > Compare**.
2. Record Avg Position together with the number of SELF mentions that have a recorded rank.
3. In **Monitor > Prompt Tracking**, locate prompts with earlier, later, or missing positions.
4. Read those answers in **Monitor > Response Analysis** to confirm that rank is meaningful for the response format.
5. Separate list-style answers from narrative answers when their position semantics differ.
6. Compare providers or periods only when the eligible answer populations are comparable.

## Interpretation

Avg Position is conditional on a recorded SELF mention position. It is not prompt Coverage and it does not include brand absences as a lower rank. An average can therefore improve while your brand disappears from more answers.

Use the distribution and underlying answers to distinguish a consistent pattern from a few extreme ranks. There is no universal good position across response formats or categories.

## Possible next actions

* Test whether a prompt-specific content gap explains late or missing placement.
* Compare list and narrative prompts separately.
* Investigate whether one provider or model accounts for the position shift.
* Pair a position experiment with Coverage and Mention Rate so absence remains visible.

Treat any expected ranking change as a hypothesis.

## Limitations

* Position is not equally meaningful in every answer format.
* Averages hide dispersion and exclude ineligible observations.
* Detection can be affected by aliases, tables, and repeated mentions.
* Position does not measure sentiment, citation, or commercial impact.

## Related pages

* [Analyze answers](/documentation/monitor/analyzing-answers)
* [Inspect prompt performance in Looker Studio](/looker-studio/sources/prompt-performance)
* [Assess overall AI visibility](/use-cases/visibility/how-visible-is-my-brand-in-ai)


# Which AI providers mention my brand the most (and the least)?
Source: https://docs.qwairy.co/use-cases/visibility/which-providers-mention-my-brand

Compare provider-level mentions using matched prompts, models, filters, raw counts, and response-level Mention Rate.

## Direct answer

Compare providers only after matching the prompt set, period, country, language, and answer coverage. Use provider-level Mention Rate and raw counts in **Cockpit > Overview**, then inspect model-level and answer-level differences.

## Data required

* The same answered prompts across the providers being compared
* Provider and model identifiers
* SELF and DIRECT brand classifications
* Mention Rate numerator and denominator by provider
* Prompt-level Coverage and raw answer counts

## Workflow

1. In **Cockpit > Overview**, fix the period, topic, tag, funnel, country, and language scope.
2. Compare provider rows using raw answer counts, Mention Rate, and Coverage.
3. In **Cockpit > GEO Matrix**, identify the prompts or topics where differences occur.
4. Separate models within a provider when multiple models are present.
5. Read representative answers in **Monitor > Response Analysis** to check mention relevance and wording.
6. Use **Cockpit > Compare** with the same filters to add DIRECT competitor context.

## Interpretation

Product Mention Rate is response-level: answers with a SELF mention divided by answers with at least one SELF or DIRECT brand mention. Product Coverage is prompt-level: distinct answered prompts with at least one SELF mention divided by distinct answered prompts.

A provider can lead on one metric and not the other. A provider with incomplete answers or a different prompt mix is not directly comparable. The result describes the selected stored dataset, not the provider as a whole.

## Possible next actions

* Test whether a provider-specific topic gap persists with a matched prompt cohort.
* Inspect the sources and wording behind a low provider result before changing content.
* Add monitoring for a relevant model when the current sample is incomplete.
* Revisit DIRECT competitor classification when the Mention Rate denominator looks unexpected.

Treat provider differences as observations to investigate, not proof of a provider's permanent behavior.

## Limitations

* Provider and model output can vary between runs.
* Availability and source-link behavior can differ by provider, model, and market.
* Unequal answer volumes distort rankings.
* Mentions do not indicate endorsement, accuracy, citation, or referral traffic.

## Related pages

* [Read Cockpit Overview](/documentation/cockpit/performance-dashboard)
* [Use the GEO Matrix](/documentation/cockpit/geo-matrix)
* [Understand different provider scores](/use-cases/providers/different-scores-across-providers)