---
title: "One advertiser's distinct ad copy, newest first"
method: GET
path: "/projects/{project_id}/advertisers/{domain}/ad-copy"
tags: ["Reports"]
---

# One advertiser's distinct ad copy, newest first

`GET /projects/{project_id}/advertisers/{domain}/ad-copy`

## Request

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

Lists the distinct ad copy versions (headline, description and display URL, with spacing and URL spelling differences ignored) one advertiser showed on the project's monitored searches in the window, newest first observed version first. Each version has its first and last seen time, ad occurrences in the window, keywords, and, when it replaced an earlier version, previous_version_id and a word-level diff. Use the diff to brief the SEM team on messaging changes seen in the monitored results. Observed creative changes do not show which version performed better; the tool measures what appeared in saved checks, not clicks or conversions. first_seen is when monitoring first observed the copy, not when the advertiser launched it. To tell a new version from an old one, up to 90 days before the window are also read. A copy change is not evidence of a policy issue.

## 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[]
- `keyword` string: Only checks of this exact keyword text, as list_keywords returns it.
- `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`

One advertiser's distinct ad copy, newest first

- object
  - `domain` string, required
  - `data` object[], required
    - `version_id` string, required: Stable id of this copy: headline, description and display URL.
    - `headline` string, required
    - `description` string, required
    - `display_url` string, required
    - `first_seen` string, required: First saved check with this copy; not its launch date.
    - `last_seen` string, required
    - `ads` integer, required: Ad occurrences with this copy in the window.
    - `keywords` string[], required
    - `previous_version_id` string, nullable, required
    - `diff` object, nullable, required
      - `headline` object[], required
        - `type` 'same' | 'added' | 'removed', required
        - `text` string, required
      - `description` object[], required
        - `type` 'same' | 'added' | 'removed', required
        - `text` string, required
      - `display_url` object[], required
        - `type` 'same' | 'added' | 'removed', required
        - `text` string, required
  - `total` integer, required
  - `next_cursor` string, nullable, required: Pass as cursor to get the next page; null on the last page.
  - `truncated` boolean, required: Too much copy to compare at once; narrow the selection.
  - `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)