> ## 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.

# Insight Tools

> Tools for vertical insights: shopping, social, local businesses, and web search query analysis.

## 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`  | number | No       | Number of days to analyze (default: 30) |
| `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`  | number | No       | Number of days to analyze (default: 30) |
| `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`  | number | No       | Number of days to analyze (default: 30) |
| `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`         |
| `period`  | number | No       | Number of days to analyze (default: 30) |
| `limit`   | number | No       | Max queries to return (default: 20)     |

### Returns

| Field          | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| `summary`      | Total queries, unique queries, avg brand presence %                     |
| `topQueries[]` | Most frequent queries with brand presence %, competitor count, priority |

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