---
title: "Advertiser domains with visibility and signals"
method: GET
path: "/projects/{project_id}/advertisers"
tags: ["Reports"]
---

# Advertiser domains with visibility and signals

`GET /projects/{project_id}/advertisers`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/projects/{project_id}/advertisers`
- Auth: HTTP bearer

Ranks the advertiser domains seen on the project's monitored searches in the window and filters. Use the ranking to prioritize domains for review, then inspect a recurring advertiser with get_advertiser_history. visibility = observations_with_ads / observations: the share of saved checks where the domain showed at least one ad. It is not impression share, spend, or proof that the advertiser bought the keyword. keywords narrows to checks of those searched keywords, like the Paid results keyword filter. Tags are signals to review. When observations is small the note says so; repeat it when reporting. Includes saved studies, which have no engine or country, unless those filters are set.

## Path parameters

- `project_id` string, required: The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

## Query parameters

- `range` '7d' | '14d' | '30d' | '12m' | 'custom': Window ending today: 7d, 14d, 30d (default) or 12m. Use custom with from and to for fixed dates.
- `from` string: First local day, YYYY-MM-DD (custom range).
- `to` string: Last local day, YYYY-MM-DD, included in full (custom range).
- `time_zone` string: IANA time zone for day boundaries, such as America/New_York. Defaults to the time zone of the person the credential acts for.
- `engine` union: Search engine, or a list of engines combined with OR.
  - 'google' | 'bing'
  - string[]
- `device` union: Device, or a list combined with OR.
  - 'desktop' | 'mobile'
  - string[]
- `os` union: Operating system. unspecified matches checks that did not pin one. Must fit the chosen device.
  - 'windows' | 'macos' | 'android' | 'ios' | 'unspecified'
  - string[]
- `country` union: ISO 3166-1 alpha-2 country code such as US, or a list.
  - string
  - string[]
- `location` union: Saved location key: code:<location code>, name:<label> or country:<ISO code>. get_project_details lists the keys that have data.
  - string
  - string[]
- `keywords` union: Searched keyword, or a list of up to 100 combined with OR. Case and extra spaces are ignored.
  - string
  - string[]
- `limit` integer: Items per page, 1 to 200.
- `cursor` string: The next_cursor value from the previous page. Omit it for the first page.

## Response `200`

Advertiser domains with visibility and signals

- object
  - `data` object[], required
    - `domain` string, required: Advertiser domain as shown in ads; not a verified company.
    - `name` string, nullable, required: The label your team saved for this domain, if any.
    - `is_own_domain` boolean, required: True for the brand's own domains.
    - `visibility` number, required: Share of the saved observations in the selection where this domain showed at least one ad (observations_with_ads / observations). It is not impression share, spend or proof of a purchased keyword.
    - `observations_with_ads` integer, required
    - `ads_observed` integer, required: Paid ad occurrences for this domain.
    - `keywords` string[], required
    - `countries` string[], required
    - `locations` string[], required
    - `operating_systems` string[], required
    - `tags` string[], required: Signals seen in the ads: affiliate markers in links, the brand named in ad copy, coupon sites or lookalike domains. Signals to review, not conclusions.
    - `affiliate_ids` string[], required: Your affiliate IDs seen in this domain's links.
    - `first_seen` string, required
    - `last_seen` string, required
  - `next_cursor` string, nullable, required: Pass as cursor to get the next page; null on the last page.
  - `observations` integer, required: Saved observations in the selection: the visibility denominator.
  - `note` string, nullable, required: A caution about sample size or configuration to repeat when reporting results.
  - `window` object, required
    - `from` string, required: First local day included, YYYY-MM-DD.
    - `to` string, required: Last local day included, YYYY-MM-DD.
    - `time_zone` string, required
    - `start` string, required: Inclusive start instant, ISO 8601.
    - `end` string, required: Exclusive end instant, ISO 8601.
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

[API](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api.md) · [All operations](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/revisions/e1a4a40b11a9?raw)