---
title: "When and where one advertiser appeared, with the observation schedule"
method: GET
path: "/projects/{project_id}/advertisers/{domain}/history"
tags: ["Reports"]
---

# When and where one advertiser appeared, with the observation schedule

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

## Request

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

Returns one advertiser domain's history on the project's monitored searches in the window and filters: presence (checks with the advertiser / checks), first and last seen, active local days, the observation schedule (project frequency, checks, days with checks, longest wait between checks), weekly presence by local week, breakdowns by keyword, location, device and engine with the change between the two halves of the window, and returns (reappearances more than gap_days after the previous one, with checks in between that did not show it). Use the breakdowns to locate where an advertiser recurs and the returns section to review reappearances. Check the schedule and days with checks before treating a presence change as a trend; the rate describes saved checks, not all searches in the market. A change is null when either half has no checks. presence_rate = checks_with_advertiser / checks over saved monitoring checks, the same calculation as visibility in list_advertisers. It describes this sample, not impression share, spend, or proof that a keyword was bought. Hours or days without checks are not evidence of absence. Breakdown lists hold the 50 busiest rows each; *_total gives the full count. Imported studies are not included.

## 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.
- `gap_days` integer: Minimum days away for a return: 3, 7, 14, 30.

## Response `200`

When and where one advertiser appeared, with the observation schedule

- object
  - `domain` string, required
  - `keyword` string, nullable, required
  - `presence` object, required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
  - `first_seen` string, nullable, required
  - `last_seen` string, nullable, required
  - `first_seen_any_date` string, nullable, required: Earliest saved check with the advertiser before the window end, same filters.
  - `active_days` integer, required: Local days with at least one check showing it.
  - `schedule` object, required
    - `frequency` string, required: The project's configured monitoring schedule.
    - `runs_per_day` integer, required
    - `checks` integer, required
    - `days_with_checks` integer, required
    - `days_in_window` integer, required
    - `largest_gap_hours` number, nullable, required
  - `weekly` object[], required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `week` string, required: Monday, YYYY-MM-DD.
  - `keywords` object[], required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `key` string, required: Filter value: keyword text, location key, device or engine.
    - `label` string, required
    - `country` string, nullable, required
    - `last_seen` string, nullable, required
    - `earlier_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `later_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `change` number, nullable, required: later_half.presence_rate − earlier_half.presence_rate; null when a half had no checks.
  - `keywords_total` integer, required
  - `markets` object[], required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `key` string, required: Filter value: keyword text, location key, device or engine.
    - `label` string, required
    - `country` string, nullable, required
    - `last_seen` string, nullable, required
    - `earlier_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `later_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `change` number, nullable, required: later_half.presence_rate − earlier_half.presence_rate; null when a half had no checks.
  - `markets_total` integer, required
  - `devices` object[], required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `key` string, required: Filter value: keyword text, location key, device or engine.
    - `label` string, required
    - `country` string, nullable, required
    - `last_seen` string, nullable, required
    - `earlier_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `later_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `change` number, nullable, required: later_half.presence_rate − earlier_half.presence_rate; null when a half had no checks.
  - `engines` object[], required
    - `checks` integer, required: Saved monitoring checks in the group: the denominator.
    - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
    - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
    - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `key` string, required: Filter value: keyword text, location key, device or engine.
    - `label` string, required
    - `country` string, nullable, required
    - `last_seen` string, nullable, required
    - `earlier_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `later_half` object, required
      - `checks` integer, required: Saved monitoring checks in the group: the denominator.
      - `checks_with_advertiser` integer, required: Checks where the advertiser showed at least one ad: the numerator.
      - `ads` integer, required: Paid ad occurrences; one check can hold more than one.
      - `presence_rate` number, nullable, required: checks_with_advertiser / checks, 0 to 1; null when the group had no checks.
    - `change` number, nullable, required: later_half.presence_rate − earlier_half.presence_rate; null when a half had no checks.
  - `returns` object, required
    - `gap_days` integer, required
    - `total` integer, required
    - `items` object[], required
      - `last_seen_before` string, required
      - `returned_at` string, required
      - `days_away` number, required
      - `checks_without_advertiser` integer, required
  - `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)