Market coverage

The Market Coverage grid as data, computed by the same rules the app uses: one row per prompt family, one cell per market and language, covered or missing. By default only rows with something missing are returned; pass only_missing=false for the whole grid. The prompt_id on each row is what Localize prompts takes.

A prompt row is one wording in one regional locale (en-GB, de-DE), tracked in one or more countries. A family is the set of versions of one question across languages. A market is a country the brand has opened, listing the languages it tracks there. Coverage is the grid Market Coverage draws from those three: one row per family, one cell per market and language, covered or missing.

Requires the read:prompts scope.


GET /v1/brands/{brand_id}/localization/coverage

Authorization

Header	Type	Required
`Authorization`	`Bearer asky_sk_…`	required

Path parameters

Parameter	Type	Required	Description
`brand_id`	`uuid`	required	From List brands

Query parameters

Parameter	Type	Required	Description
`limit`	`integer`	optional	Rows per page, 1 to 100. Defaults to 20
`cursor`	`string`	optional	Opaque cursor from the previous response. Treat it as a token, never construct one
`topic_id`	`uuid`	optional	Restrict to a topic and its subtopics. Includes the topic and its subtopics; a root topic returns everything beneath it
`country_code`	`string`	optional	Restrict the columns to one market, e.g. `DE`
`locale_code`	`string`	optional	Restrict the columns to one language, e.g. `de-DE`
`only_missing`	`boolean`	optional	Default `true`. `false` returns every family
`search`	`string`	optional	Case-insensitive substring of the wording

Request

cURL


curl --request GET \
  --url 'https://api.askylabs.com/v1/brands/242546de-4cee-4a7d-952e-f6aa60c63ef8/localization/coverage' \
  --header 'Authorization: Bearer <api-key>'

Response

200


{
  "data": {
    "rows": [
      {
        "prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852",
        "prompt_text": "What are the best GEO tools in the US?",
        "locale_code": "en-US",
        "country_codes": [
          "US",
          "DE"
        ],
        "family_id": "3f1d2c9b-6a4e-4b8f-9c2d-1e5a7b3c9d0e",
        "family_size": 2,
        "topic_id": null,
        "markets": [
          {
            "country_code": "DE",
            "country_name": "Germany",
            "cells": [
              {
                "locale_code": "de-DE",
                "status": "missing",
                "version_prompt_id": null
              },
              {
                "locale_code": "en-US",
                "status": "covered",
                "version_prompt_id": "7c2f5a91-3b8e-4d06-9a44-1e7b30c9f852"
              }
            ]
          }
        ],
        "missing": [
          {
            "country_code": "DE",
            "locale_code": "de-DE"
          }
        ],
        "missing_count": 1
      }
    ],
    "total": 1,
    "columns": [
      {
        "country_code": "DE",
        "locale_code": "de-DE"
      },
      {
        "country_code": "DE",
        "locale_code": "en-US"
      }
    ],
    "totals": {
      "families": 120,
      "families_missing": 1,
      "cells_missing": 1
    }
  },
  "pagination": {
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  },
  "request_id": "req_2f7b90c14ae8471da3cd"
}

Response fields

Field	Type	Description
`data.rows[].prompt_id`	`uuid`	required. The family’s source prompt; use it for Localize prompts
`data.rows[].prompt_text`	`string`	required
`data.rows[].locale_code`	`string \	null`
`data.rows[].country_codes`	`string[]`	required
`data.rows[].family_id`	`uuid \	null`
`data.rows[].family_size`	`integer`	required. Versions in the family
`data.rows[].markets[]`	`object[]`	required. One entry per market with `cells[]` of `{ locale_code, status, version_prompt_id }`
`data.rows[].missing`	`object[]`	required. Every missing `{ country_code, locale_code }`
`data.rows[].missing_count`	`integer`	required
`data.total`	`integer`	required. Rows matching before paging
`data.columns`	`object[]`	required. The market and language columns after filters
`data.totals`	`object`	required. `families`, `families_missing`, `cells_missing`

Errors

Status	Code	When
401	`invalid_token`	The key is missing, malformed, or does not exist
403	`insufficient_scope`	The key does not carry `read:prompts`
404	`not_found`	The brand does not exist, or this key is not allowed to reach it
429	`rate_limited`	Over the per-minute limit for this endpoint