--- title: "Change a project's monitoring plan, brand or affiliate settings" method: PATCH path: "/projects/{project_id}" tags: ["Projects"] --- # Change a project's monitoring plan, brand or affiliate settings `PATCH /projects/{project_id}` ## Request - Base URL: `https://adslighthouse.com/api/v1` - URL: `https://adslighthouse.com/api/v1/projects/{project_id}` - Auth: HTTP bearer Changes any of a project's settings, like Settings > Project: name, market (country and language), locations and how many each run checks (locations_per_run), devices, search engines, Shopping, schedule (monitoring_frequency, from daily to every_15_minutes; manual pauses scheduled monitoring, another value resumes it), random check times (randomize_check_times), brand name and owned domains, and the affiliate URL parameter with its registered affiliate IDs. Omitted fields keep their value; list fields replace the whole list. Coverage changes (keywords × locations checked per run × devices × sources × runs per day) are checked against the plan's limits and the account's full-month scheduled check allowance before they are saved; a change that does not fit returns quota_exceeded with the checks it needs and the allowance, and nothing changes. Call preview_check_demand first to show the user the effect. No check starts now: new coverage applies to the next scheduled runs. Saved observations are never rewritten. Requires the write scope. ## 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. ## Request body - object - `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. - `brand_name` string: The brand to monitor, such as Nike. - `owned_domains` string[]: The full list of the brand's own domains; the first is the primary domain. Ads from these domains and their subdomains count as the brand's own. - `affiliate_parameter` string, nullable: Older single-parameter form: one parameter name, such as affiliate_id, replacing every tracked parameter. null or an empty string turns affiliate identification off. Prefer affiliate_parameters. - `affiliate_parameters` string[]: The full list of tracked affiliate parameters, replacing the current list. Each is a name, such as fpr (any value in the URL is the affiliate ID), or name=value, such as utm_source=partners (only that exact value). An empty list turns affiliate identification off. Do not send full URLs. - `affiliate_ids` object[]: The full list of your registered affiliate IDs, replacing the current list. - `id` string, required: The affiliate ID as it appears in URLs. - `name` string, required: Who the ID belongs to. ## Response `200` Change a project's monitoring plan, brand or affiliate settings - object - `updated` string[], required: Which settings groups were saved. - `project` object, required - `id` string, required - `name` string, required - `brand` object, required - `name` string, required - `domain` string, required - `country` string, required: ISO 3166-1 alpha-2 market code. - `language` string, required - `search_engines` string[], required - `devices` string[], required - `shopping_enabled` boolean, required - `monitoring_frequency` 'manual' | 'daily' | 'twice_daily' | 'four_times_daily' | 'six_times_daily' | 'twelve_times_daily' | 'hourly' | 'every_30_minutes' | 'every_15_minutes', required - `runs_per_day` integer, required - `randomize_check_times` boolean, required: Each scheduled run starts at a random moment inside its interval. - `locations_per_run` integer, nullable, required: Locations each run checks, least recently checked first; null checks every listed location. - `status` 'active' | 'paused', required: active runs scheduled checks; paused is set to manual checks only or has no active keyword, as on the Overview projects table. - `created_at` string, required - `owned_domains` string[], required - `locations` object[], required - `code` integer, required: Location code used by the location filter as code:. - `name` string, required - `keyword_count` integer, required - `active_keyword_count` integer, required - `affiliate_tracking` object, required - `configured` boolean, required: True when at least one affiliate URL parameter is set. - `parameter` string, nullable, required: The first tracked parameter's name. Kept for older clients; read parameters. - `parameters` string[], required: Every tracked rule: a name (fpr, any value is the affiliate ID) or name=value (utm_source=partners, only that exact value). - `registered_ids` integer, required - `data` object, required: What actually has data, so filters can be chosen without guessing. - `observations` integer, required: Saved monitoring checks (search result pages) for this project, all time. - `latest_observation_at` string, nullable, required - `engines` string[], required: Search engines with saved observations. - `devices` string[], required: Devices with saved observations. - `countries` string[], required: Countries with saved observations. - `locations` object[], required: Location filter keys with saved observations. - `key` string, required - `name` string, required - `country` string, 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)