Get GEO Matrix - Qwairy Documentation

Get GEO Matrix

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/matrix \
  --header 'Authorization: <authorization>'

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>"
  },
  "granularity": "<string>",
  "providers": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "rows": [
    {
      "id": "<string>",
      "name": "<string>",
      "promptCount": 123,
      "mentionRate": 123,
      "coverage": {
        "count": 123,
        "total": 123,
        "percentage": 123
      },
      "cells": [
        {
          "provider": "<string>",
          "score": 123,
          "subScores": {
            "mentionRate": 123,
            "shareOfVoice": 123,
            "citationRate": 123,
            "sentiment": 123
          },
          "ranking": {
            "mentionRate": {},
            "shareOfVoice": {},
            "citationRate": {},
            "sentiment": {}
          },
          "citations": 123,
          "position": 123,
          "topCompetitor": "<string>",
          "topCompetitors": [
            {}
          ],
          "topSources": [
            {}
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    {
      "provider": "<string>",
      "score": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "citationRate": 123,
      "sentiment": 123
    }
  ],
  "summary": {
    "totalRows": 123,
    "averageMentionRate": 123,
    "topPerforming": {},
    "needsAttention": {}
  }
}

GET

api

brands

{brandId}

matrix

Get GEO Matrix

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/matrix \
  --header 'Authorization: <authorization>'

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>"
  },
  "granularity": "<string>",
  "providers": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "rows": [
    {
      "id": "<string>",
      "name": "<string>",
      "promptCount": 123,
      "mentionRate": 123,
      "coverage": {
        "count": 123,
        "total": 123,
        "percentage": 123
      },
      "cells": [
        {
          "provider": "<string>",
          "score": 123,
          "subScores": {
            "mentionRate": 123,
            "shareOfVoice": 123,
            "citationRate": 123,
            "sentiment": 123
          },
          "ranking": {
            "mentionRate": {},
            "shareOfVoice": {},
            "citationRate": {},
            "sentiment": {}
          },
          "citations": 123,
          "position": 123,
          "topCompetitor": "<string>",
          "topCompetitors": [
            {}
          ],
          "topSources": [
            {}
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    {
      "provider": "<string>",
      "score": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "citationRate": 123,
      "sentiment": 123
    }
  ],
  "summary": {
    "totalRows": 123,
    "averageMentionRate": 123,
    "topPerforming": {},
    "needsAttention": {}
  }
}

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

Value	Groups rows by
`topics`	Keywords/topics (default)
`tags`	Tags applied to prompts
`prompts`	Individual monitored questions
`funnel`	Funnel stages (TOFU/MOFU/BOFU)

Response

success

boolean

Indicates if the request was successful

brand

object

Show Brand info

string

Brand ID

name

string

Brand name

granularity

string

The granularity used for this matrix (topics, tags, prompts, or funnel)

providers

array

List of AI providers used as columns. Each entry is an object with an id and a name.

Show Provider object

string

Provider ID (e.g., chatgpt, perplexity, claude)

name

string

Display name of the provider

rows

array

Matrix rows, one per topic/tag/prompt/funnel stage

Show Row structure

string

Row identifier (topic ID, tag ID, prompt ID, or funnel stage)

name

string

Display name of the row

promptCount

number

Number of distinct prompts in this row

mentionRate

number

Row-level brand mention rate (%) across all providers

coverage

object

Row-level coverage: how many responses in this row mention your brand. Reported per row, not per cell.

Show Coverage object

count

number

Responses in this row that mention your brand

total

number

Total responses in this row

percentage

number

Coverage percentage (0-100)

cells

array

One cell per provider

Show Cell structure

provider

string

Provider ID

score

number

Composite GEO score (0-100)

subScores

object

Show Sub-scores breakdown

mentionRate

number

Brand mention rate (%)

Share of voice (%)

citationRate

number

Source citation rate (%)

sentiment

number

Average sentiment (0-100)

ranking

object

Show Ranking per metric

mentionRate

object

Rank and total (e.g., {"rank": 2, "total": 8})

Rank and total

citationRate

object

Rank and total

sentiment

object

Rank and total

citations

number

Number of source citations

position

number

Best (minimum) position your brand reaches across this cell’s responses (lower is better; null if not mentioned)

topCompetitor

string

Name of the leading competitor in this cell (null if none)

topCompetitors

array

Top competitors in this cell, each with name, mentions, avgPosition, and relationship

topSources

array

Top cited sources in this cell

providerAverages

array

Per-provider average metrics across all returned rows.

Show Provider average object

provider

string

Provider ID

score

number

Average composite GEO score for this provider (0-100)

mentionRate

number

Average mention rate for this provider (%)

Average share of voice for this provider (%)

citationRate

number

Average citation rate for this provider (%)

sentiment

number

Average sentiment for this provider (0-100)

summary

object

Show Summary statistics

totalRows

number

Total number of rows

averageMentionRate

number

Average mention rate across all returned rows (%)

topPerforming

object

Highest mention-rate row, or null. Shape: { rowId, rowName, mentionRate }.

needsAttention

object

Lowest non-zero mention-rate row below 50%, or null. Shape: { rowId, rowName, mentionRate }.

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"
  },
  "granularity": "topics",
  "providers": [
    { "id": "chatgpt", "name": "ChatGPT" },
    { "id": "perplexity", "name": "Perplexity" },
    { "id": "claude", "name": "Claude" }
  ],
  "rows": [
    {
      "id": "topic1",
      "name": "Product Reviews",
      "promptCount": 12,
      "mentionRate": 52.4,
      "coverage": { "count": 38, "total": 60, "percentage": 63.0 },
      "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,
          "topCompetitor": "Competitor A",
          "topCompetitors": [
            { "name": "Competitor A", "mentions": 9, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Competitor B", "mentions": 6, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "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,
          "topCompetitor": "Competitor B",
          "topCompetitors": [
            { "name": "Competitor B", "mentions": 11, "avgPosition": 2, "relationship": "DIRECT" },
            { "name": "Competitor A", "mentions": 7, "avgPosition": 4, "relationship": "DIRECT" }
          ],
          "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,
          "topCompetitor": "Competitor A",
          "topCompetitors": [
            { "name": "Competitor A", "mentions": 5, "avgPosition": 3, "relationship": "DIRECT" }
          ],
          "topSources": [
            { "domain": "mybrand.com", "citations": 3 }
          ]
        }
      ]
    }
  ],
  "providerAverages": [
    { "provider": "chatgpt", "score": 72, "mentionRate": 65.0, "shareOfVoice": 18.5, "citationRate": 30.2, "sentiment": 81.0 },
    { "provider": "perplexity", "score": 58, "mentionRate": 50.0, "shareOfVoice": 12.3, "citationRate": 42.1, "sentiment": 76.0 },
    { "provider": "claude", "score": 45, "mentionRate": 35.0, "shareOfVoice": 9.8, "citationRate": 15.0, "sentiment": 72.0 }
  ],
  "summary": {
    "totalRows": 12,
    "averageMentionRate": 50,
    "topPerforming": {
      "rowId": "topic1",
      "rowName": "Product Reviews",
      "mentionRate": 52.4
    },
    "needsAttention": {
      "rowId": "topic7",
      "rowName": "Pricing",
      "mentionRate": 31.0
    }
  }
}

Error Responses

Status	Code	Description
400	`INVALID_PARAMETER`	Invalid query parameter (e.g., unknown granularity)
401	`INVALID_TOKEN`	Authentication failed
404	`BRAND_NOT_FOUND`	Brand doesn’t exist or not accessible

Get Performance Snapshot List Prompts

​Get Matrix

​Path Parameters

​Query Parameters

​Granularity Options

​Response

​Example Request

​Example Response

​Error Responses

Get Matrix

Path Parameters

Query Parameters

Granularity Options

Response

Example Request

Example Response

Error Responses