Lumirank Filters
Count only some answers in a report, for example only 1 engine or 1 country.
A filter is a query parameter that holds a list of values, separated by commas. The report then counts only the answers whose value is in the list. When you send more than 1 filter, an answer must match all of them.
?engine=chatgpt,perplexity&country=US| Parameter | Reports | Values |
|---|---|---|
engine | all 3 | engine ids, see Engines |
country | all 3 | 2-letter ISO 3166-1 country codes, in capital or small letters |
prompt_id | all 3 | ids of your brand's prompts. An archived prompt also needs include_archived=true. |
intent | all 3 | brand, comparison, how_to, informational, other |
competitor_id | brands | ids from /v1/competitors, or your own from /v1/brand |
domain | citations | domains in small letters, without www., for example g2.com |
is_own_domain | citations | 1 value: true or false |
content_type | citations | social_media, community, blog, docs, news, education, brand, government |
include_archived | all 3, and the 3 lists | true or false. The default is false: the answers and citations of archived prompts are left out. |
Rules
- A filter keeps only the values in its list. There is no way to leave values out, so list the values you want.
- A filter that you do not send, or send empty, counts everything.
- Each filter holds 1 to 100 values.
- The API checks every value. An unknown engine, a misspelt country, or the id of another brand's prompt gets status
400with the error codefilter_value_invalid, and the message names the wrong value. So a typo never returns 0 rows without telling you why. - The id of an archived prompt gets status
400with the error codefilter_value_invalidunless you sendinclude_archived=true. include_archivedtakestrueorfalse, in capital or small letters. Any other value gets status400with the error codeparameter_invalid.- A filter that the report does not accept, for example
domainon the visibility report, gets status400with the error codefilter_field_invalid.
competitor_id does not change the numbers
In the brands report, the numbers are calculated first, over all brands in the report. competitor_id then only chooses which rows to return. So share_of_voice still divides by all brands in the report, and your row shows the same numbers with or without the filter.
This request returns only your own row. It reads your competitor_id from /v1/brand with jq:
ME=$(curl -s https://api.lumirank.ai/v1/brand -H "Authorization: Bearer $LUMIRANK_API_KEY" | jq -r .competitor_id)
curl -G https://api.lumirank.ai/v1/reports/brands \
-H "Authorization: Bearer $LUMIRANK_API_KEY" \
-d competitor_id=$MEFilters in the citations report
engine, country, prompt_id, and intent count only the citations in the answers that match. content_type counts only the citations of pages of that type.