---
title: "Chart-ready paid-search and Shopping aggregates for one project"
method: GET
path: "/projects/{project_id}/analytics"
tags: ["Reports"]
---

# Chart-ready paid-search and Shopping aggregates for one project

`GET /projects/{project_id}/analytics`

## Request

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

Returns chart-ready aggregates for one authorized project and date window, using the same observation filters as the app. Use these metrics to find changes in monitored search results, then inspect the matching observations before drawing a conclusion. Paid-search charts include saved checks and eligible imported studies; studies are excluded when engine or ISO-country filters are selected because they do not record those dimensions. Shopping aggregates are null when the account's plan does not include Shopping. Counts are grouped before any chart display limit; unavailable dimensions are omitted rather than represented as zero. Connected Google Ads and Search Console reports are separate live data and are not historical chart inputs. The window defaults to the last 30 days in the person's time zone.

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

## Response `200`

Chart-ready paid-search and Shopping aggregates for one project

- object
  - `project` object, required
    - `id` string, required
    - `name` string, required
  - `data_state` 'no_observations' | 'no_ads' | 'ads_found', required
  - `observations` integer, required
  - `ads_observed` integer, required
  - `advertiser_domains` integer, required
  - `active_keywords` integer, required: Keywords currently monitored for paid search in this project; this count is independent of the selected date window and observation filters.
  - `imported_studies` object, required
    - `available` boolean, required
    - `included` boolean, required
    - `observations` integer, required
  - `analytics` object, required
    - `byDate` object[], required
      - `date` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byEngine` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byCountry` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byDevice` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byOperatingSystem` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byLocation` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byKeyword` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byAdvertiser` object[], required
      - `label` string, required
      - `checks` integer, required
      - `ads` integer, required
      - `advertisers` integer, required
    - `byPosition` object[], required
      - `label` string, required
      - `count` integer, required
    - `checkOutcomes` object[], required
      - `label` string, required
      - `count` integer, required
    - `adsPerCheck` object[], required
      - `label` string, required
      - `count` integer, required
    - `advertisersPerKeyword` object[], required
      - `label` string, required
      - `count` integer, required
  - `shopping` object, nullable, required: Null when the account plan does not include Shopping.
    - `captures` integer, required
    - `unavailable` integer, required
    - `captured` integer, required
    - `products` integer, required
    - `state` 'no_data' | 'unavailable' | 'no_products' | 'available', required
    - `outcomes` object[], required
      - `label` string, required
      - `count` integer, required
    - `byMerchant` object[], required
      - `label` string, required
      - `count` integer, required
    - `byPosition` object[], required
      - `label` string, required
      - `count` integer, required
    - `byLanguage` object[], required
      - `label` string, required
      - `count` integer, required
    - `byKeyword` object[], required
      - `label` string, required
      - `count` integer, required
    - `byDate` object[], required
      - `date` string, required
      - `captures` integer, required
      - `unavailable` integer, required
      - `products` 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)