---
title: "Checks, ads and advertisers by local day, week or month"
method: GET
path: "/projects/{project_id}/timeseries"
tags: ["Reports"]
---

# Checks, ads and advertisers by local day, week or month

`GET /projects/{project_id}/timeseries`

## Request

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

Returns one row per local day, week (starting Monday) or month with saved monitoring checks, in the person's time zone or time_zone: checks_saved, ads_observed (ad occurrences) and advertiser_domains (distinct domains in that period). A period without saved checks is absent: nothing was measured, which is not the same as zero ads. Pass advertiser to add that domain's visibility per period = checks where it showed at least one ad / checks_saved; it is not impression share. Compare like-for-like windows and filters, and check changes in checks_saved before attributing a change in observed presence to the market. Imported studies are not included, as on the Overview chart. The default granularity matches the Overview chart: days, or months for windows longer than 62 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

- `granularity` 'day' | 'week' | 'month': Period length. Defaults to day, or month for windows longer than 62 days.
- `advertiser` string: Advertiser domain as it appears in list_advertisers, such as rival.example.
- `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`

Checks, ads and advertisers by local day, week or month

- object
  - `granularity` 'day' | 'week' | 'month', required
  - `advertiser` string, nullable, required
  - `data` object[], required
    - `period` string, required: YYYY-MM-DD for a day or the Monday that starts a week; YYYY-MM for a month.
    - `checks_saved` integer, required
    - `ads_observed` integer, required
    - `advertiser_domains` integer, required
    - `advertiser_checks_with_ads` integer, nullable, required: Checks where the requested advertiser showed an ad; null without advertiser.
    - `advertiser_visibility` number, nullable, required: advertiser_checks_with_ads / checks_saved; null without advertiser.
  - `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)