# Tags and topics

> Group prompts by topic, tag, funnel stage and brand mention, and get metrics for each group.

Canonical URL: https://gensiv.com/docs/tags-and-topics
Product: Gensiv — Become the brand AI recommends

---

A brand's prompts can be grouped in four ways. Every group works as a filter on the metrics and responses endpoints, and you can ask for metrics per group.

| Group            | How many per prompt | Set by                                           | Example                     |
| ---------------- | ------------------- | ------------------------------------------------ | --------------------------- |
| **Topic**        | One                 | You, or AI when it organises your prompts        | "Expense management"        |
| **Tag**          | Any number          | You                                              | "Q4 launch", "EMEA"         |
| **Funnel stage** | One                 | AI when a prompt is suggested; you can change it | `comparison`                |
| **Branded**      | Yes or no           | Automatic                                        | The prompt names your brand |

Topics are exclusive, so the responses in each topic add up to the brand's total. Tags overlap: a prompt with two tags counts in both.

## Funnel stages [#funnel-stages]

| Value           | Meaning                                                                  |
| --------------- | ------------------------------------------------------------------------ |
| `informational` | A question about a problem that does not ask for a product.              |
| `commercial`    | Asks for a recommendation or shortlist, such as "best CRM for agencies". |
| `comparison`    | Names products and compares them, or asks for alternatives to one.       |
| `transactional` | About price, free options, buying or booking.                            |

## Branded prompts [#branded-prompts]

A prompt is branded when its text names your brand. Branded prompts show how AI describes you rather than whether it recommends you, so their visibility is usually high. Filter with `branded=non-branded` to measure how often you are recommended to buyers who have not named you.

## List a brand's topics and tags [#list-a-brands-topics-and-tags]

[`GET /brands/{brandId}/prompt-groups`](/docs/api-reference/brands/listPromptGroups) returns the topics and tags with their ids.

```json
{
  "topics": [
    { "id": "3b0f57eb-ae2d-4d03-a049-55592c2d3f2a", "name": "Issue tracking" }
  ],
  "tags": [
    { "id": "9c1d7f1e-52a4-4a7e-8f1b-0a2f6f4d3c11", "name": "High intent" }
  ]
}
```

[`GET /brands/{brandId}/prompts`](/docs/api-reference/brands/listPrompts) returns each prompt's `topic`, `tags`, `funnelStage` and `branded`.

## Filter metrics and responses [#filter-metrics-and-responses]

These endpoints accept `topicId`, `tagId` and `branded`:

* [`GET /brands/{brandId}/metrics`](/docs/api-reference/metrics/getMetrics)
* [`GET /brands/{brandId}/metrics/daily`](/docs/api-reference/metrics/getDailyMetrics)
* [`GET /brands/{brandId}/metrics/prompts`](/docs/api-reference/metrics/getPromptMetrics)
* [`GET /brands/{brandId}/responses`](/docs/api-reference/responses/listResponses)

```bash
curl "https://api.gensiv.com/v1/brands/$BRAND_ID/metrics?topicId=$TOPIC_ID&branded=non-branded" \
  -H "Authorization: Bearer $GENSIV_API_KEY"
```

When you pass more than one filter, a response must match all of them.

## Metrics per group [#metrics-per-group]

[`GET /brands/{brandId}/metrics/groups`](/docs/api-reference/metrics/getGroupMetrics) returns one row per group. Set `groupBy` to `topic` (the default), `tag`, `funnelStage` or `branded`.

```json
{
  "from": "2026-09-02",
  "to": "2026-10-01",
  "groupBy": "topic",
  "data": [
    {
      "groupId": "3b0f57eb-ae2d-4d03-a049-55592c2d3f2a",
      "name": "Issue tracking",
      "prompts": 3,
      "responses": 533,
      "visibility": 42,
      "visibilityChange": 10.3,
      "avgPosition": 1.6,
      "sentiment": 86,
      "shareOfVoice": 9.3
    }
  ]
}
```

Prompts that are not in any group come back in a row with `groupId: null`.

## Groups follow the prompt [#groups-follow-the-prompt]

Group metrics use each prompt's current topic and tags. If you move a prompt to another topic, all of its past responses move with it, so a topic's history can change after you reorganise.