API docs v1
PATCH /v1/reports/{report_id}/markets/{market_id}

Update a report's market

scope write:markets cost 1 RU idempotent optional

Change a market's label, what {location} becomes in its prompts (location_text, or its other name prompt_city_text), its language or AI platforms, move it to another place (place_id), its city's region and centre (latitude, longitude), link one of the brand's places (location_id), or pause, resume or archive it (status). A market is never deleted: its results stay.

Path parameters

Query parameters

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Header parameters

  • Idempotency-Key string optional

    Optional. A retry with the same key and body within 24 hours replays the first response.

Request body

application/json required
Type: MarketUpdate
  • ai_platforms array of enum (nullable) nullable
  • label string (nullable) nullable
  • language string (nullable) nullable
  • latitude number (nullable) nullable

    The city's centre, with longitude.

  • location_id string (nullable) nullable
  • location_text string (nullable) nullable

    What {location} becomes in its prompts; null uses the place's name. location_text and prompt_city_text are two names of the same value: send either (both only with the same text).

  • longitude number (nullable) nullable
  • place_id string (nullable) nullable

    Move it to a Google place from POST /v1/place-resolutions.

  • prompt_city_text string (nullable) nullable

    What {location} becomes in its prompts; null uses the place's name. location_text and prompt_city_text are two names of the same value: send either (both only with the same text).

  • region string (nullable) nullable

    The city's state or province.

  • status enum (nullable) nullable
Example payload 
{
  "status": "paused"
}

Responses

Updated a report's market application/json
Type: Market
  • active_prompts_count integer required

    Active prompts it asks: the report's shared ones and its own.

    min: 0

  • country string required
  • created_at string required

    format: `date-time`

  • id string required

    The market; a report's market_id, and a region config's id when scheduled.

  • name string required

    Its label, else its place's name, its city or its country.

  • place_key string required

    country|city lowercased: the place filter of the reader endpoints. country|city|region for a town of a name the country shares that is not the one the bare name is measured as (australia|emerald|victoria beside australia|emerald, which is Emerald, Queensland), so both can be measured.

  • status enum required

    paused and archived markets are skipped by later runs.

  • tracker_id string required

    The tracker (the report's definition) it belongs to.

  • ai_platforms array of string (nullable) nullable

    Null asks the report's AI platforms.

  • city string (nullable) nullable

    Null measures the whole country.

  • country_code string (nullable) nullable

    ISO 3166-1 alpha-2 of country.

  • label string (nullable) nullable
  • language string (nullable) nullable

    Null asks in the report's language.

  • latitude number (nullable) nullable

    The city's centre, when known (a linked place's own coordinates win on runs).

  • location_id string (nullable) nullable

    The brand's place it measures, when linked.

  • location_text string (nullable) nullable

    What {location} becomes in its prompts when set; null uses the place's name in the market's language, else city, else its place's city, else country (a whole country market). A whole country market asked in a language other than English gets its country as that language writes it (México in Spanish) unless one is set, and it follows a change of its country or language. prompt_city_text is another name of the same value.

  • longitude number (nullable) nullable
  • measured_as string (nullable) nullable

    Set when the city has no region and the country has other towns of that name: the town it is measured as, e.g. Emerald, Queensland. Null otherwise.

  • namesake_regions array of string (nullable) nullable

    With measured_as: the states or provinces of the country's other towns of that name. Set region on the market (PATCH) to measure one of them.

  • object string

    Always market.

    default: `market`

  • place_id string (nullable) nullable

    The Google place id of the place it measures (from POST /v1/place-resolutions), when it was added on one; null for a whole country or a market added by city name.

  • prompt_city_text string (nullable) nullable

    Another name of location_text: always the same value.

  • prompts_waiting_for_city integer

    Of those, the ones that name {location} while the market has no place (no city, no location_text and a place without an address): they are not asked until it has one. A schedule whose every prompt waits is paused and resumes by itself.

    min: 0 · default: `0`

  • region string (nullable) nullable

    The city's state or province, when known.

Example response 
{
  "active_prompts_count": 12,
  "city": "Austin",
  "country": "United States",
  "country_code": "US",
  "created_at": "2026-10-20T10:00:00+00:00",
  "id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04",
  "latitude": 30.2672,
  "location_id": "5c1e2f3a-4b5c-4d6e-8f70-112233445566",
  "longitude": -97.7431,
  "name": "Austin",
  "object": "market",
  "place_id": "ChIJLwPMoJm1RIYRetVp1EtGm10",
  "place_key": "united states|austin",
  "region": "Texas",
  "status": "active",
  "tracker_id": "8a72d9f1-c4b5-4e6d-9b1f-0e3a2c6d8b04"
}
Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Request body did not match the expected schema application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}