---
title: "One advertiser's metrics, category and saved ads"
method: GET
path: "/projects/{project_id}/advertisers/{domain}"
tags: ["Reports"]
---

# One advertiser's metrics, category and saved ads

`GET /projects/{project_id}/advertisers/{domain}`

## Request

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

Returns one advertiser domain on the project's monitored searches: its Paid results row (visibility = observations where it showed at least one ad / observations, ad occurrences, keywords, markets, signals), the category and name your team saved for it, its automated policy review counts, and its saved ads newest first, 25 per page, each with the results-page screenshot of its first appearance when one was stored. observed_in_selection is false when the domain showed no ad in this window and filters; that is not proof it stopped advertising. Use get_advertiser_history to check how often the project measured the advertiser and where its presence changed. Metrics describe this saved sample and do not establish market share, spend, or whether a competitor stopped advertising. Includes imported studies unless engine or country filters are set. When a saved landing-page preview is available, each ad also has landing_screenshot metadata with an app_url; it is null when no preview was saved. MCP returns metadata and the app link, while REST serves the private JPEG rendered from saved HTML. New previews may include selected static styles, images and fonts fetched at render time; scripts and nested documents remain disabled, and fetched assets may differ from the original capture time.

## 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.
- `domain` string, required: Advertiser domain as it appears in list_advertisers, such as rival.example.

## 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[]
- `cursor` string: The next_cursor value from the previous page. Omit it for the first page.

## Response `200`

One advertiser's metrics, category and saved ads

- object
  - `domain` string, required
  - `name` string, nullable, required: The label your team saved; not a verified company.
  - `classification` 'unclassified' | 'competitor' | 'authorized_retailer' | 'affiliate' | 'reseller' | 'marketplace' | 'publisher' | 'coupon_site' | 'other', required: The category your team chose on the Advertisers page; unclassified when none.
  - `observed_in_selection` boolean, required
  - `metrics` object, nullable, 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
  - `policy_reviews` object, nullable, required: Automated first reading of ads that use the brand in their copy, against the advertising policy on trademarks and misrepresentation. It is a triage aid, not a legal finding.
    - `reviewed_ads` integer, required: Saved Google ads with an automated policy review.
    - `likely_policy_concern` integer, required
    - `needs_review` integer, required
    - `likely_allowed` integer, required
    - `insufficient_evidence` integer, required
    - `pending` integer, required: Queued, not reviewed yet.
    - `unavailable` integer, required: The review could not be completed.
  - `observations` integer, required: Saved observations: the visibility denominator.
  - `ads` object[], required
    - `keyword` string, required
    - `observed_at` string, required
    - `engine` 'google' | 'bing', nullable, required: Null for imported studies.
    - `device` string, nullable, required
    - `os` string, nullable, required
    - `country` string, nullable, required: Null for imported studies, which record no country.
    - `location` string, nullable, required
    - `position` integer, nullable, required: Paid slot, 1 is the first ad; null if unknown.
    - `title` string, nullable, required
    - `description` string, nullable, required
    - `display_url` string, nullable, required
    - `url` string, nullable, required: Destination URL exactly as observed, parameters included.
    - `placement` 'top' | 'bottom', nullable, required: Where a Google ad was shown on the page; null for Bing and older observations.
    - `rank_absolute` integer, nullable, required: Position among every element of the page, when the search reported it.
    - `assets` union[], nullable, required: Ad assets shown with the ad (sitelinks, phone, promotion, price, image, extra description rows). null: not captured (older observations, imported studies); []: captured, none shown.
      - union
        - object
          - `kind` 'sitelink', required
          - `title` string, nullable, required
          - `url` string, nullable, required
          - `description` string, nullable, required
        - object
          - `kind` 'phone', required
          - `number` string, required
        - object
          - `kind` 'promotion', required
          - `text` string, required
          - `url` string, nullable, required
        - object
          - `kind` 'price', required
          - `displayed` string, nullable, required
          - `current` number, nullable, required
          - `regular` number, nullable, required
          - `max_value` number, nullable, required
          - `currency` string, nullable, required: ISO 4217 code when reported.
          - `is_range` boolean, nullable, required
        - object: The ad showed an image; it is not stored.
          - `kind` 'image', required
        - object
          - `kind` 'description_line', required
          - `text` string, required
    - `screenshot` object, nullable, required: Picture of the results page where this ad (same domain, title and description) first appeared in the project; null when none was stored. Evidence of that page, not proof of spend.
      - `id` string, required: Download it over REST from /projects/{project_id}/screenshots/{id}.
      - `exact` boolean, required: true: the results page this ad was found on. false: only on older pictures, taken from a new load of the same search moments later, which may show different ads.
      - `captured_at` string, required
      - `app_url` string, required: Opens the picture in the app for a signed-in member of the project's account.
    - `landing_screenshot` object, nullable, required: Preview of saved HTML with scripts disabled. Static-assets previews fetch images, styles and fonts at render time; offline previews block external resources. Null when no preview exists.
      - `id` string, required
      - `captured_at` string, required
      - `app_url` string, required
      - `rendering` 'saved_html_offline' | 'saved_html_static_assets', required
  - `ads_total` integer, required
  - `next_cursor` string, nullable, required: Pass as cursor to get the next page; null on the last page.
  - `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)