The API puts your brands' figures wherever you report: a client dashboard, a spreadsheet, your own reporting tool. It returns the Flare score and its five factors, how each AI engine treats the brand, and share of voice against competitors, for every brand on your workspace.
It's part of the Agency plan. It reads and changes nothing, and every figure it returns is the one the brand's pages show.
Your first result in two minutes
- Open Settings › API and select Create key. Give it a name and choose what it reads: all your brands, or one brand only.
- Copy the key. It's shown once, so copy it before you leave the page.
- Send it with a request:
curl -H "Authorization: Bearer YOUR_KEY" https://brandflare.io/api/v1/brands
You get your brands back, each with its current Flare score:
{
"brands": [
{
"id": "3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34",
"name": "Northwind Coffee",
"domain": "northwindcoffee.com",
"category": "Coffee",
"score": 72,
"band": "High",
"early_score": false,
"markets": ["gb"],
"last_checked": "2026-09-29T06:12:40Z",
"next_check": "2026-10-06",
"url": "https://brandflare.io/brands/3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34"
}
]
}
The id is what every other address takes. Settings › API also has a preview: choose what you want and it shows the real answer for your brands, with the request already written out.
In Google Sheets, with no code
Every address can return a table instead of JSON, and Google Sheets can import a table from an address. Put this in a cell:
=IMPORTDATA("https://brandflare.io/api/v1/brands?format=csv&key=YOUR_KEY")
The sheet fills with one row per brand, and Sheets refreshes it by itself, about once an hour while the sheet is open. Swap the address for any of the others below, such as a brand's score history, to chart it.
Two more places the same link works:
- Looker Studio. Connect the Google Sheet as a data source. That's the simplest route from brandflare to a Looker Studio report.
- Excel and Power BI. In Excel use Data › From Web, in Power BI Get data › Web, and paste the link.
A spreadsheet formula can't send a header, so here the key goes in the address as key=. Anyone who can open the sheet can read that key, which is the reason to use a key that reads one brand for anything a client will see.
Keys
A key is how the API knows a request is yours. You make them in Settings › API, and you can have as many as you need.
- All brands, or one. A key for all brands reads every brand on the workspace, including ones you add later. A key for one brand reads that brand and nothing else, so a key sitting in one client's dashboard can never show another client's figures.
- Shown once. brandflare keeps only a fingerprint of a key, so it can't show it to you again. If one is lost, delete it and make another.
- One per place. Give each dashboard, sheet or client its own key, named after where it's used. Then you can delete one without disturbing the rest, and Last used tells you which are still in service.
- Deleting is immediate. Whatever was using the key is refused from the next request on.
- Owners and admins create and delete keys. Everyone on the workspace can see the list. See teams and roles.
Treat a key like a password. It can only read, but what it reads is your clients' data.
Sending the key
From code, send it as a header:
Authorization: Bearer YOUR_KEY
Where a header isn't possible, as in a spreadsheet formula, add it to the address as ?key=YOUR_KEY. Prefer the header wherever you have the choice: addresses end up in browser histories and logs, and headers don't.
Don't call the API from a page your visitors load in their browser, because the key would be readable in the page's source. Fetch from your server and pass the figures on.
The addresses
Everything lives under https://brandflare.io/api/v1. Every address is a GET.
| Address | Returns |
|---|---|
/brands | Your brands, each with its current Flare score |
/brands/{id} | One brand: score, five factors, last and next check |
/brands/{id}/history | The score and factors day by day |
/brands/{id}/engines | How each AI engine treats the brand |
/brands/{id}/competitors | Share of voice against competitors |
Your brands
GET /brands
Every brand the key can read, in name order. Archived brands are left out. The example is at the top of this page.
| Field | Meaning |
|---|---|
id | The brand's ID, used in every other address |
name, domain, category | The brand as it appears in brandflare |
score | The Flare score, 0 to 100. null until the first check has finished |
band | Very high, High, Moderate, Low or Very low |
early_score | true while the score is marked "Early score, still settling" |
markets | The markets the brand is checked in |
last_checked | When the last check finished, in UTC |
next_check | The date of the next one, or null if checks are paused |
url | The brand's page in brandflare |
One brand
GET /brands/{id}
{
"id": "3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34",
"name": "Northwind Coffee",
"domain": "northwindcoffee.com",
"category": "Coffee",
"archived": false,
"market": "gb",
"markets": [{ "market": "gb", "name": "United Kingdom", "home": true }],
"score": 72,
"band": "High",
"early_score": false,
"score_previous": 69,
"score_change": 3,
"change_days": 14,
"answers_judged": 412,
"factors": {
"visibility": 80,
"prominence": 64,
"accuracy": 91,
"consistency": 70,
"sentiment": 66
},
"competitors": ["Bluebird Roasters", "Harbour Coffee Co"],
"last_checked": "2026-09-29T06:12:40Z",
"next_check": "2026-10-06",
"url": "https://brandflare.io/brands/3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34"
}
| Field | Meaning |
|---|---|
score, band, early_score | As in the list above |
score_previous | The score change_days days earlier, the same comparison the brand's page makes |
score_change | score minus score_previous |
answers_judged | How many judged answers are behind the score |
factors | The five factors, each 0 to 100: Visibility, Prominence, Accuracy, Consistency and Sentiment. A factor that hasn't been measured yet is null, never zero |
competitors | The competitors tracked for this brand |
market, markets | The market these figures are for, and the markets available. See Markets, below |
What each factor measures is in how the Flare score works.
Score history
GET /brands/{id}/history
One row for each day the brand has a score, oldest first. This is the line on the brand's Flare chart, with the factors beside it.
| Option | Meaning |
|---|---|
days | How far back to go, from 1 to 365. The default is 90 |
{
"brand": { "id": "3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34", "name": "Northwind Coffee" },
"market": "gb",
"days": 90,
"history": [
{ "date": "2026-09-22", "score": 69, "visibility": 76, "prominence": 62, "accuracy": 90, "consistency": 68, "sentiment": 66 },
{ "date": "2026-09-29", "score": 72, "visibility": 80, "prominence": 64, "accuracy": 91, "consistency": 70, "sentiment": 66 }
]
}
Engines
GET /brands/{id}/engines
One row for each engine: ChatGPT, Gemini, Google Search, Perplexity and Claude.
{
"brand": { "id": "3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34", "name": "Northwind Coffee" },
"market": "gb",
"change_days": 14,
"engines": [
{
"engine": "ChatGPT",
"visibility": 64,
"visibility_previous": 58,
"average_position": 1.8,
"average_position_previous": 2.1,
"share_of_voice": 31,
"measured_on": "2026-09-29"
}
]
}
| Field | Meaning |
|---|---|
visibility | The percentage of answers from this engine that name the brand. See how visibility is measured |
average_position | Where the brand comes among the brands named, on average. 1 is first, so lower is better |
share_of_voice | The brand's percentage of all mentions of it and its competitors on this engine |
visibility_previous, average_position_previous | The same figures change_days days earlier, or null if there are none that old |
measured_on | The date of the check these figures come from |
Competitors
GET /brands/{id}/competitors
Who AI names in answers to the brand's questions over the last 30 days, most named first. Your brand is one of the rows, marked your_brand.
{
"brand": { "id": "3f6c2a1e-9b4d-4c1a-8e2f-5a7d9c0b1e34", "name": "Northwind Coffee" },
"market": "gb",
"period_days": 30,
"companies": [
{
"name": "Northwind Coffee",
"your_brand": true,
"domain": "northwindcoffee.com",
"share_of_voice": 38,
"mentions": 152,
"average_position": 1.6,
"answers_naming_both": null,
"you_named_first": null,
"you_named_first_rate": null
},
{
"name": "Bluebird Roasters",
"your_brand": false,
"domain": "bluebirdroasters.com",
"share_of_voice": 34,
"mentions": 136,
"average_position": 2.2,
"answers_naming_both": 120,
"you_named_first": 78,
"you_named_first_rate": 65
}
]
}
| Field | Meaning |
|---|---|
share_of_voice | This company's percentage of all the mentions counted. The rows add up to 100 |
mentions | How many times it was named |
average_position | Where it comes among the brands named, on average |
answers_naming_both | For a competitor: the answers that named both it and your brand |
you_named_first, you_named_first_rate | Of those answers, how many named your brand first, as a count and a percentage |
How competitors are measured is in competitors.
Markets
A brand checked in more than one market has a set of figures for each. Add market to any brand address to choose:
https://brandflare.io/api/v1/brands/{id}?market=gb
Leave it out and you get what the brand's pages show by default: All markets combined (all) for a brand with several, or its one market otherwise. The markets list on /brands/{id} gives the values a brand accepts. A brand with no location is global.
A table instead of JSON
Add format=csv to any address and the answer is a table with a header row, ready for a spreadsheet or a reporting tool:
https://brandflare.io/api/v1/brands/{id}/history?format=csv
date,score,visibility,prominence,accuracy,consistency,sentiment
2026-09-22,69,76,62,90,68,66
2026-09-29,72,80,64,91,70,66
The columns are the fields described above. A figure that isn't measured yet is an empty cell.
How fresh the figures are
The API returns what the last check measured. Brands are checked weekly, so a brand's figures change once a week, on the day of its check; next_check tells you when. Fetching once a day keeps a dashboard current. The API can't start a check.
Limits
A key can make 60 requests a minute. Every answer says where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per minute |
X-RateLimit-Remaining | Requests left this minute |
Retry-After | On a refused request, the seconds to wait |
When something goes wrong
An error comes back as JSON with a code and a sentence saying what to do:
{
"error": {
"code": "invalid_key",
"message": "This API key isn't recognised. It may have been deleted. Make a new one in Settings › API."
}
}
| Status | Code | What it means |
|---|---|---|
| 400 | bad_request | Something in the address isn't right, such as a market the brand isn't checked in |
| 401 | missing_key | No key was sent |
| 401 | invalid_key | The key isn't recognised, or has been deleted |
| 403 | plan_required | The workspace doesn't have an active Agency plan |
| 403 | account_inactive | The account isn't active |
| 404 | not_found | No brand with that ID is available to this key. A key for one brand gets this for every other brand |
| 429 | rate_limited | More than 60 requests in a minute. Wait for Retry-After |
| 500 | server_error | A fault on brandflare's side. Try again, and raise a support request if it continues |
If the Agency plan ends, keys stop working and start again when it resumes. They aren't deleted.
Using it well
- One key per client. Use a one-brand key for anything a client can see, and an all-brands key only for your own reporting.
- Fetch daily, not constantly. The figures move weekly. A daily fetch is current; a fetch every minute returns the same numbers all week.
- Chart the history. A score on its own is a number; the line is the story.
/historyis the address a retainer report is built on, alongside Export Report. - Show the band with the score. "72, High" reads at a glance to a client who has never seen the scale.
- Keep
early_scorein view. While it'struethe score is still settling, so present it as provisional.