Get Performance Snapshot

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

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>",
    "domain": "<string>"
  },
  "period": {
    "start": "<string>",
    "end": "<string>"
  },
  "methodology": {
    "promptsCount": 123,
    "providersCount": 123,
    "providers": [
      {}
    ],
    "responsesTotal": 123,
    "responsesWithMentions": 123,
    "responsesWithSources": 123
  },
  "scores": {
    "mentionRate": 123,
    "mentionCount": 123,
    "mentionTotal": 123,
    "coverage": 123,
    "sourceRate": 123,
    "sourceCount": 123,
    "sourceTotal": 123,
    "sourcePages": 123,
    "sentiment": 123,
    "shareOfVoice": 123
  },
  "topCompetitors": [
    {}
  ],
  "topSources": [
    {}
  ],
  "byTopic": [
    {
      "id": "<string>",
      "topic": "<string>",
      "score": 123,
      "mentionRate": 123,
      "sourceRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": 123,
      "promptsCount": 123
    }
  ],
  "byTag": [
    {
      "id": "<string>",
      "name": "<string>",
      "score": 123,
      "mentionRate": 123,
      "sourceRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": 123,
      "promptsCount": 123
    }
  ]
}

GET

api

brands

{brandId}

performance

Get Performance Snapshot

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

{
  "success": true,
  "brand": {
    "id": "<string>",
    "name": "<string>",
    "domain": "<string>"
  },
  "period": {
    "start": "<string>",
    "end": "<string>"
  },
  "methodology": {
    "promptsCount": 123,
    "providersCount": 123,
    "providers": [
      {}
    ],
    "responsesTotal": 123,
    "responsesWithMentions": 123,
    "responsesWithSources": 123
  },
  "scores": {
    "mentionRate": 123,
    "mentionCount": 123,
    "mentionTotal": 123,
    "coverage": 123,
    "sourceRate": 123,
    "sourceCount": 123,
    "sourceTotal": 123,
    "sourcePages": 123,
    "sentiment": 123,
    "shareOfVoice": 123
  },
  "topCompetitors": [
    {}
  ],
  "topSources": [
    {}
  ],
  "byTopic": [
    {
      "id": "<string>",
      "topic": "<string>",
      "score": 123,
      "mentionRate": 123,
      "sourceRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": 123,
      "promptsCount": 123
    }
  ],
  "byTag": [
    {
      "id": "<string>",
      "name": "<string>",
      "score": 123,
      "mentionRate": 123,
      "sourceRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": 123,
      "promptsCount": 123
    }
  ]
}

Get a comprehensive overview of your brand’s visibility in AI-generated responses. Includes mention rates, source citations, sentiment scores, share of voice, and breakdowns by topic and competitor.

This endpoint returns aggregated metrics. See Competitor and Source for entity structures used in topCompetitors and topSources.

Key Formulas

Understanding how metrics are calculated is essential for reproducing results:

Metric	Formula	Details
Mention Rate	`mentionCount / mentionTotal × 100`	`mentionCount` = responses where your brand (SELF) is mentioned. `mentionTotal` = responses with at least one SELF or DIRECT competitor mention (not total responses).
Coverage	`mentionCount / responsesTotal × 100`	Percentage of all monitored responses mentioning your brand. Unlike Mention Rate, uses total responses as denominator.
Source Rate	`sourceCount / sourceTotal × 100`	`sourceCount` = responses citing your domain (SELF). `sourceTotal` = responses with at least one SELF or DIRECT source citation (not total responses).
Share of Voice	`sovSelf / sovTotal × 100`	`sovSelf` = distinct SELF mention count. `sovTotal` = distinct SELF + DIRECT mention count. INDIRECT mentions are excluded.

Common mistake: Using total responses as the denominator for Mention Rate, or including INDIRECT competitor mentions in the Share of Voice denominator. The API returns sovSelf and sovTotal so you can verify the calculation.

Get Performance Snapshot

Authorization

string

required

Bearer token. Example: Bearer qw-api-xxx

GET /api/v1/brands/{brandId}/performance

Path Parameters

brandId

string

required

The unique identifier of the brand

Query Parameters

period

number

Number of days to include in the snapshot. If not specified, returns all data.

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

type

string

Filter by prompt type: TOFU, MOFU, BOFU

Response

success

boolean

Indicates if the request was successful

brand

object

Show Brand info

string

Brand ID

name

string

Brand name

domain

string

Primary domain

period

object

Show Period info

start

string

Start date (ISO 8601)

end

string

End date (ISO 8601)

methodology

object

Show Methodology details

promptsCount

number

Total prompts analyzed

providersCount

number

Number of AI providers

providers

array

List of provider IDs (e.g., chatgpt, perplexity)

responsesTotal

number

Total AI responses generated

responsesWithMentions

number

Responses containing brand mentions

responsesWithSources

number

Responses citing sources

scores

object

Show Performance scores

mentionRate

number

Brand mention rate (%)

mentionCount

number

Number of responses where your brand (SELF) is mentioned

mentionTotal

number

Number of responses containing at least one SELF or DIRECT competitor mention. This is the denominator for mentionRate — it is NOT the total number of responses. INDIRECT mentions are excluded.

coverage

number

Brand coverage (%). Percentage of all monitored responses where your brand is mentioned. Formula: mentionCount / responsesTotal × 100.

sourceRate

number

Source citation rate (%)

sourceCount

number

Number of source citations

sourceTotal

number

Number of responses containing at least one SELF or DIRECT source citation. This is the denominator for sourceRate — it is NOT the total number of responses. INDIRECT sources are excluded.

sourcePages

number

Number of unique URLs from your domain (SELF) cited as sources across all AI responses.

sentiment

number

Average sentiment score (0-100)

Share of voice (%). Formula: SELF mentions / (SELF + DIRECT mentions) × 100. INDIRECT mentions are excluded.

topCompetitors

array

Top competitors by mention count

topSources

array

Top sources by citation count

byTopic

array

Show Topic breakdown object

string

Topic ID

topic

string

Topic name

score

number

Composite score (0-100). Formula: mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2.

mentionRate

number

Mention rate for this topic (%). Formula: selfMentionAnswers / responsesWithMentions × 100 where responsesWithMentions counts answers in this topic with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level scores.mentionRate.

sourceRate

number

Source citation rate for this topic (%). Formula: selfSourceAnswers / responsesWithSources × 100 where responsesWithSources counts answers in this topic with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level scores.sourceRate (INDIRECT excluded).

Share of voice for this topic (%). Formula: SELF mentions in topic / (SELF + DIRECT mentions in topic) × 100.

avgSentiment

number

Average sentiment score for brand mentions in this topic (null if no mentions)

promptsCount

number

Number of distinct prompts in this topic

byTag

array

Show Tag breakdown object

string

Tag ID

name

string

Tag name

score

number

Composite score (0-100). Formula: mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2.

mentionRate

number

Mention rate for this tag (%). Formula: selfMentionAnswers / responsesWithMentions × 100 where responsesWithMentions counts answers in this tag with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level scores.mentionRate.

sourceRate

number

Source citation rate for this tag (%). Formula: selfSourceAnswers / responsesWithSources × 100 where responsesWithSources counts answers in this tag with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level scores.sourceRate (INDIRECT excluded).

Share of voice for this tag (%). Formula: SELF mentions in tag / (SELF + DIRECT mentions in tag) × 100.

avgSentiment

number

Average sentiment score for brand mentions in this tag (null if no mentions)

promptsCount

number

Number of distinct prompts in this tag

Example Request

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

Example Response

{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "My Brand",
    "domain": "mybrand.com"
  },
  "period": {
    "start": "2024-12-01",
    "end": "2024-12-31"
  },
  "methodology": {
    "promptsCount": 156,
    "providersCount": 2,
    "providers": ["chatgpt", "perplexity"],
    "responsesTotal": 312,
    "responsesWithMentions": 230,
    "responsesWithSources": 184
  },
  "scores": {
    "mentionRate": 45.2,
    "mentionCount": 104,
    "mentionTotal": 230,
    "coverage": 33.33,
    "sourceRate": 23.9,
    "sourceCount": 44,
    "sourceTotal": 184,
    "sourcePages": 27,
    "sentiment": 78.1,
    "shareOfVoice": 8.13
  },
  "topCompetitors": [
    {
      "id": "cmp1",
      "name": "Competitor A",
      "relationship": "DIRECT",
      "mentions": 111,
      "avgPosition": 2.3,
      "avgSentiment": 75.2
    }
  ],
  "topSources": [
    {
      "id": "src1",
      "domain": "industry-news.com",
      "mentions": 102,
      "avgPosition": 3.1,
      "isSelf": false
    }
  ],
  "byTopic": [
    {
      "id": "topic1",
      "topic": "Product Reviews",
      "score": 68,
      "mentionRate": 67.50,
      "sourceRate": 28.00,
      "shareOfVoice": 9.44,
      "avgSentiment": 76.3,
      "promptsCount": 12
    }
  ],
  "byTag": [
    {
      "id": "tag1",
      "name": "comparison",
      "score": 72,
      "mentionRate": 55.00,
      "sourceRate": 30.00,
      "shareOfVoice": 10.25,
      "avgSentiment": 81.5,
      "promptsCount": 8
    }
  ]
}

Error Responses

Status	Code	Description
400	`INVALID_PARAMETER`	Invalid query parameter
401	`INVALID_TOKEN`	Authentication failed
404	`BRAND_NOT_FOUND`	Brand doesn’t exist or not accessible

Tag Evolution Get GEO Matrix

​Key Formulas

​Get Performance Snapshot

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Error Responses

Key Formulas

Get Performance Snapshot

Path Parameters

Query Parameters

Response

Example Request

Example Response

Error Responses