Ads Lighthouse API

Authentication

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

Send the key in the Authorization header of every request. A key acts for the whole account. It stops working as soon as it is revoked, or when the person who created it leaves the account or stops being an admin.

The API does not accept browser sessions or 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, and changes need write access. Each endpoint lists its scope and side effects.

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

Write operations can update projects, keywords, alert rules, team access, policy and affiliate reviews, and personal settings. Some also send invitations or test alerts, request reports, or trace saved ad destinations. Check each endpoint's scope and effects before you call it.

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 does not use your allowance or run 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"}'

How to read the results

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 appeared. It does not prove 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.

get_analytics returns chart-ready aggregates for the selected project, window and filters. Its active_keywords count covers the whole project and ignores the window and observation filters. Imported studies do not record engine or country, so they are left out when you filter by either. Shopping data is null when the plan does not include Shopping.

Observations and related history rows are kept for three UTC calendar months. An empty older window does not prove an advertiser or ad was absent: the records may have expired.

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. After repeated failed authentication, an address is blocked for a few minutes.

Questions