Topic Evolution

Daily time-series metrics for a specific topic

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

Topic Evolution

cURL

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

200

{
  "success": true,
  "keyword": {
    "id": "<string>",
    "text": "<string>"
  },
  "evolution": [
    {
      "date": "<string>",
      "answers": 123,
      "mentionRate": 123,
      "shareOfVoice": 123,
      "avgSentiment": {},
      "sourceRate": 123
    }
  ]
}

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

Show Topic info

id · string

Topic ID

text · string

Topic text

evolution · array

Show Daily metrics

date · string

Date (YYYY-MM-DD format)

answers · number

Number of AI responses analyzed

mentionRate · number

Percentage of responses mentioning brand (0-100)

shareOfVoice · number

Brand mentions vs competitors (0-100)

avgSentiment · number | null

Average sentiment score

sourceRate · number

Percentage of responses citing brand sources (0-100)

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

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