> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rankraft.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Segment by engine, category or prompt

> Break your Visibility Score down by the engine that answered, the prompt category, or the individual prompt.

The same visibility call splits by any answer dimension: put it in `group_by`. Use it to find where you are strong and where you are missing: one engine that never names you, a category of question where competitors win, a single prompt worth writing a page for.

| Segment | `group_by` | Row field |
| - | - | - |
| Engine | `["platform"]` | `platform`: `chatgpt`, `ai_overviews`, `ai_mode`, `gemini`, ... |
| Prompt category | `["category"]` | `category`: `Discovery`, `Comparison`, `Alternatives`, `How-to`, `Pricing`, `Brand` |
| Prompt | `["prompt"]` | `prompt`: `{ id, text }` |
| Two at once | e.g. `["platform", "category"]` | both |

To look at a single segment rather than all of them, use a `filter` instead, e.g. `{ "field": "platform", "op": "is", "value": "chatgpt" }`.

## How this example works

1. **Group by engine**, sort by score to rank the engines.
2. **Group by prompt** and keep those where you were never named. Those are the gaps.
3. **Show `answers`** on every row: a segment resting on a few answers is not a finding yet.

```js JavaScript theme={"system"}
import { RankRaft } from "rankraft-js";

const rr = new RankRaft();
const q = { site_id: process.env.RANKRAFT_SITE_ID, start_date: "2026-09-01", end_date: "2026-09-30" };

const byEngine = await rr.reports.visibility({
  ...q,
  group_by: ["platform"],
  metrics: ["visibility_score", "mention_rate", "citation_rate", "answers"],
  sort: { field: "visibility_score", dir: "desc" },
});
console.log("By engine");
for (const r of byEngine.data) {
  console.log(`  ${r.platform.padEnd(14)} ${String(r.visibility_score).padStart(3)}  mentioned ${(r.mention_rate * 100).toFixed(0)}%  (${r.answers} answers)`);
}

const byPrompt = await rr.reports
  .visibility({ ...q, group_by: ["prompt"], metrics: ["mention_rate", "answers"], limit: 100 })
  .all();
console.log("\nPrompts where you were never named");
for (const r of byPrompt.filter((r) => r.mention_rate === 0)) console.log(`  ${r.prompt.text}  (${r.answers} answers)`);
```

```python Python theme={"system"}
import os
from rankraft import RankRaft

q = dict(site_id=os.environ["RANKRAFT_SITE_ID"], start_date="2026-09-01", end_date="2026-09-30")

with RankRaft() as rr:
    by_engine = rr.reports.visibility(
        **q,
        group_by=["platform"],
        metrics=["visibility_score", "mention_rate", "citation_rate", "answers"],
        sort={"field": "visibility_score", "dir": "desc"},
    )
    by_prompt = rr.reports.visibility(**q, group_by=["prompt"], metrics=["mention_rate", "answers"], limit=100).all()

print("By engine")
for r in by_engine:
    print(f"  {r['platform']:<14} {r['visibility_score']:>3}  mentioned {r['mention_rate']:.0%}  ({r['answers']} answers)")

print("\nPrompts where you were never named")
for r in by_prompt:
    if r["mention_rate"] == 0:
        print(f"  {r['prompt']['text']}  ({r['answers']} answers)")
```

```bash curl theme={"system"}
curl https://api.rankraft.ai/v1/reports/visibility \
  -H "X-API-Key: $RANKRAFT_API_KEY" -H "Content-Type: application/json" \
  -d '{"site_id":"'$RANKRAFT_SITE_ID'","start_date":"2026-09-01","end_date":"2026-09-30",
       "group_by":["platform"],"sort":{"field":"visibility_score","dir":"desc"},
       "metrics":["visibility_score","mention_rate","citation_rate","answers"]}'
```

## Reading the segments

* **`prompt_coverage` per prompt is 0 or 1**, because a prompt either named you at least once or did not. Use `mention_rate` to see how often.
* **Per-engine rows don't average to the headline.** Engines answer different numbers of prompts each day; the headline weights every answer once.
* **Who beats you on a gap prompt?** Add `brands: "all"` with `group_by: ["prompt"]`: rows with `rank` 1 and `owned: false` show the competitor that leads each prompt.
* **The Brand category** ("is X any good", "X reviews") almost always names you. Filter it out to see how you do on questions that don't name you first: `{ "not": { "field": "category", "op": "is", "value": "Brand" } }`.

> [!NOTE]
>
> There are no region or persona segments: each site is measured from one market, set in the dashboard.

## Common follow-ups

> **[Where AI gets its answers](/cookbook/citation-sources)**
>
> What the engines cite for the prompts you miss.

> **[Read the answers](/api-reference/endpoints/list-answers)**
>
> Pass `prompt_ids` to read what each engine actually said.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.