Ads Lighthouse API

Authentication

Create a key in Settings > API and MCP. The account owner and account admins can create keys, and the full key is shown once. Choose read only, or read and write.

Send the key in the Authorization header of every request. Keys act for the whole account and stop working as soon as they are revoked, or when the person who created them leaves the account or is no longer an admin.

Browser sessions are not accepted, and the API does not allow cross-origin browser requests. Keep keys on a server or in a secret manager.

Authorization: Bearer als_your_key

Quick start

List your projects, then read the last 7 days of saved checks for one of them. Every project endpoint accepts the project id, the brand domain or the exact project name.

# List your projects
curl -s https://adslighthouse.com/api/v1/projects \
  -H "Authorization: Bearer $ADS_LIGHTHOUSE_API_KEY"

# Saved checks for one project in the last 7 days, Google on mobile
curl -s -G https://adslighthouse.com/api/v1/projects/nike.example/observations \
  -H "Authorization: Bearer $ADS_LIGHTHOUSE_API_KEY" \
  --data-urlencode "range=7d" \
  --data-urlencode "engine=google" \
  --data-urlencode "device=mobile"

const base = "https://adslighthouse.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.ADS_LIGHTHOUSE_API_KEY}` };

// Advertisers seen on the project's searches, busiest first
const response = await fetch(`${base}/projects/nike.example/advertisers?range=30d`, { headers });
if (!response.ok) {
  const { error, request_id } = await response.json();
  throw new Error(`${error.code}: ${error.message} (${request_id})`);
}
const report = await response.json();
for (const advertiser of report.data)
  console.log(advertiser.domain, advertiser.visibility, report.note ?? "");

Endpoints

All paths are relative to the base URL below. Read endpoints need the read scope; the others need a key with write access.

https://adslighthouse.com/api/v1

Dates and filters

Reports use the same filters as the app: engine, device, os, country and location. Send one value, repeat the parameter, or pass a JSON array such as engine=["google","bing"]. Values in one filter combine with OR, and different filters combine with AND.

Dates default to the last 30 days. Use range=7d, 14d, 30d or 12m, or range=custom with from and to (YYYY-MM-DD). Days start and end in the time zone of the person who created the key, or in the IANA time zone you pass as time_zone. The response echoes the exact window it used.

Pagination

Lists return data and next_cursor. Pass next_cursor as cursor to get the next page, with the same filters. It is null on the last page. limit accepts 1 to 200 and defaults to 50.

Report rows, such as advertisers, are computed for the whole filtered selection before paging, so shares do not depend on the page size.

Changes and paid checks

Creating a project and running an on-demand check start searches that use your plan's allowance. Both need an Idempotency-Key header with a unique value, such as a UUID. Repeating a request with the same key returns the first result and never reserves or runs the checks again. Reusing a key for a different request returns 409.

Checks run in the background. Poll the check status endpoint, then read the results from the observations endpoint.

curl -s -X POST https://adslighthouse.com/api/v1/projects/nike.example/checks \
  -H "Authorization: Bearer $ADS_LIGHTHOUSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"device": "mobile"}'

Reading the results honestly

An observation is one saved check: one search result page for a keyword, engine, device and location at one moment. It shows that an ad was displayed; it is not proof of a purchased keyword, spend or an infringement.

visibility is the share of saved observations in the selection where a domain showed at least one ad. It is not impression share. ads_observed counts ad occurrences, not unique advertisers. When a report is based on few observations, the note field says so.

Errors

Errors use one envelope with a stable code, a message and, for invalid input, field details. Every response carries a request_id; include it if you contact us.

{
  "error": {
    "code": "invalid_request",
    "message": "The request has invalid parameters.",
    "details": [{ "field": "os", "message": "Operating system does not match device" }]
  },
  "request_id": "5f0c1c1e-8f7a-4c52-9a55-2f1c3e8b7d10"
}

Rate limits

Each key or connected app may make 120 requests per minute. Responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response includes Retry-After in seconds. Repeated failed authentication from one address is blocked for a few minutes.

Questions