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

# Query Fan-Out

> Web search queries generated by AI (Query Fan Out)

Access aggregated web search queries that AI providers generate when responding to prompts. Results are grouped by query text with brand presence, competitor presence, and priority metrics.

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

## List Search Insights

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

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

### Path Parameters

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

### Query Parameters

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

<ParamField query="startDate" type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format)
</ParamField>

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

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

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

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

<ParamField query="order" type="string" default="desc">
  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">List of direct competitor names mentioned</ResponseField>
    <ResponseField name="uniquePrompts" type="number">Number of distinct prompts that triggered this query</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">List of model IDs that generated this query</ResponseField>
    <ResponseField name="topics" type="array">Associated topics</ResponseField>
    <ResponseField name="tags" type="array">Associated tags</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>

### Example 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"
```

### Example Response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 142,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "searches": [
    {
      "query": "best CRM software 2024 enterprise features comparison",
      "occurrences": 12,
      "priority": "very-high",
      "brandPresence": 0,
      "competitorPresence": 8,
      "competitors": ["Salesforce", "HubSpot"],
      "uniquePrompts": 5,
      "uniqueAnswers": 12,
      "uniqueModels": 3,
      "models": ["gpt-4o", "claude-3-5-sonnet", "gemini-1.5-pro"],
      "topics": ["CRM", "Enterprise Software"],
      "tags": ["comparison"],
      "firstSeen": "2024-12-01T10:30:00.000Z",
      "lastSeen": "2024-12-15T10:30:00.000Z"
    },
    {
      "query": "Acme CRM pricing plans 2024",
      "occurrences": 5,
      "priority": "medium",
      "brandPresence": 3,
      "competitorPresence": 0,
      "competitors": [],
      "uniquePrompts": 2,
      "uniqueAnswers": 5,
      "uniqueModels": 2,
      "models": ["gpt-4o", "gemini-1.5-pro"],
      "topics": ["Pricing"],
      "tags": [],
      "firstSeen": "2024-12-05T09:15:00.000Z",
      "lastSeen": "2024-12-14T09:15:00.000Z"
    }
  ]
}
```

<Warning>
  **Breaking change from previous version:** Results are now aggregated by unique query text. The previous `id` and `prompt` fields have been removed. Use `lastSeen` instead of the previous `createdAt` field for timestamp ordering.
</Warning>

<Note>
  Search queries reveal valuable keyword and intent data. Use `priority` to identify high-value queries where competitors appear but your brand doesn't (`very-high`).
</Note>

### Error Responses

| Status | Code              | Description                           |
| ------ | ----------------- | ------------------------------------- |
| 401    | `INVALID_TOKEN`   | Authentication failed                 |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible |