---
updatedAt: 2026-10-21T02:38:48.000Z
agentTools:
  projectIndex: https://developers.jasper.ai/llms.txt
---

# Create a GEO analysis

Returns `201` with the new analysis. `metadata.credits.cost` quotes the first run.

Queries bill on every run, per provider, so later re-runs of the same settings cost the same.

A network-level retry can otherwise create and bill a second analysis with no way to detect it. Send an `Idempotency-Key` to make retries safe.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "paths": {
    "/v1/geo/analyses": {
      "post": {
        "description": "Returns `201` with the new analysis. `metadata.credits.cost` quotes the first run.\n\nQueries bill on every run, per provider, so later re-runs of the same settings cost the same.\n\nA network-level retry can otherwise create and bill a second analysis with no way to detect it. Send an `Idempotency-Key` to make retries safe.",
        "operationId": "createAnalysis",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "required": false,
            "in": "header",
            "description": "Your id for this create request. A retry with the same key and the same body returns the original response without creating or billing anything new. The same key with a different body is rejected with a 409. Omit it and each call is treated as a distinct create, so a retry after a dropped response can create a second analysis.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGeoAnalysisBodyDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeoAnalysisCreatedResponseDto"
                }
              }
            }
          },
          "402": {
            "description": "Not enough credits for the first run."
          },
          "403": {
            "description": "Not permitted, or not entitled to the requested `schedule` or `region`."
          },
          "409": {
            "description": "The `Idempotency-Key` was already used with a different request body."
          }
        },
        "security": [
          {
            "X-API-Key": []
          },
          {
            "oauth2": [
              "user"
            ]
          }
        ],
        "summary": "Create a GEO analysis",
        "tags": [
          "GEO"
        ]
      }
    }
  },
  "info": {
    "title": "Jasper API",
    "description": "Jasper API",
    "version": "1.0",
    "contact": {}
  },
  "tags": [
    {
      "name": "GEO",
      "description": ""
    }
  ],
  "servers": [
    {
      "url": "https://api.jasper.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Workspace authentication using API key tokens in the X-API-Key header."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.jasper.ai/oauth2/authorize",
            "tokenUrl": "https://api.jasper.ai/oauth2/token",
            "refreshUrl": "https://api.jasper.ai/oauth2/token",
            "scopes": {
              "user:read": "Read user information",
              "user": "Read and write user information"
            }
          }
        },
        "description": "User-level authentication using OAuth bearer tokens in the Authorization header."
      }
    },
    "schemas": {
      "GeoAnalysisActiveStatusDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "active"
            ],
            "example": "active"
          }
        },
        "required": [
          "type"
        ]
      },
      "GeoAnalysisPausedStatusDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "paused"
            ],
            "example": "paused"
          },
          "reason": {
            "type": "string",
            "enum": [
              "insufficient_credits",
              "user_requested"
            ],
            "description": "Why updates are paused. Only `user_requested` carries `pausedAt` and `pausedBy`.",
            "example": "user_requested"
          },
          "pausedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp. Present when reason is `user_requested`."
          },
          "pausedBy": {
            "type": "string",
            "description": "ID of the user who paused. Present when reason is `user_requested`."
          }
        },
        "required": [
          "type",
          "reason"
        ]
      },
      "GeoRunSummaryDto": {
        "type": "object",
        "properties": {
          "runId": {
            "type": "string",
            "example": "aga_ABC123"
          },
          "configId": {
            "type": "string",
            "example": "agc_ABC123",
            "description": "Present on the run history listing. Omitted from an analysis’s `latestRun`, which is already nested under it."
          },
          "runDate": {
            "type": "string",
            "description": "Calendar date the run reports on, in the analysis timezone. Not an instant.",
            "example": "2026-09-08"
          },
          "createdAt": {
            "type": "string",
            "description": "ISO 8601 timestamp",
            "example": "2026-09-08T04:02:11.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "ISO 8601 timestamp",
            "example": "2026-09-08T04:12:07.000Z"
          }
        },
        "required": [
          "runId",
          "runDate",
          "createdAt",
          "updatedAt"
        ]
      },
      "CreateGeoCompetitorDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Acme",
            "description": "Display name. Resolved from the website when omitted."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://acme.example.com"
          }
        },
        "required": [
          "url"
        ]
      },
      "CreateGeoScopeDto": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "internal",
              "external"
            ],
            "example": "internal"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://www.jasper.ai"
          },
          "match": {
            "type": "string",
            "enum": [
              "page",
              "path_prefix",
              "hostname",
              "hostname_and_subdomains"
            ],
            "description": "How `url` is matched, as on the analysis `settings.scopes`. An `external` scope only accepts `page`.",
            "example": "hostname"
          }
        },
        "required": [
          "kind",
          "url",
          "match"
        ]
      },
      "CreateGeoPromptSourceDto": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://www.jasper.ai/pricing"
          }
        },
        "required": [
          "url"
        ]
      },
      "CreateGeoPromptDto": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "example": "What is the best AI writing assistant for marketing teams?"
          },
          "sources": {
            "description": "Pages you expect AI answers to cite for this prompt. Each must fall within `scopes`.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateGeoPromptSourceDto"
            }
          }
        },
        "required": [
          "prompt"
        ]
      },
      "CreateGeoTopicClusterDto": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string",
            "example": "AI writing assistants"
          },
          "prompts": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateGeoPromptDto"
            }
          }
        },
        "required": [
          "topic",
          "prompts"
        ]
      },
      "CreateGeoAnalysisBodyDto": {
        "type": "object",
        "properties": {
          "competitors": {
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateGeoCompetitorDto"
            }
          },
          "providers": {
            "type": "array",
            "minItems": 1,
            "description": "AI providers to query.",
            "items": {
              "type": "string",
              "enum": [
                "chatgpt",
                "gemini",
                "claude",
                "perplexity"
              ]
            }
          },
          "scopes": {
            "minItems": 1,
            "maxItems": 10,
            "description": "What the analysis may cover. At least one must be `internal`; the analysis website is derived from them.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateGeoScopeDto"
            }
          },
          "topicClusters": {
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreateGeoTopicClusterDto"
            }
          },
          "label": {
            "type": "string",
            "example": "Jasper",
            "description": "Resolved from the website when omitted."
          },
          "timezone": {
            "type": "string",
            "example": "America/New_York",
            "description": "IANA timezone."
          },
          "schedule": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "one-off"
            ],
            "description": "How often the analysis re-runs. `one-off` requires an entitlement."
          },
          "region": {
            "type": "string",
            "enum": [
              "US",
              "GB",
              "AU",
              "CA",
              "NZ",
              "IE",
              "ZA",
              "HK",
              "AE"
            ],
            "nullable": true,
            "description": "Country market provider web searches are localized to. Omit or `null` for provider defaults. Requires the `aeo-geo-region` entitlement."
          }
        },
        "required": [
          "competitors",
          "providers",
          "scopes",
          "topicClusters",
          "timezone",
          "schedule"
        ]
      },
      "GeoInternalScopeDto": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "internal"
            ],
            "example": "internal"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://www.jasper.ai/pricing"
          },
          "match": {
            "type": "string",
            "enum": [
              "page",
              "path_prefix",
              "hostname",
              "hostname_and_subdomains"
            ],
            "description": "How `url` is matched when deciding whether a page is in scope.\n\n- `page`: only the page `url` points at.\n- `path_prefix`: every page under `url`'s path.\n- `hostname`: every page on `url`'s hostname, excluding subdomains.\n- `hostname_and_subdomains`: every page on `url`'s hostname and any of its subdomains.",
            "example": "page"
          }
        },
        "required": [
          "kind",
          "url",
          "match"
        ]
      },
      "GeoExternalScopeDto": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "external"
            ],
            "example": "external"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://competitor.example.com/pricing"
          },
          "match": {
            "type": "string",
            "enum": [
              "page"
            ],
            "description": "Always `page`: an external scope covers only the page `url` points at.",
            "example": "page"
          }
        },
        "required": [
          "kind",
          "url",
          "match"
        ]
      },
      "GeoCompetitorDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Acme"
          },
          "url": {
            "type": "string",
            "example": "https://acme.example.com"
          }
        },
        "required": [
          "name",
          "url"
        ]
      },
      "GeoTopicClusterSettingDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "b0d1f6b0-1f4a-4a0e-9a3f-2f0c7a5a1c2d"
          },
          "name": {
            "type": "string",
            "example": "AI writing assistants"
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "GeoAnalysisSettingsDto": {
        "type": "object",
        "properties": {
          "pages": {
            "description": "Absolute URLs of the pages the run analysed.",
            "example": [
              "https://www.jasper.ai/",
              "https://www.jasper.ai/pricing"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "competitors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeoCompetitorDto"
            }
          },
          "providers": {
            "type": "array",
            "description": "AI providers the run queried.",
            "items": {
              "type": "string",
              "enum": [
                "chatgpt",
                "gemini",
                "claude",
                "perplexity"
              ]
            }
          },
          "topicClusters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeoTopicClusterSettingDto"
            }
          },
          "scopes": {
            "type": "array",
            "description": "What the analysis is permitted to cover. Distinct from `pages`, which is what it actually analysed.",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GeoInternalScopeDto"
                },
                {
                  "$ref": "#/components/schemas/GeoExternalScopeDto"
                }
              ]
            }
          }
        },
        "required": [
          "pages",
          "competitors",
          "providers",
          "scopes"
        ]
      },
      "GeoCreatedPromptDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated."
          },
          "prompt": {
            "type": "string",
            "example": "What is the best AI writing assistant for marketing teams?"
          }
        },
        "required": [
          "id",
          "prompt"
        ]
      },
      "GeoCreatedTopicClusterDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Server-generated."
          },
          "topic": {
            "type": "string",
            "example": "AI writing assistants"
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeoCreatedPromptDto"
            }
          }
        },
        "required": [
          "id",
          "topic",
          "prompts"
        ]
      },
      "GeoCreditCostDto": {
        "type": "object",
        "properties": {
          "cost": {
            "type": "number",
            "example": 120,
            "description": "Credits on your workspace plan."
          }
        },
        "required": [
          "cost"
        ]
      },
      "GeoCreateMetadataDto": {
        "type": "object",
        "properties": {
          "credits": {
            "description": "Quoted cost of the first run. Omitted when it cannot be determined. Queries bill per provider on every run.",
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoCreditCostDto"
              }
            ]
          }
        }
      },
      "GeoAnalysisCreatedDto": {
        "type": "object",
        "properties": {
          "configId": {
            "type": "string",
            "example": "agc_ABC123"
          },
          "label": {
            "type": "string",
            "example": "Jasper"
          },
          "website": {
            "type": "string",
            "example": "https://www.jasper.ai"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone the schedule and each run analysisDate are anchored to.",
            "example": "America/New_York"
          },
          "region": {
            "type": "string",
            "enum": [
              "US",
              "GB",
              "AU",
              "CA",
              "NZ",
              "IE",
              "ZA",
              "HK",
              "AE"
            ],
            "nullable": true,
            "description": "Country market provider web searches are localized to. `null` means provider defaults.",
            "example": "US"
          },
          "status": {
            "description": "Schedule status. `null` when the analysis has never been scheduled.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/GeoAnalysisActiveStatusDto"
              },
              {
                "$ref": "#/components/schemas/GeoAnalysisPausedStatusDto"
              }
            ],
            "example": {
              "type": "active"
            }
          },
          "latestRun": {
            "description": "Latest completed run, when one exists.",
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoRunSummaryDto"
              }
            ]
          },
          "settings": {
            "description": "Settings the latest completed run used. Omitted when no run has completed.",
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoAnalysisSettingsDto"
              }
            ]
          },
          "schedule": {
            "type": "string",
            "enum": [
              "daily",
              "weekly",
              "monthly",
              "one-off"
            ],
            "example": "weekly"
          },
          "nextScheduledAnalysisAt": {
            "type": "string",
            "nullable": true,
            "description": "ISO 8601 timestamp of the next scheduled run. `null` for a `one-off` analysis, or when unavailable.",
            "example": "2026-10-12T00:00:00.000Z"
          },
          "topicClusters": {
            "description": "The clusters and prompts as created, with their server-generated ids. This is the only place these ids are returned — keep them if you plan to reference these prompts or clusters again, e.g. on an update.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GeoCreatedTopicClusterDto"
            }
          },
          "metadata": {
            "$ref": "#/components/schemas/GeoCreateMetadataDto"
          }
        },
        "required": [
          "configId",
          "label",
          "website",
          "timezone",
          "region",
          "schedule",
          "nextScheduledAnalysisAt",
          "topicClusters"
        ]
      },
      "GeoAnalysisCreatedResponseDto": {
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "example": "8393f82b3f6a4f6e8a405777b9305254"
          },
          "resource": {
            "type": "string",
            "example": "knowledge"
          },
          "data": {
            "$ref": "#/components/schemas/GeoAnalysisCreatedDto"
          }
        },
        "required": [
          "requestId",
          "resource",
          "data"
        ]
      }
    }
  },
  "x-readme": {
    "metrics-enabled": false
  }
}
```