Skip to main content
GET
/
api
/
v1
/
brands
/
{brandId}
/
search
Query Fan-Out
curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/search \
  --header 'Authorization: <authorization>'
{
  "success": true,
  "pagination": {
    "total": 123,
    "count": 123,
    "limit": 123,
    "offset": 123
  },
  "searches": [
    {
      "query": "<string>",
      "occurrences": 123,
      "priority": "<string>",
      "brandPresence": 123,
      "competitorPresence": 123,
      "competitors": [
        {}
      ],
      "uniquePrompts": 123,
      "uniqueAnswers": 123,
      "uniqueModels": 123,
      "models": [
        {}
      ],
      "topics": [
        {}
      ],
      "tags": [
        {}
      ],
      "firstSeen": "<string>",
      "lastSeen": "<string>"
    }
  ]
}
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.
Results are aggregated by query (case-insensitive, trimmed). Each row represents a unique search query across all responses and providers.

​
List Search Insights

​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/search

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand

​
Query Parameters

​
period
number
Number of days to include. If not specified, returns all data.
​
startDate
string
Start date (ISO 8601 format)
​
endDate
string
End date (ISO 8601 format)
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
limit
number
default:"50"
Maximum number of queries to return (max: 100)
​
offset
number
default:"0"
Number of results to skip for pagination
​
sort
string
default:"occurrences"
Field to sort by: occurrences, priority, brandPresence, query, createdAt
​
order
string
default:"desc"
Sort order: asc or desc

​
Response

​
success
boolean
Indicates if the request was successful
​
pagination
object
​
searches
array

​
Example Request

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

{
  "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"
    }
  ]
}
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.
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).

​
Error Responses

StatusCodeDescription
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible