Introduction to the Lumirank API

The Lumirank API lets developers read and manage the data of the Lumirank app from their own code. Its reports give your visibility, share of voice, and citation numbers for each day, week, month, engine, country, or prompt. You can also read every AI answer, with its full text, your brand's position in it, the brands it mentions, and the web pages it cites. You can add, pause, resume, or archive your prompts, the questions that Lumirank asks AI engines for your brand. You can also track, suggest, or dismiss competitors.

You can use it to load your numbers into a BI tool, a spreadsheet, or a script, to compare your brand with its competitors over time, to copy every answer into a data warehouse, or to add prompts from your own system. The numbers match the dashboard, because each report counts answers by the same rules as its screen in the app.

You create API keys in the Lumirank dashboard, where you can also see the same data as charts.

QuickstartCopy Anchor Link

Every request goes to this base URL. The API accepts HTTPS only, and it sends and receives JSON:

https://api.lumirank.ai/v1

1. Pull your first reportCopy Anchor Link

First, create an API key:

1. Open app.lumirank.ai and go to Settings > API keys.
2. Click Create API key, give it a name, and keep Read access.
3. Copy the key. It starts with lr_, and Lumirank shows it only once.

A key works for 1 brand: the brand you choose on that page. Only owners and managers can create keys, on the Starter, Pro, or Scale plan or the trial.

Save the key in an environment variable, so that it does not appear in your shell history or in your code:

export LUMIRANK_API_KEY="lr_..."

Then ask for the brands report. Every request sends the key in the Authorization header. The brands report compares your brand with the competitors you track. With no parameters, it covers the last 30 days and returns 1 row per brand, with the highest share of voice first:

curl https://api.lumirank.ai/v1/reports/brands \
  -H "Authorization: Bearer $LUMIRANK_API_KEY"

{
  "data": [
    {
      "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-09", "end_date": "2026-10-08", "total": 4, "has_more": false }
}

This example shows 1 row and leaves out some meta fields. Rates are fractions from 0 to 1, so a visibility of 0.4199 is the 42% that the dashboard shows.

If you get status 401, the key is missing or was not copied in full. If you get status 403 with the error code plan_upgrade_required, your plan does not include API access.

2. Call the API from PythonCopy Anchor Link

This script asks for the brands report split by engine, and prints each brand's share of voice:

import os

import requests

API = "https://api.lumirank.ai/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['LUMIRANK_API_KEY']}"}

resp = requests.get(f"{API}/reports/brands", headers=HEADERS, params={"dimensions": "engine"}, timeout=30)
resp.raise_for_status()
for row in resp.json()["data"]:
    share = row["share_of_voice"]  # null when no brand was ranked in the group
    print(row["engine"], row["competitor_name"], "-" if share is None else f"{share:.1%}")

Next stepsCopy Anchor Link