API docs v1
POST /v1/region-configs

Create a region config

scope write:region-configs cost 2 RU idempotent required

Create a region config under a brand. A region config defines a (country, language, location, AI-platforms) target. One report is materialised per region config every time the parent schedule ticks.

scheduled_report_id is required: create the schedule first via POST /v1/scheduled-reports, then pass its id here. Each schedule is capped at 20 region configs.

Returns 404 not_found if the referenced schedule or source report belongs to a different brand.

Header parameters

Request body

application/json required
Type:RegionConfigCreate
  • brand_idstringrequired

    Brand to create the region config under.

  • countrystringrequired

    Country the region targets.

    min length: 1 ยท max length: 100

  • namestringrequired

    Human-readable label.

    min length: 1 ยท max length: 200

  • scheduled_report_idstringrequired

    Schedule to attach this region config to. Required. Create the schedule first via POST /v1/scheduled-reports, then pass its id here.

  • ai_platformsarray of enum

    AI platforms to run against (1-10). Standard tier: chatgpt, perplexity, ai_overviews, claude. Premium tier: chatgpt_search, claude_search, gemini, grok.

    min items: 1 ยท max items: 10

  • is_activeboolean

    Whether the config should run on scheduled executions.

    default: `true`

  • languagestring

    Language. Accepts English name (English, Spanish) or ISO 639-1 code (en, es).

    max length: 50 ยท default: `English`

  • locationstring (nullable)nullable

    Optional sub-region / city.

  • source_report_idstring (nullable)nullable

    Optionally bootstrap the config from an existing report's settings.

Example payload 
{
  "ai_platforms": [
    "chatgpt",
    "perplexity"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "country": "United States",
  "is_active": true,
  "language": "English",
  "location": "New York, NY",
  "name": "United States, English",
  "scheduled_report_id": "018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d"
}

Responses

Region config created.application/json
Type:RegionConfig
  • brand_idstringrequired

    Owning brand id (UUID).

  • countrystringrequired

    Country the region targets.

  • created_atstringrequired

    ISO-8601 timestamp when the region config was created.

    format: `date-time`

  • idstringrequired

    Stable region-config identifier (UUID).

  • is_activebooleanrequired

    Whether the config is used by scheduled runs.

  • languagestringrequired

    Language label (e.g. English, Spanish).

  • namestringrequired

    Human-readable label (e.g. United States, English).

  • scheduled_report_idstringrequired

    Schedule this config feeds. Required: every region config is tied to exactly one schedule (DB column is NOT NULL).

  • ai_platformsarray of string

    AI platforms this region runs against. Standard tier (bundled, 1 credit per prompt total): chatgpt, perplexity, ai_overviews, claude. Premium tier (1 credit per platform per prompt, additive): chatgpt_search, claude_search, gemini, grok.

  • last_error_messagestring (nullable)nullable

    Last error message surfaced by a scheduled run, if any.

  • last_run_atstring (nullable)nullable

    ISO-8601 timestamp of the most recent scheduled run from this config.

    format: `date-time`

  • last_run_statusenum (nullable)nullable

    Status of the most recent run.

  • locationstring (nullable)nullable

    Free-form location string used for queries.

  • objectstring

    Always region_config.

    default: `region_config`

  • prompts_countinteger

    Number of non-disabled prompts attached.

    min: 0 ยท default: `0`

  • source_report_idstring (nullable)nullable

    Original report this config was bootstrapped from, when applicable.

Example response 
{
  "ai_platforms": [
    "chatgpt",
    "perplexity"
  ],
  "brand_id": "3f9c7e8a-1b6a-4d8e-92cf-7d9c8b1e2a04",
  "country": "United States",
  "created_at": "2026-04-01T11:00:00.000Z",
  "id": "018e7c2e-33ab-7df1-b1cd-2ac3a8f9112d",
  "is_active": true,
  "language": "English",
  "last_run_at": "2026-04-19T03:00:00.000Z",
  "last_run_status": "completed",
  "location": "New York, NY",
  "name": "United States, English",
  "object": "region_config",
  "prompts_count": 12,
  "scheduled_report_id": "018e7c2d-33ab-7df1-b1cd-2ac3a8f9112d"
}
Request validation failedapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 credentialsapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 resourceapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 conflictapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 schemaapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 exceededapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 occurredapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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 retryapplication/json
Type:ApiError
  • errorobjectrequired
    Show fields
    • codestringrequired

      Stable machine-readable error code from the catalog.

    • messagestringrequired

      Human-readable description suitable for logging.

    • detailsobject

      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_idstring

    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"
}