---
title: "Choose which properties to pull"
method: PATCH
path: "/v1/gsc/properties"
tags: ["Search Console"]
---

# Choose which properties to pull

`PATCH /v1/gsc/properties`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/gsc/properties`
- Auth: HTTP bearer

Set which properties the nightly pull keeps current. Selecting a property that has never been pulled queues an immediate first pull: the response returns at once with its additive `pull_state`, and a bounded background task imports the last 180 days (or a larger configured backfill) for your account only. The queue is durable — a five-minute recovery sweep finishes anything the background task does not, and the token-free selection write means repeat submissions never reset a queued, running, failed or completed job, its retry timer or its fixed window. A `failed` job is retried only after an explicit Google reconnect, never by resubmitting the same selection. A missing Google configuration does not discard the queue or report the import complete. Requires the customer key's `read` scope; a revoked connection is refused with `reconnect_required` until it is reconnected, and the response is `private, no-store`. Unknown properties are refused; the daily read contract is unchanged.

## Request body

- object
  - `selected` string[], required: The exact property names to keep selected. Properties not listed are deselected; their stored rows are kept.

## Response `200`

OK

- object
  - `properties` object[]
    - `property` string, required: Exactly as Google names it: `sc-domain:example.com` or `https://www.example.com/`.
    - `permission_level` string, nullable, required: siteOwner | siteFullUser | siteRestrictedUser | siteUnverifiedUser, or null.
    - `selected` boolean, required: Whether the nightly pull keeps this property current.
    - `pulled_through` string, date, nullable, required: Last day actually pulled, or null.
    - `last_pull_at` string, date-time, nullable, required: Most recent pull attempt, which may have failed; null if never.
    - `last_error` string, nullable, required: Error from the most recent attempt, or null. Immediate first pulls use short error codes.
    - `pull_state` 'queued' | 'running' | 'done' | 'failed' | 'null', nullable, required: Additive immediate-first-pull state. `queued`/`running`: an immediate import is pending or in progress. `done`: the requested window was processed under Google's existing row caps — not a complete Google total. `failed`: terminal permission/revocation outcome. null: unselected or never requested. A property pulled before the queue existed derives `done` from `pulled_through` when it has no queue state of its own.
  - `selected` string[]: The selected property names, in the same order as `properties`.
  - `next` string: A short hint about what happens next; wording is not part of the contract.

## Other responses

- `400`: `bad_request` for a malformed body; `unknown_property` when a name is not visible to this connection.
- `401`: `unauthorized`, or `reconnect_required` when the stored connection has been revoked and must be reconnected before work can be queued.
- `403`: `insufficient_scope` when the key lacks the `read` scope.
- `404`: `not_connected`: no Google connection for this account.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)