Setup
Connect Looker
Lighthouse reads your Looker semantic layer, so the measures your team already defined in LookML become monitored metrics — same joins, same filters, same numbers as your dashboards. Setup takes about 20 minutes and most of it needs Looker Admin access.
Decide which model to connect
You • 5 minutes
You don’t need to connect all of Looker. Pick one model to start — whichever one holds the metrics you actually care about watching. Sales, revenue, and product usage models are the usual starting points.
To find the model name: open any Explore you use in Looker and look at the URL. It reads /explore/model_name/explore_name — the first part is the model.
ecommerce.Create a service account
Looker admin • 2 minutes
Lighthouse connects as its own account rather than borrowing a real person’s login. Access is then easy to audit and easy to revoke, and nothing breaks when someone leaves the company.
Looker has a dedicated account type for exactly this. On the Users page, the Add button opens a dropdown — choose Service Account, not Users.
Name it Lighthouse. Leave the Create default set of API credentialsswitch turned on — it’s on by default, and it saves you a step later. Then save.
Create a permission set
Looker admin • 3 minutes
A permission set is a named list of what an account can do. You’re creating one that allows reading and querying, and nothing else.
Name it Lighthouse Read Only, then tick these boxes in this order — Looker greys out a permission until its parent is ticked:
| Permission | Needed? | What it allows |
|---|---|---|
| access_data | Required | See any data at all — everything else depends on it |
| see_looks | Required | Required before explore can be ticked |
| explore | Required | Run queries against your Explores |
| see_lookml | Recommended | Read how each metric is defined |
| see_user_dashboards | Optional | Import existing dashboard tiles as monitors |
| see_sql | Optional | Read the SQL behind a metric |
Leave everything else switched off. In particular develop, deploy, manage_models, administer, save_content, and anything that sends or schedules content.
see_lookml, the connection still works fine. You only lose the ability for Lighthouse to warn you when someone changes a metric definition underneath a live monitor.Lighthouse Read Only appears in your list of permission sets.Create a model set
Looker admin • 2 minutes
A model set is a named list of which models an account can see. This is what keeps Lighthouse scoped to the model chosen in step 1 rather than everything in Looker.
Name it Lighthouse Models and select only the model from step 1. You can add more later without redoing any of this.
Lighthouse Models appears in your list of model sets, containing one model.Create the role and assign it
Looker admin • 3 minutes
A role combines the two things you just made — what the account can do, and which models it can see — and attaches them to the service account.
Name it Lighthouse. Set the permission set to Lighthouse Read Only and the model set to Lighthouse Models, then assign it to the service account from step 2.
Lighthouse.Copy the API credentials
Looker admin • 1 minute
These are the username and password Lighthouse uses to connect. Looker calls the two halves a Client ID and a Client Secret.
If you left the credentials switch on in step 2, a key already exists and you just need to open it. Service accounts live under their own tab on the Users page:
If no key is listed, click Create New API Key.
Network access
Looker admin • 5 minutes, if needed
Many companies restrict Looker so it only accepts connections from approved locations. What you need to do here depends entirely on how your Looker is hosted — and the two cases are genuinely different, so check which one you are before following either.
If you use Looker (Google Cloud core)
There is no IP Allowlist page in the admin panel on these instances — access is controlled in Google Cloud rather than in Looker. What matters is the connection type your instance was created with:
| Connection type | What it means for Lighthouse |
|---|---|
| Public | Works immediately, nothing to configure |
| Public secure or hybrid | Add the ranges below to the instance's IP allowlist in Google Cloud |
| Private IP only | Not reachable from outside your VPC — talk to us before going further |
If you use customer-hosted Looker
The admin panel does have an IP allowlist page:
If the allowlist is disabled, skip this step. If it is enabled, add both ranges below.
The ranges to add
Connect in Lighthouse
You • 2 minutes
In Lighthouse, go to /data-sources, click New Data Source, and choose Looker.
| Field | Required | Description |
|---|---|---|
| baseUrl | Yes | Your Looker web address, e.g. https://yourcompany.cloud.looker.com — copy it from your browser |
| port | No | Leave blank unless your admin says Looker is self-hosted, in which case it's usually 19999 |
| clientId | Yes | The Client ID from step 6 |
| clientSecret | Yes | The Client Secret from step 6 — stored encrypted |
| model | Yes | The model name from step 1 |
Click Test Connection. Lighthouse signs in, lists the Explores it can see, and refuses to save if anything is wrong — so a green result means the whole chain works.
Check the numbers match
You • 10 minutes
Don’t skip this. Before you build monitoring on top of the connection, confirm Lighthouse is seeing what your team sees.
Pick one metric you know well — something with a number you could recite from memory. Create it in Lighthouse, then open the equivalent tile in Looker for the same date range and compare.
If they match, you’re done and everything else will match too. If they don’t, it’s almost always row-level security — see access filters below.
Three things worth knowing
If your numbers don’t match
Some companies restrict what each person sees in Looker — a regional manager sees only their region, for example. This is called row-level security, and it follows the account making the request. Since Lighthouse connects as its own service account, that account needs to be told what it’s allowed to see, or it will quietly read a filtered slice of the data.
The symptom is unmistakable: Lighthouse consistently reports lower numbers than your dashboards. The fix is for your admin to set the right values in the User attributessection of the service account’s edit page:
If your data updates on a schedule
Some Explores are built on tables Looker rebuilds periodically rather than reading live — your admin will call these PDTs. If a metric sits on one, Lighthouse can only detect a change after the rebuild happens. A metric checked hourly on a table that rebuilds nightly will only ever move once a day.
This isn’t a problem, but it’s worth knowing before you set an alert expecting to hear within the hour. Ask your admin which of your Explores use PDTs and how often they refresh.
What this costs you in Looker
Each check Lighthouse runs is one query through Looker to your warehouse. Lighthouse only pulls the periods that have changed rather than re-reading full history every time, so normal usage sits comfortably inside Looker’s concurrency limits, which default to around 15 to 25 simultaneous queries per account per connection. If your instance also has an API rate limit configured, tell us the value and we will pace requests to fit. You will not notice the load, but your warehouse bill will see it, the same as any other scheduled query.
What Lighthouse stores
Lighthouse stores the structure of your LookML — Explore names, field names, labels, descriptions, and how each measure is defined — plus the aggregated numbers used to draw your metric charts. It does not store raw row-level data from your warehouse.
Credentials are encrypted at rest. For our full security posture and compliance status, see the Trust Center.
If something goes wrong
| What you see | What it usually means |
|---|---|
| The connection test just hangs, then times out | The IP allowlist in step 7. This is by far the most common cause — check it first. |
| "Invalid credentials" or a 401 error | The Client ID or Secret has a typo, or the key was revoked. Ask your admin to generate a new one. |
| It connects, but no Explores show up | The model set doesn't include the model you entered, or the role was never assigned to the service account. |
| Explores appear but some detail is missing | The see_lookml permission wasn't ticked. Harmless — you only lose change detection. |
| Numbers are lower than your dashboards | Row-level security. See "If your numbers don't match" above. |
| Nothing connects and your Looker is self-hosted | The port field is probably missing. Self-hosted Looker usually serves its API on 19999. |
For anything not listed here, see Troubleshooting or get in touch — we can usually tell from the error message which step went wrong.