---
title: "Forecast the monthly checks and allowance for a proposed change"
method: POST
path: "/check-demand"
tags: ["Projects"]
---

# Forecast the monthly checks and allowance for a proposed change

`POST /check-demand`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/check-demand`
- Auth: HTTP bearer

Previews, without saving anything, whether a proposed configuration fits the account's plan, with the same calculation the New project, Edit monitoring plan and Add keywords forms and the server use. Compare the proposed keyword, location, device and search-engine coverage with the account's full-month check allowance before choosing a monitoring plan. change=new_project needs country and keywords (other fields default as in create_project); change=update_project needs project_id plus the fields to change, as in update_project; change=add_keywords needs project_id and keywords (country and language default to the project's). One check is one search: keyword × location × device × source (Google, Bing, Shopping); a project that checks only some of its locations per run counts locations_per_run. scheduled_checks.full_month is account-wide for a 31-day month; the plan must cover both it and projected_this_month. Periods are UTC months. Use it to explain projected check usage and plan fit before calling create_project, update_project or add_keywords.

## Request body

- object
  - `change` 'new_project' | 'update_project' | 'add_keywords', required: What to preview.
  - `project_id` string: Required for update_project and add_keywords.
  - `name` string: Project name, such as Nike US.
  - `country` string: Market, ISO 3166-1 alpha-2 such as US. Changing it without locations monitors the whole new country.
  - `language` string: Search language, such as en.
  - `locations` object[]: The full list of locations inside the country, replacing the current list. Use search_locations to find codes. The plan limits how many the list may hold (location_pool_per_project in get_monitoring_options) and how many each run checks (locations_per_project).
    - `code` integer, required: Location code from search_locations.
    - `name` string, required
  - `locations_per_run` integer, nullable: How many of the listed locations each run checks, least recently checked first, so the whole list is covered over time. null, or a number at or above the list size, checks every location in every run. Counts against the plan's locations_per_project and the check forecast. Omit to keep the current value.
  - `randomize_check_times` boolean: Start each scheduled run at a random moment inside its interval (for Every hour, once in each UTC hour). It never runs more often than the fixed schedule and uses the same checks. Omit to keep the current value.
  - `devices` string[]: The full list of devices to check.
  - `search_engines` string[]: The full list of search engines. May be empty only when shopping_enabled is true. The market must offer each engine (get_monitoring_options).
  - `shopping_enabled` boolean: Also check Google Shopping ads. Needs a plan that includes Shopping and a market with Google.
  - `monitoring_frequency` 'manual' | 'daily' | 'twice_daily' | 'four_times_daily' | 'six_times_daily' | 'twelve_times_daily' | 'hourly' | 'every_30_minutes' | 'every_15_minutes': How often scheduled checks run, from daily to every_15_minutes. manual pauses scheduled monitoring (on-demand checks still work); any other value resumes it. The plan limits the most frequent schedule (allowed_on_plan in get_monitoring_options), and the account's full-month forecast must fit its scheduled check allowance.
  - `keywords` string[]: Search terms, up to 20, such as nike running shoes.

## Response `200`

Forecast the monthly checks and allowance for a proposed change

- object
  - `fits` boolean, required: True when the account's plan can carry the change: projects, keywords, full-month scheduled checks and any first run.
  - `blocked_reason` string, nullable, required: Why it does not fit, as the app would say it; null when it fits.
  - `period` string, required: Usage month, YYYY-MM in UTC.
  - `scheduled_checks` object, required
    - `full_month` integer, required: Scheduled checks the whole account would need in a 31-day month with this change: sum over projects of keywords × locations checked per run × devices × sources × runs per day × 31.
    - `projected_this_month` integer, required: Scheduled checks already used this month plus those still due before the month ends (UTC).
    - `monthly_limit` integer, required
  - `first_run_checks` integer, required: On-demand checks a new project's first run would use (keywords × locations checked per run × devices × sources). 0 for other changes.
  - `realtime_remaining` integer, required: On-demand checks left this month.
  - `keywords` object, required
    - `activated_this_month` integer, required: Distinct keyword, country and language identities used this month, including removed ones, plus the new keywords.
    - `monthly_limit` integer, required
  - `trial` object, nullable, required: Trial allowances when the account is on a trial; null otherwise.
    - `ends_at` string, nullable, required
    - `scheduled_remaining` integer, nullable, required
    - `realtime_remaining` integer, nullable, required
  - `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)