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

# Tag Evolution

> Daily time-series metrics for a specific tag

Returns daily time-series metrics for a specific tag, including mention rate, share of voice, sentiment, and source citation rate.

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

<ParamField path="tagId" type="string" required>
  The unique identifier of the tag
</ParamField>

### Query Parameters

<ParamField query="period" type="number">
  Number of days to include. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date (ISO 8601 format)
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format)
</ParamField>

<ParamField query="provider" type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filter by topic (keyword) ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="type" type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="tag" type="object">
  <Expandable title="Tag info">
    <ResponseField name="id" type="string">Tag ID</ResponseField>
    <ResponseField name="name" type="string">Tag name</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="evolution" type="array">
  <Expandable title="Daily metrics">
    <ResponseField name="date" type="string">Date (YYYY-MM-DD format)</ResponseField>
    <ResponseField name="answers" type="number">Number of AI responses analyzed</ResponseField>
    <ResponseField name="mentionRate" type="number">Percentage of responses mentioning brand (0-100)</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Brand mentions vs competitors (0-100)</ResponseField>
    <ResponseField name="avgSentiment" type="number | null">Average sentiment score</ResponseField>
    <ResponseField name="sourceRate" type="number">Percentage of responses citing brand sources (0-100)</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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

| Status | Code              | Description                           |
| ------ | ----------------- | ------------------------------------- |
| 401    | `INVALID_TOKEN`   | Authentication failed                 |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible |
| 404    | `TAG_NOT_FOUND`   | Tag doesn't exist or not accessible   |