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

# Visibility report

> POST /v1/reports/visibility

Visibility Score and its components for your brand — or for you and your competitors — over a date range, optionally grouped by date, platform, prompt or category. Identical to the numbers on the dashboard for the same range. See [Metric definitions](/api-reference/metrics).

## Body

**site\_id** `string` *required*

The site's id, from [List sites](/api-reference/endpoints/list-sites).

**start\_date** `string` *required*

Inclusive day, `YYYY-MM-DD`, UTC.

**end\_date** `string` *required*

Inclusive day, `YYYY-MM-DD`, UTC. At most 92 days after `start_date`.

**group\_by** `enum\<string\>[]`

Any of: `date`, `platform`, `prompt`, `category`.

**metrics** `enum\<string\>[]`

Any of: `visibility_score`, `mention_rate`, `citation_rate`, `prompt_coverage`, `average_position`, `share_of_voice`, `answers`.

**brands** `enum\<string\> | string[]` (default: owned)

`owned` (your brand), `all` (you plus confirmed competitors, ranked), or a list of brand names.

**filter** `object`

Fields `platform`, `prompt`, `category`. See [Filtering](/api-reference/filtering).

**sort** `object`

**properties**

**field** `enum\<string\>` *required*

One of: `visibility_score`, `mention_rate`, `citation_rate`, `prompt_coverage`, `average_position`, `share_of_voice`, `answers`.

**dir** `enum\<string\>` (default: desc)

One of: `asc`, `desc`.

**limit** `integer` (default: 50)

Rows per page, 1–100.

**cursor** `string`

Opaque cursor from `info.next_cursor`.

## Response

**info** `object`

**properties**

**count** `integer`

Rows in this page.

**total\_results** `integer`

Rows across all pages.

**next\_cursor** `string`

Pass as `cursor` for the next page; null on the last page.

**site\_id** `string`

**start\_date** `string`

**end\_date** `string`

**data** `object[]`

One row per brand per group. Only the `group_by` fields and `metrics` you asked for are present.

**properties**

**date** `string`

**platform** `string`

**prompt** `object`

**properties**

**id** `string`

**text** `string`

**category** `string`

**brand** `object`

**properties**

**name** `string`

**owned** `boolean`

True for your own brand.

**rank** `integer`

Position by Visibility Score among you and your confirmed competitors, within this row's group.

**visibility\_score** `number`

0–100: 45% mention rate, 35% citation rate, 20% prompt coverage.

**mention\_rate** `number`

0–1: share of answers naming the brand.

**citation\_rate** `number`

0–1: share of answers linking to the brand's site.

**prompt\_coverage** `number`

0–1: share of prompts where the brand was named at least once.

**average\_position** `number`

Average order of first mention when named (1 = first). Null when never named.

**share\_of\_voice** `number`

0–1: the brand's share of all brand mentions (you plus confirmed competitors).

**answers** `integer`

Answers in the group.

```bash cURL theme={"system"}
curl -X POST https://api.rankraft.ai/v1/reports/visibility \
  -H "X-API-Key: $RANKRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "brands": "all",
    "group_by": ["platform"],
    "metrics": ["visibility_score", "mention_rate", "citation_rate"]
  }'
```

```javascript JavaScript theme={"system"}
// npm install rankraft-js · https://www.npmjs.com/package/rankraft-js
import { RankRaft } from "rankraft-js";

const rr = new RankRaft(); // reads RANKRAFT_API_KEY

const page = await rr.reports.visibility({
  site_id: "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
  start_date: "2026-09-01",
  end_date: "2026-09-30",
  brands: "all",
  group_by: ["platform"],
  metrics: ["visibility_score", "mention_rate", "citation_rate"],
});
for (const row of page.data) console.log(row.platform, row.brand.name, row.rank, row.visibility_score);
```

```python Python theme={"system"}
# pip install rankraft-py · https://pypi.org/project/rankraft-py/
from rankraft import RankRaft

with RankRaft() as rr:  # reads RANKRAFT_API_KEY
    page = rr.reports.visibility(
        site_id="3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
        start_date="2026-09-01",
        end_date="2026-09-30",
        brands="all",
        group_by=["platform"],
        metrics=["visibility_score", "mention_rate", "citation_rate"],
    )
    for row in page:
        print(row["platform"], row["brand"]["name"], row["rank"], row["visibility_score"])
```

```json 200 theme={"system"}
{
  "info": {
    "site_id": "3f2c9a10-7b1e-4c55-9d2a-1a2b3c4d5e6f",
    "start_date": "2026-09-01",
    "end_date": "2026-09-30",
    "count": 2,
    "total_results": 2,
    "next_cursor": null
  },
  "data": [
    {
      "platform": "chatgpt",
      "brand": { "name": "Shan Foods", "owned": false },
      "rank": 1,
      "visibility_score": 48,
      "mention_rate": 0.61,
      "citation_rate": 0.2
    },
    {
      "platform": "chatgpt",
      "brand": { "name": "Misali Foods", "owned": true },
      "rank": 2,
      "visibility_score": 31,
      "mention_rate": 0.4,
      "citation_rate": 0.13
    }
  ]
}
```


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