List topics
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/keywords \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/keywords"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/keywords', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"pagination": {
"total": 123,
"count": 123,
"limit": 123,
"offset": 123
},
"keywords": [
{
"id": "<string>",
"keyword": "<string>",
"totalPrompts": 123,
"totalAnswers": 123,
"brandMentionRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123
}
]
}Topics
List topics
Analyze performance by topic (keyword).
GET
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
keywords
List topics
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/keywords \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/keywords"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/keywords', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"pagination": {
"total": 123,
"count": 123,
"limit": 123,
"offset": 123
},
"keywords": [
{
"id": "<string>",
"keyword": "<string>",
"totalPrompts": 123,
"totalAnswers": 123,
"brandMentionRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123
}
]
}Lists topics with answer counts and response-level SELF metrics for the selected scope. The API route retains
See Rate limits for retry behavior.
keywords and keyword field names for compatibility.
See Entities for the complete Topic object structure.
string
required
Bearer token. Example:
Bearer qw-api-xxxPath parameters
string
required
The unique identifier of the brand
Query parameters
number
Number of days to include. If not specified, returns all data.
string
Start date in
YYYY-MM-DD. Provide it with endDate; a lone boundary is currently ignored. Choose either period or the complete date pair.string
End date in
YYYY-MM-DD. Provide it with startDate; a lone boundary is currently ignored. Do not combine the complete date pair with period.string
Filter by AI provider. Supports comma-separated multi-select (e.g.,
chatgpt,claude).string
Filter by tag ID. Supports comma-separated multi-select (e.g.,
id1,id2).number
default:"50"
Maximum number of topics to return (max: 100)
number
default:"0"
Number of results to skip for pagination
string
default:"prompts"
Field to sort by:
prompts, answers, mentionRate, shareOfVoice, sentiment, keywordstring
default:"desc"
Sort order:
asc or descResponse
boolean
Indicates if the request was successful
object
array
Show Topic object
Show Topic object
string
Topic ID
string
Topic text
number
Number of prompts with this topic
number
Stored answers in the selected scope
number
Answers with a SELF mention divided by answers with a SELF or DIRECT mention
number
SELF mention occurrences divided by SELF and DIRECT mention occurrences
number
Average SELF mention sentiment on a 0 to 100 scale;
0 is returned when no scored SELF mention existsSynthetic request
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/keywords?limit=10" \
-H "Authorization: Bearer $QWAIRY_API_TOKEN"
Synthetic response
{
"success": true,
"pagination": {
"total": 25,
"count": 2,
"limit": 10,
"offset": 0
},
"keywords": [
{
"id": "topic_01",
"keyword": "data exports",
"totalPrompts": 15,
"totalAnswers": 120,
"brandMentionRate": 45.5,
"shareOfVoice": 32.1,
"avgSentiment": 78.3
},
{
"id": "topic_02",
"keyword": "analytics integrations",
"totalPrompts": 8,
"totalAnswers": 64,
"brandMentionRate": 28.1,
"shareOfVoice": 18.5,
"avgSentiment": 72.0
}
]
}
Errors
| Status | Code | Description |
|---|---|---|
| 401 | gateway error | Missing or invalid API token |
| 404 | BRAND_NOT_FOUND | Brand doesn’t exist or not accessible |
| 429 | gateway error | Rate limit exceeded; honor Retry-After |

