---
title: "Saved checks with the paid ads they found"
method: GET
path: "/projects/{project_id}/observations"
tags: ["Observations"]
---

# Saved checks with the paid ads they found

`GET /projects/{project_id}/observations`

## Request

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

Lists saved monitoring checks, newest first, each with its search context (keyword, engine, device, operating system, country, location, time) and every paid ad it found: position, advertiser domain, title, description, display URL and destination URL as observed. A check with an empty ads list found no ads. An observation shows an ad was displayed for that search at that moment; it is not proof of a purchased keyword, spend or infringement. Filters combine with OR within a dimension and AND across dimensions. Defaults to the last 30 days.

## 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

- `keyword_id` string: Only this keyword's checks.
- `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[]
- `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`

Saved checks with the paid ads they found

- object
  - `data` object[], required
    - `id` string, required
    - `keyword` string, required
    - `keyword_id` string, nullable, required: Null when the keyword was removed later.
    - `observed_at` string, required
    - `engine` 'google' | 'bing', required
    - `device` 'desktop' | 'mobile', required
    - `os` 'windows' | 'macos' | 'android' | 'ios', nullable, required
    - `country` string, required
    - `location` object, required
      - `key` string, required: The value to pass as the location filter.
      - `code` integer, nullable, required
      - `name` string, nullable, required
    - `ads_count` integer, required
    - `ads` object[], required
      - `position` integer, required: Paid slot on the page, 1 is the first ad.
      - `advertiser_domain` string, required: Domain shown for the ad; not a verified identity.
      - `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
  - `next_cursor` string, nullable, required: Pass as cursor to get the next page; null on the last page.
  - `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)