Lumirank How reports work
The 3 reports, the query parameters they all take, and the rows they return.
The 3 reports
| Endpoint | Each row is | Use it to learn |
|---|---|---|
GET /v1/reports/visibility | your brand in 1 group | How often AI answers name my brand, how high they rank it, and how positive they are about it. |
GET /v1/reports/brands | 1 brand in 1 group: your brand and each tracked competitor | How my brand compares with its competitors, and what my share of voice is. |
GET /v1/reports/citations | 1 cited domain in 1 group, or 1 cited page with the url dimension | Which websites and pages AI engines cite for my prompts. |
A group is a set of answers that have the same values for the dimensions you ask for, for example the same week and the same engine. With no dimensions, the whole date range is 1 group. See Dimensions.
Query parameters
Every report takes the same query parameters. Every parameter is optional:
GET /v1/reports/brands?start_date=2026-09-01&end_date=2026-09-30&dimensions=week,engine&country=US,GB&order_by=share_of_voice:desc| Parameter | Default | More details |
|---|---|---|
start_date, end_date | the last 30 days | Dates and time zones |
dimensions | none | Dimensions |
engine, country, prompt_id, intent, and the filters of each report | no filter | Filters |
include_archived | false: the answers of archived prompts are left out | Filters |
order_by, limit, offset | depends on the report | Sorting and paging |
A report is a normal GET request, so you can use the same URL in a script, a spreadsheet, or a BI tool. Reports never change any data, so a read key can call them.
What a report returns
Each row is a JSON object with 1 key per column. So pandas.DataFrame(body["data"]) turns the rows into a table directly:
{
"data": [
{
"week": "2026-09-14",
"engine": "chatgpt",
"competitor_id": "5e0b3f71-9a2c-4d8e-b6f4-2c1d0e9f8a73",
"competitor_name": "Acme",
"is_self": true,
"answers": 412,
"mentions": 173,
"visibility": 0.4199,
"ranked": 160,
"share_of_voice": 0.2871
}
],
"meta": {
"report": "brands",
"start_date": "2026-09-01",
"end_date": "2026-09-30",
"dimensions": ["week", "engine"],
"country": ["US", "GB"],
"include_archived": false,
"order_by": ["share_of_voice:desc"],
"limit": 1000,
"offset": 0,
"total": 48,
"has_more": false,
"data_through": "2026-09-30T06:41:12Z"
}
}This example shows 1 row and leaves out some of its columns. meta lists the parameters the report used, with the defaults filled in, so you can see exactly what it counted. data_through is the time of the newest answer inside the date range.
Rules for all reports
- Rates are fractions from 0 to 1, rounded to 4 decimals. When a rate has nothing to divide by, it is
null. - You can add up counts across rows, but not rates or averages. See Metrics.
- A group with no answers has no row.
- In the brands report, every group with answers has a row for every brand in the report, with
mentions: 0when no answer named the brand. So a chart of a competitor has a point for every week, even a week when no answer named it.