Agency API

The Agency API lets you pull your clients' Luciqo data into Power BI, Excel, Looker Studio or your own code. It is read-only and only covers the brands in your workspace. Every endpoint returns JSON by default, or a CSV table when you ask for one.

Before you start

• An Agency plan. On other plans, API calls return 403 with "The API is included on the Agency plan."
• The workspace owner or an admin to create keys.
• Your Luciqo address. The Agency API page shows each endpoint with a Copy address button, so you get the exact URL. In the examples below, replace https://your-luciqo-address with it.

Create an API key

1. Click Agency API in the sidebar.
2. Under API keys, choose which brands the key can read: All brands in this workspace, or Only one brand.
3. Give the key a name, for example "Power BI for Client X".
4. Click Create key.
5. Copy the key straight away. It starts with lq_ and isn't shown again. Keep it secret, like a password.

Make one key per tool or client, so you can revoke one without affecting the others. To revoke a key, click Revoke, then Revoke again to confirm. It stops working at once.

Brand-limited keys

If you give a key to a client's own system, limit it to their brand. A brand-limited key:

• only lists that brand from /api/v1/brands, and
• returns 404 for any other brand ID, so it can never read your other clients.

Authenticate

Send the key in the Authorization header:

curl -H "Authorization: Bearer lq_your_key" \
  "https://your-luciqo-address/api/v1/brands"

Tools that can't send headers can add ?key=lq_your_key (or &key= if the address already has a ?) instead. Treat such addresses like passwords, as the key is visible in the URL.

Endpoints

All endpoints use GET. Start with the first one to find your brand IDs.

Endpoint	What it returns
/api/v1/brands	Your brands, with their IDs, website, sector, location and country
/api/v1/brands/{id}/visibility	Latest and previous AI visibility, by engine, top businesses, and the trend
/api/v1/brands/{id}/questions	Every question and AI engine in the latest analysis: mentioned, position, website cited, tone
/api/v1/brands/{id}/channels?days=90	Every channel from visit to revenue
/api/v1/brands/{id}/reputation	Reputation score, what it's made of, and review profiles
/api/v1/brands/{id}/content	GEO Writer pieces, readiness and where they're published

For channels, days can be 7, 30, 90, 180, 365 or all. Anything else uses 90.

JSON or CSV

By default you get JSON. Add ?format=csv (or &format=csv) to get a CSV file instead, ready for Excel or Power BI. The CSV holds the main table from each endpoint:

Endpoint	CSV contains
brands	One row per brand
visibility	The trend: one row per analysis
questions	One row per question and engine
channels	One row per channel
reputation	One row per part of the score
content	One row per piece

The JSON adds context the CSV leaves out, such as the brand, dates, periods, totals and the latest and previous summaries.

Rate limit

Each key can make up to 120 requests a minute. Above that, calls return 429 with "Too many requests: up to 120 a minute." Wait a minute and try again. A scheduled refresh in Power BI or a nightly job stays well within the limit.

Errors

Status	Meaning
401	The key is missing, isn't valid or has been revoked
403	The workspace isn't on the Agency plan
404	The brand doesn't exist, or the key can't read it
429	More than 120 requests in a minute

Errors come back as JSON with an error message.

What next

• Connect Power BI
• Client reports
• Reports features