> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Deep-Dive Tools

> Tools for detailed analysis: on-page presence, source profiles, competitor positioning, and the GEO visibility matrix.

## 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`         | number | No       | Number of days to analyze (default: 30)          |
| `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`       | number | No       | Number of days to analyze (default: 30)                            |

### 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`      | number | No       | Number of days to analyze (default: 30)                      |
| `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`