Skip to main content

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.

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.
This endpoint returns a cross-tabulation of your brand’s visibility. See Performance for aggregated metrics and Competitor for entity structures used in topCompetitors.

​
Get Matrix

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

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand

​
Query Parameters

​
granularity
string
Group rows by: topics (default), tags, prompts, or funnel
​
period
number
Number of days to include. Default: 30
​
startDate
string
Start date (ISO 8601 format). Overrides period if provided with endDate
​
endDate
string
End date (ISO 8601 format). Overrides period if provided with startDate
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
topic
string
Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., id1,id2).
​
tag
string
Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).
​
limit
number
Max rows to return. Default: 50, max: 100

​
Granularity Options

ValueGroups rows by
topicsKeywords/topics (default)
tagsTags applied to prompts
promptsIndividual monitored questions
funnelFunnel stages (TOFU/MOFU/BOFU)

​
Response

​
success
boolean
Indicates if the request was successful
​
brand
object
​
granularity
string
The granularity used for this matrix (topics, tags, prompts, or funnel)
​
providers
array
List of AI provider IDs used as columns (e.g., ["chatgpt", "perplexity", "claude"])
​
rows
array
Matrix rows, one per topic/tag/prompt/funnel stage
​
summary
object

​
Example Request

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/matrix?granularity=topics&period=30&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"

​
Example Response

{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "My Brand",
    "domain": "mybrand.com"
  },
  "granularity": "topics",
  "providers": ["chatgpt", "perplexity", "claude"],
  "rows": [
    {
      "id": "topic1",
      "name": "Product Reviews",
      "cells": [
        {
          "provider": "chatgpt",
          "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.1,
          "coverage": 78.5,
          "topCompetitor": {
            "name": "Competitor A",
            "score": 68
          },
          "topCompetitors": [
            { "name": "Competitor A", "score": 68 },
            { "name": "Competitor B", "score": 55 }
          ],
          "topSources": [
            { "domain": "industry-news.com", "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.4,
          "coverage": 62.0,
          "topCompetitor": {
            "name": "Competitor B",
            "score": 71
          },
          "topCompetitors": [
            { "name": "Competitor B", "score": 71 },
            { "name": "Competitor A", "score": 60 }
          ],
          "topSources": [
            { "domain": "tech-review.com", "citations": 14 }
          ]
        },
        {
          "provider": "claude",
          "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.2,
          "coverage": 40.0,
          "topCompetitor": {
            "name": "Competitor A",
            "score": 62
          },
          "topCompetitors": [
            { "name": "Competitor A", "score": 62 }
          ],
          "topSources": [
            { "domain": "mybrand.com", "citations": 3 }
          ]
        }
      ]
    }
  ],
  "summary": {
    "totalRows": 12,
    "avgScore": 58,
    "bestProvider": "chatgpt",
    "worstProvider": "claude"
  }
}

​
Error Responses

StatusCodeDescription
400INVALID_PARAMETERInvalid query parameter (e.g., unknown granularity)
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible