List Topics

Analyze performance by topic (keyword)

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

List Topics

cURL

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

200

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

Track how your brand performs across different topics. Topics (also called keywords) are the semantic themes that organize your monitoring prompts.

See Entities for the complete Topic object structure.

Authorization · string · required

Bearer token. Example: Bearer qw-api-xxx

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

tag · string

Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

limit · number · default: "50"

Maximum number of topics to return (max: 100)

offset · number · default: "0"

Number of results to skip for pagination

sort · string · default: "prompts"

Field to sort by: prompts, answers, mentionRate, shareOfVoice, sentiment, keyword

order · string · default: "desc"

Sort order: asc or desc

Response

success · boolean

Indicates if the request was successful

pagination · object

Show Pagination info

total · number

Total number of topics matching filters

count · number

Number of topics in this response

limit · number

Maximum items per page

offset · number

Number of items skipped

keywords · array

Show Topic object

id · string

Topic ID

keyword · string

Topic text

totalPrompts · number

Number of prompts with this topic

totalAnswers · number

Total AI responses analyzed

brandMentionRate · number

Percentage of responses mentioning brand (0-100)

shareOfVoice · number

Brand mentions vs competitors (0-100)

avgSentiment · number

Average sentiment score (0-100)

Example Request

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

Example Response

{
  "success": true,
  "pagination": {
    "total": 25,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "keywords": [
    {
      "id": "kw1",
      "keyword": "best CRM software",
      "totalPrompts": 15,
      "totalAnswers": 120,
      "brandMentionRate": 45.5,
      "shareOfVoice": 32.1,
      "avgSentiment": 78.3
    },
    {
      "id": "kw2",
      "keyword": "enterprise solutions",
      "totalPrompts": 8,
      "totalAnswers": 64,
      "brandMentionRate": 28.1,
      "shareOfVoice": 18.5,
      "avgSentiment": 72.0
    }
  ]
}

Error Responses

Status	Code	Description
401	INVALID_TOKEN	Authentication failed
404	BRAND_NOT_FOUND	Brand doesn’t exist or not accessible