Skip to main content
GET
/
api
/
v1
/
brands
/
{brandId}
/
keywords
/
{keywordId}
/
evolution
Topic Evolution
curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/keywords/{keywordId}/evolution \
  --header 'Authorization: <authorization>'
{
  "success": true,
  "keyword": {
    "id": "<string>",
    "text": "<string>"
  },
  "evolution": [
    {
      "date": "<string>",
      "answers": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": {},
      "sourceRate": 123
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt

Use this file to discover all available pages before exploring further.

Returns daily time-series metrics for a specific topic (keyword), including mention rate, share of voice, sentiment, and source citation rate.
​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand
​
keywordId
string
required
The unique identifier of the topic

​
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).
​
type
string
Filter by prompt type: TOFU, MOFU, BOFU

​
Response

​
success
boolean
Indicates if the request was successful
​
keyword
object
​
evolution
array

​
Example Request

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

​
Example Response

{
  "success": true,
  "keyword": {
    "id": "kw1",
    "text": "best CRM software"
  },
  "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
404KEYWORD_NOT_FOUNDTopic doesn’t exist or not accessible