Lumirank Data model
The brand, competitors, prompts, answers, mentions, and citations, and how they connect.
brand (the key's)
|- competitors brands that AI answers name next to yours
|- prompts questions Lumirank asks AI engines
|- answers 1 prompt, asked to 1 engine, in 1 country, at 1 time
|- mentions 1 row per brand the answer ranks or names
|- citations 1 row per source the answer citesIds are UUIDs. They are the same ids the app shows in its URLs.
Brand
GET /v1/brand returns the brand that the key belongs to. It gives the brand's domains (domains), the countries its active prompts run in (countries), the engines it tracks (engines), how many prompts it has in each status (prompt_counts), and the time of its newest answer (data_through).
It also gives competitor_id: the id of your own brand in the list of brands that answers rank. In mention rows and in the brands report, rows with this id are about your brand, and they have is_self: true.
Competitors
GET /v1/competitors returns the other brands that AI answers name. Each one has a status:
| Status | Meaning |
|---|---|
tracked | You compare your brand with it. The brands report includes it. |
suggested | AI answers name it, but you have not chosen to track it yet. |
dismissed | You set it aside. Later answers do not suggest it again. |
Your own brand is not in this list. To change a status, use PATCH /v1/competitors/{competitor_id}.
Prompts
GET /v1/prompts returns the questions Lumirank asks. Each prompt runs in 1 or more countries.
| Status | Asked every day | Its answers in lists and reports |
|---|---|---|
active | yes | yes |
paused | no | yes |
archived | no | only with include_archived=true |
intent says what kind of question it is: brand, comparison, how_to, informational, or other. To add a prompt, use POST /v1/prompts. To change one, use PATCH /v1/prompts/{prompt_id}.
Answers
GET /v1/answers returns 1 row per AI answer, with its text. Each row says whether the answer names your brand (brand_mentioned), your brand's position in the answer's list (brand_position), the sentiment about your brand (brand_sentiment), how many brands the answer ranked (brands_ranked), and how many sources it cited (citation_count).
Mentions and citations
GET /v1/mentions returns 1 row for each brand that an answer ranks or names, your brand included. A brand that is named only in the text, not in a ranked list, has position: null.
GET /v1/citations returns 1 row for each source that an answer cites, with its url, its domain, and its position in the engine's list of sources.
Rows in the 3 lists connect through the answer: each mention and citation row has the answer_id of its answer, which is the id of the answer row. See Export every answer to a warehouse.