---
title: "Update GEO analysis by ID"
method: PATCH
path: "/v1/geo/analyses/{configId}"
tags: ["GEO"]
---

# Update GEO analysis by ID

`PATCH /v1/geo/analyses/{configId}`

## Request

- Base URL: `https://api.jasper.ai`
- URL: `https://api.jasper.ai/v1/geo/analyses/{configId}`
- Auth: one of:
  - API key in header `X-API-Key`
  - OAuth 2
    - Authorization code: `https://api.jasper.ai/oauth2/authorize`
    - Token URL: `https://api.jasper.ai/oauth2/token` scopes: `user`

`label`, `timezone`, `schedule` and `region` are free to change and never start a run.

Sending any of `competitors`, `providers`, `scopes` or `topicClusters` makes it a settings update. Omitted settings fields keep the latest run's values. If the resulting settings are the same as the latest run's, in any order, nothing runs and nothing is charged. Otherwise a new run starts, replacing any run still in progress, and `metadata.credits.cost` quotes it. Pages never bill on an update; queries bill per provider.

`topicClusters` replaces the full set. Send the `id` a previous response returned to keep a cluster or prompt. One without an `id` keeps the current cluster with the same `topic`, or prompt with the same text; otherwise it is new and gets a fresh id. Ids are returned in `topicClusters`.

Updates are idempotent: repeating one that already applied resolves to the same settings, so it starts nothing and charges nothing.

## Path parameters

- `configId` string, required

## Request body

- UpdateGeoAnalysisBodyDto
  - `competitors` CreateGeoCompetitorDto[]
    - `name` string: Display name. Resolved from the website when omitted.
    - `url` string, uri, required
  - `providers` string[]: AI providers to query.
  - `scopes` CreateGeoScopeDto[]: What the analysis may cover. At least one must be `internal`, on the same root domain as the current scopes.
    - `kind` 'internal' | 'external', required
    - `url` string, uri, required
    - `match` 'page' | 'path_prefix' | 'hostname' | 'hostname_and_subdomains', required: How `url` is matched, as on the analysis `settings.scopes`. An `external` scope only accepts `page`.
  - `topicClusters` UpdateGeoTopicClusterDto[]: The full set of topic clusters, replacing the current ones. Keep a cluster or prompt by sending its `id`. One without an `id` keeps the current cluster with the same `topic`, or prompt with the same text; otherwise it is new.
    - `id` string, uuid: The id a previous create or update returned for this cluster. When omitted, the current cluster with the same `topic` is kept, or a new one is created.
    - `topic` string, required
    - `prompts` UpdateGeoPromptDto[], required
      - `id` string, uuid: The id a previous create or update returned for this prompt. When omitted, the current prompt with the same text is kept, or a new one is created.
      - `prompt` string, required
      - `sources` CreateGeoPromptSourceDto[]: Pages you expect AI answers to cite for this prompt. Each must fall within `scopes`. Omit on a prompt with an `id` to keep its current sources.
        - `url` string, uri, required
  - `label` string
  - `timezone` string: IANA timezone.
  - `schedule` 'daily' | 'weekly' | 'monthly' | 'one-off': How often the analysis re-runs. `one-off` requires an entitlement.
  - `region` 'US' | 'GB' | 'AU' | 'CA' | 'NZ' | 'IE' | 'ZA' | 'HK' | 'AE', nullable: Country market provider web searches are localized to. `null` resets to provider defaults. Setting a region requires the `aeo-geo-region` entitlement.

## Response `200`

- GeoAnalysisUpdatedResponseDto
  - `requestId` string, required
  - `resource` string, required
  - `data` GeoAnalysisUpdatedDto, required
    - `configId` string, required
    - `label` string, required
    - `website` string, required
    - `timezone` string, required: IANA timezone the schedule and each run analysisDate are anchored to.
    - `region` 'US' | 'GB' | 'AU' | 'CA' | 'NZ' | 'IE' | 'ZA' | 'HK' | 'AE', nullable, required: Country market provider web searches are localized to. `null` means provider defaults.
    - `status` union: Schedule status. `null` when the analysis has never been scheduled.
      - GeoAnalysisActiveStatusDto
        - `type` 'active', required
      - GeoAnalysisPausedStatusDto
        - `type` 'paused', required
        - `reason` 'insufficient_credits' | 'user_requested', required: Why updates are paused. Only `user_requested` carries `pausedAt` and `pausedBy`.
        - `pausedAt` string: ISO 8601 timestamp. Present when reason is `user_requested`.
        - `pausedBy` string: ID of the user who paused. Present when reason is `user_requested`.
    - `latestRun` GeoRunSummaryDto
      - `runId` string, required
      - `configId` string: Present on the run history listing. Omitted from an analysis’s `latestRun`, which is already nested under it.
      - `runDate` string, required: Calendar date the run reports on, in the analysis timezone. Not an instant.
      - `createdAt` string, required: ISO 8601 timestamp
      - `updatedAt` string, required: ISO 8601 timestamp
    - `schedule` 'daily' | 'weekly' | 'monthly' | 'one-off', required
    - `nextScheduledAnalysisAt` string, nullable, required: ISO 8601 timestamp of the next scheduled run. `null` for a `one-off` analysis, or when unavailable.
    - `runStarted` boolean, required: Whether the update started a new run, cancelling any run still in progress. `false` when only free fields changed, or when the settings came out the same as the latest run.
    - `topicClusters` GeoUpdatedTopicClusterDto[]: The clusters and prompts now configured, with their ids, including ids generated for new ones. Omitted when no settings field was sent.
      - `id` string, uuid, required
      - `topic` string, required
      - `prompts` GeoUpdatedPromptDto[], required
        - `id` string, uuid, required
        - `prompt` string, required
    - `metadata` GeoUpdateMetadataDto
      - `credits` GeoCreditCostDto
        - `cost` number, required: Credits on your workspace plan.

## Other responses

- `402`: Not enough credits for the new run.
- `403`: Not permitted, or not entitled to the requested `schedule` or `region`.
- `404`: Analysis not found.

## Changes

- **2026-11-03** `3d5be7408661`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/jasper/apis/jasper-api/changes/v1/geo/analyses/:configId/patch.md)

---

[API](https://skmtc.dev/jasper/apis/jasper-api.md) - [All operations](https://skmtc.dev/jasper/apis/jasper-api/llms.txt) - [OpenAPI document](https://skmtc.dev/jasper/apis/jasper-api/revisions/3d5be7408661?raw)