JAjasper
GEO

Create a GEO analysis

Changed on

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.

post/v1/geo/analyses

Request

  • Base URL
    https://api.jasper.ai
  • URL
    https://api.jasper.ai/v1/geo/analyses
  • Auth
    • API key in header X-API-Key
    • or OAuth 2
      Authorization code: https://api.jasper.ai/oauth2/authorize
      Token URL: https://api.jasper.ai/oauth2/token scopes: user

Headers

Idempotency-Keystring

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.

Request body

providersstring[] required

AI providers to query.

labelstring

Resolved from the website when omitted.

timezonestring required

IANA timezone.

schedule'daily' | 'weekly' | 'monthly' | 'one-off' required

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. Omit or null for provider defaults. Requires the aeo-geo-region entitlement.

Example request

{
  "competitors": [
    {
      "name": "Acme",
      "url": "https://acme.example.com"
    }
  ],
  "scopes": [
    {
      "kind": "internal",
      "url": "https://www.jasper.ai",
      "match": "hostname"
    }
  ],
  "topicClusters": [
    {
      "topic": "AI writing assistants",
      "prompts": [
        {
          "prompt": "What is the best AI writing assistant for marketing teams?",
          "sources": [
            {
              "url": "https://www.jasper.ai/pricing"
            }
          ]
        }
      ]
    }
  ],
  "label": "Jasper",
  "timezone": "America/New_York"
}

Response

requestIdstring required
resourcestring required

Example response

{
  "requestId": "8393f82b3f6a4f6e8a405777b9305254",
  "resource": "knowledge",
  "data": {
    "configId": "agc_ABC123",
    "label": "Jasper",
    "website": "https://www.jasper.ai",
    "timezone": "America/New_York",
    "region": "US",
    "status": {
      "type": "active"
    },
    "latestRun": {
      "runId": "aga_ABC123",
      "configId": "agc_ABC123",
      "runDate": "2026-09-08",
      "createdAt": "2026-09-08T04:02:11.000Z",
      "updatedAt": "2026-09-08T04:12:07.000Z"
    },
    "settings": {
      "pages": [
        "https://www.jasper.ai/",
        "https://www.jasper.ai/pricing"
      ],
      "competitors": [
        {
          "name": "Acme",
          "url": "https://acme.example.com"
        }
      ],
      "topicClusters": [
        {
          "id": "b0d1f6b0-1f4a-4a0e-9a3f-2f0c7a5a1c2d",
          "name": "AI writing assistants"
        }
      ],
      "scopes": [
        {
          "kind": "internal",
          "url": "https://www.jasper.ai/pricing",
          "match": "page"
        }
      ]
    },
    "schedule": "weekly",
    "nextScheduledAnalysisAt": "2026-10-12T00:00:00.000Z",
    "topicClusters": [
      {
        "topic": "AI writing assistants",
        "prompts": [
          {
            "prompt": "What is the best AI writing assistant for marketing teams?"
          }
        ]
      }
    ],
    "metadata": {
      "credits": {
        "cost": 120
      }
    }
  }
}

Changes