Lumirank Common examples
Short examples of the calls most programs make. Pull a report, pull AI answers, read 1 answer, add a prompt, and pause a prompt.
Each example is a curl command. First save your key in the LUMIRANK_API_KEY environment variable, as the Quickstart shows. 2 examples read an id with jq. For longer scripts in Python and other tools, see the recipes.
Pull a report
This request asks for your visibility for each week and engine, over the last 30 days:
curl -G https://api.lumirank.ai/v1/reports/visibility \
-H "Authorization: Bearer $LUMIRANK_API_KEY" \
-d dimensions=week,engine{
"data": [
{
"week": "2026-09-14",
"engine": "chatgpt",
"answers": 412,
"mentions": 173,
"visibility": 0.4199,
"average_position": 2.4,
"sentiment": 38.5
}
],
"meta": { "report": "visibility", "start_date": "2026-09-09", "end_date": "2026-10-08", "total": 10, "has_more": false }
}This example shows 1 row and some of its columns. Each row counts the answers of 1 week from 1 engine. The other reports are the brands report and the citations report. All 3 take the same query parameters. See How reports work.
Pull AI answers
This request asks for the 10 oldest answers from ChatGPT in the last 30 days:
curl -G https://api.lumirank.ai/v1/answers \
-H "Authorization: Bearer $LUMIRANK_API_KEY" \
-d engine=chatgpt -d limit=10{
"data": [
{
"id": "f3a91c27-8d4e-4b5f-a6c7-9e0f1a2b3c4d",
"prompt_text": "What is the best CRM for a 5 person sales team?",
"engine": "chatgpt",
"country": "US",
"answered_at": "2026-10-07T04:12:55Z",
"brand_mentioned": true,
"brand_position": 2,
"text": "For a 5 person team, the strongest options are Globex, Acme, and Initech."
}
],
"meta": { "total": 1240, "limit": 10, "offset": 0, "has_more": true }
}Each row is 1 answer with its full text. brand_mentioned says whether the answer names your brand, and brand_position gives its rank in the answer's list. For another date range, send start_date and end_date. To read every answer, request the next pages. See Pagination.
Read the brands and sources in 1 answer
GET /v1/answers/{answer_id} returns 1 answer with its mentions and its citations. This example reads the id of 1 answer from the list, and then asks for that answer:
ANSWER_ID=$(curl -s -G https://api.lumirank.ai/v1/answers \
-H "Authorization: Bearer $LUMIRANK_API_KEY" -d limit=1 | jq -r '.data[0].id')
curl https://api.lumirank.ai/v1/answers/$ANSWER_ID \
-H "Authorization: Bearer $LUMIRANK_API_KEY"{
"id": "f3a91c27-8d4e-4b5f-a6c7-9e0f1a2b3c4d",
"text": "For a 5 person team, the strongest options are Globex, Acme, and Initech.",
"mentions": [
{ "competitor_name": "Globex", "is_self": false, "position": 1, "sentiment": 55 }
],
"citations": [
{ "url": "https://www.g2.com/categories/crm", "domain": "g2.com", "title": "Best CRM Software", "position": 0 }
]
}This example leaves out some fields. Each item in mentions is a brand that the answer ranks or names. Each item in citations is a web page that the answer cites as a source.
Add a prompt
Changes need a key with Read & write access. This request adds a prompt that Lumirank asks in the US:
curl -X POST https://api.lumirank.ai/v1/prompts \
-H "Authorization: Bearer $LUMIRANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Which CRM is easiest to set up for a small team?", "countries": ["US"], "intent": "comparison"}'The response is the new prompt, with its id and the status active. Lumirank asks it in the brand's next daily run. The prompt counts once for each of its countries toward the prompt limit of your plan. If the brand already has a prompt with this text, the request gets status 409 with the error code prompt_already_exists.
Pause a prompt
PATCH /v1/prompts/{prompt_id} changes a prompt. This example finds the prompt from the last example by its text, and then pauses it:
PROMPT_ID=$(curl -s -G https://api.lumirank.ai/v1/prompts \
-H "Authorization: Bearer $LUMIRANK_API_KEY" -d status=active -d limit=200 \
| jq -r '.data[] | select(.text == "Which CRM is easiest to set up for a small team?") | .id')
curl -X PATCH https://api.lumirank.ai/v1/prompts/$PROMPT_ID \
-H "Authorization: Bearer $LUMIRANK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'The response is the prompt with the status paused. Lumirank does not ask a paused prompt any more, but its past answers stay in reports. To resume it, send {"status": "active"}. To archive it, send {"status": "archived"}. You can also change its countries. See Update a prompt.
The list returns up to 200 prompts on each page. If your brand has more prompts, read the next pages too.