---
title: "Create a project and start its first checks"
method: POST
path: "/projects"
tags: ["Projects"]
---

# Create a project and start its first checks

`POST /projects`

## Request

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

Creates a project for one brand with the supplied default market and immediately queues its first checks, which use the on-demand allowance: keywords × locations checked per run × devices × search engines. Random check times are on unless randomize_check_times is false. The initial keywords use that market; later keyword batches can use another country and language. Plan limits on projects, keywords, locations and schedule apply, exactly as in the app. Requires the write scope and an idempotency key; repeating the key returns the same project without new checks. Confirm the details with the user before calling.

## Headers

- `Idempotency-Key` string, required: A unique value you choose for this request, such as a UUID. Repeating the same key returns the first result instead of starting paid work again.

## Request body

- object
  - `name` string, required: Project name, such as Nike US.
  - `brand_name` string, required: The brand to monitor, such as Nike.
  - `brand_domains` string[], required: The brand's own domains. The first is the primary domain; ads from them count as yours.
  - `country` string, required: Market to monitor, ISO 3166-1 alpha-2, such as US.
  - `language` string: Search language, such as en.
  - `locations` object[]: Locations inside the country, by location code. Omit to monitor the whole country. The plan limits how many the list may hold and how many each run checks (get_monitoring_options).
    - `code` integer, required
    - `name` string, required
  - `locations_per_run` integer, nullable: How many of the locations each run checks, least recently checked first. null (the default) checks every location in every run.
  - `devices` string[]
  - `search_engines` string[]
  - `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. The plan limits the most frequent schedule, and the full-month forecast must fit the scheduled check allowance.
  - `randomize_check_times` boolean: Start each scheduled run at a random moment inside its interval. On by default; it never runs more often than the schedule.
  - `keywords` string[], required: Search terms to monitor, such as nike running shoes.

## Response `201`

Create a project and start its first checks

- object
  - `created` boolean, required
  - `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:<n>.
      - `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)