Skip to main content
Track how your brand performs across different tags. Tags are custom labels you can apply to prompts for grouping and filtering.
See Entities for the complete Tag object structure.

​
List Tags

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

​
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).
​
topic
string
Filter by topic (keyword) ID. Supports comma-separated multi-select (e.g., id1,id2).
​
limit
number
default:"50"
Maximum number of tags 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, name
​
order
string
default:"desc"
Sort order: asc or desc

​
Response

​
success
boolean
Indicates if the request was successful
​
pagination
object
​
tags
array

​
Example Request

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

​
Example Response

{
  "success": true,
  "pagination": {
    "total": 12,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "tags": [
    {
      "id": "tag1",
      "name": "Product Comparisons",
      "totalPrompts": 25,
      "totalAnswers": 200,
      "brandMentionRate": 52.0,
      "shareOfVoice": 38.5,
      "avgSentiment": 81.2
    },
    {
      "id": "tag2",
      "name": "Pricing Questions",
      "totalPrompts": 18,
      "totalAnswers": 144,
      "brandMentionRate": 35.4,
      "shareOfVoice": 22.1,
      "avgSentiment": 68.5
    }
  ]
}

​
Error Responses

StatusCodeDescription
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible

​
Tag Evolution

​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/tags/{tagId}/evolution
Returns daily time-series metrics for a specific tag.

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand
​
tagId
string
required
The unique identifier of the tag

​
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).
​
topic
string
Filter by topic (keyword) 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
​
tag
object
​
evolution
array

​
Example Request

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

​
Example Response

{
  "success": true,
  "tag": {
    "id": "tag1",
    "name": "Product Comparisons"
  },
  "evolution": [
    {
      "date": "2026-02-15",
      "answers": 42,
      "mentionRate": 65.2,
      "shareOfVoice": 48.3,
      "avgSentiment": 72.1,
      "sourceRate": 55.0
    },
    {
      "date": "2026-02-16",
      "answers": 38,
      "mentionRate": 60.5,
      "shareOfVoice": 45.1,
      "avgSentiment": 74.2,
      "sourceRate": 52.6
    }
  ]
}

​
Error Responses

StatusCodeDescription
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible
404TAG_NOT_FOUNDTag doesn’t exist or not accessible