Using GEO Analyses

This guide describes how to read GEO visibility data, and manage the analyses behind it, through the Jasper API and the Jasper MCP Server.

GEO analyses track how AI answer engines (ChatGPT, Gemini, Claude and Perplexity) describe and cite your brand. Use the API to pull the same analyses, runs, recommendations and trends that appear in the GEO Hub into your own reporting, or use the MCP tools to ask a connected AI assistant questions like "what are my top 3 GEO recommendations?"

Key concepts

Endpoints

Listing analyses and runs

List your analyses:

curl --request GET \
  --url https://api.jasper.ai/v1/geo/analyses \
  --header 'X-API-KEY: YOUR_API_KEY'

List the completed runs for one analysis, newest first:

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs?from=2026-08-01&to=2026-09-08&limit=20' \
  --header 'X-API-KEY: YOUR_API_KEY'

Getting a run

Get one run. Omit sections to return everything:

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs/aga_ABC123?sections=overview,metrics' \
  --header 'X-API-KEY: YOUR_API_KEY'

sections is a comma-separated list. An unknown value returns 400.

recommendations is paginated. page and limit apply only when it is the only paginated section you request, and the response includes pagination.next for the following page. To filter findings, use the recommendations endpoint below.

Recommendations

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs/aga_ABC123/recommendations?severity=critical,warning&category=missing-faq' \
  --header 'X-API-KEY: YOUR_API_KEY'

The response includes totals per severity and category across every page, so you can see when results are truncated.

Trends and key events

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/trends?range=30d' \
  --header 'X-API-KEY: YOUR_API_KEY'

The response has score deltas and a series over the range, plus key events that help explain why a score moved:

• Analysis settings changed: queries, AI providers, pages or competitors were added or removed.
• Query model changed: a newer model was used when querying an AI provider.
• Page content changed: a meaningful change was found on a tracked page.
• Score methodology changed: the way GEO scores are calculated was updated.

Events start from when the feature was released and are not backfilled. Most events are logged on scheduled runs, so a page change can appear on a slightly later date than the edit itself.

Pagination

Paginated endpoints take page and limit, and return totalRecords, page, pageSize, next and prev. Follow next until it is null.

Creating an analysis

curl --request POST \
  --url https://api.jasper.ai/v1/geo/analyses \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Idempotency-Key: 8d6c2d1e-1f6b-4a0e-9d2b-3c5a7f1e2b44' \
  --header 'content-type: application/json' \
  --data '{
    "providers": ["chatgpt"],
    "scopes": [{ "kind": "internal", "url": "https://www.jasper.ai", "match": "hostname" }],
    "competitors": [{ "name": "Copy.ai", "url": "https://www.copy.ai" }],
    "topicClusters": [
      {
        "topic": "AI marketing tools",
        "prompts": [{ "prompt": "What is the best AI tool for marketing teams?" }]
      }
    ],
    "label": "Jasper",
    "timezone": "Australia/Sydney",
    "schedule": "weekly"
  }'

Creating an analysis queues its first run and returns the new analysis. Example response:

{
  "requestId": "b2ca6fbc-16e1-45b7-be2f-207e89acf377",
  "resource": "geo-analyses",
  "data": {
    "configId": "agc_01a15be81507700080000fa991a2c221",
    "label": "Jasper",
    "website": "https://www.jasper.ai",
    "timezone": "Australia/Sydney",
    "region": null,
    "status": { "type": "active" },
    "schedule": "weekly",
    "nextScheduledAnalysisAt": "2026-10-28T10:19:53.187Z",
    "topicClusters": [
      {
        "id": "0d0f7a04-8562-462f-b1d3-18760d2eced5",
        "topic": "AI marketing tools",
        "prompts": [
          {
            "id": "3bae2e9c-9398-4670-8ec4-5504e75da66a",
            "prompt": "What is the best AI tool for marketing teams?"
          }
        ]
      }
    ],
    "metadata": { "credits": { "cost": 10 } }
  },
  "pagination": null
}

Retrying safely. Send an Idempotency-Key header. A retry with the same key and the same body returns the original response without creating a second analysis or charging again. Reusing a key with a different body returns 409.

Updating and deleting an analysis

Create, update and delete need write access. Read-only tokens receive 403.

curl --request PATCH \
  --url https://api.jasper.ai/v1/geo/analyses/agc_ABC123 \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{ "label": "New label" }'

• Metadata (label, timezone, schedule, region) is applied as sent. No run starts and nothing is charged.
• Settings (scopes, competitors, providers, topicClusters): omitted fields keep their current values. If the result differs from the latest analysis, a new run starts and any run in progress is cancelled. If it is identical, nothing runs and nothing is charged.
• Existing clusters and prompts keep their IDs from earlier responses. Send an ID to edit that item. Leave it out to add a new one.

DELETE /v1/geo/analyses/{configId} returns 204. Deleting stops the schedule and pauses Copilot automations. Afterwards every endpoint for that analysis returns 404. You cannot restore a deleted analysis yourself.

Credits

• Reading is free.
• Creating an analysis, or updating settings so that a new run starts, uses credits. The cost is the number of queries multiplied by the number of providers, and it is charged on every run. Pages are not billed.
• The cost is returned as metadata.credits.cost on create and on an update that starts a run. The same settings cost the same on every run.
• An update that changes no settings returns credits.cost of 0 and analysisId as null. A metadata-only update returns no credits.
• If the workspace does not have enough credits, the update is rejected and nothing is applied, including metadata changes.

Errors

Using GEO with MCP

The Jasper MCP Server exposes four read-only GEO tools. Writes are available through the API only. See Jasper MCP Server to connect a client.

Example: find and review your top issues

Step 1: List your analyses and note the configId of the site you want.

curl --request GET \
  --url https://api.jasper.ai/v1/geo/analyses \
  --header 'X-API-KEY: YOUR_API_KEY'

Step 2: Get the latest run ID from the runs list.

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs?limit=1' \
  --header 'X-API-KEY: YOUR_API_KEY'

Step 3: Pull its critical recommendations.

curl --request GET \
  --url 'https://api.jasper.ai/v1/geo/analyses/agc_ABC123/runs/aga_ABC123/recommendations?severity=critical' \
  --header 'X-API-KEY: YOUR_API_KEY'