GeoGenee API — Documentation

The GeoGenee REST API gives you access to your visibility data in generative AI engines (scores, technical GEO audits, competitors, sources) and lets you trigger analyses on demand. It is available on all accounts. This page documents every endpoint with a full response example.

1. Authentication

Generate an API key in Settings → API & developers. The key (gg_live_… format) is only shown once. Send it with every request:

curl https://api-geo.genee.tech/api/v1/me \
  -H "Authorization: Bearer gg_live_VOTRE_CLE"

Alternative: header X-API-Key: gg_live_….

2. Base URL

https://api-geo.genee.tech/api/v1

All responses are JSON (UTF-8). Dates use the ISO 8601 format (UTC).

3. Endpoints

Account & usage

GET/me

Your account, your effective limits (plan + overrides) and your consumption for the month.

Response codes

200Success
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "email": "vous@exemple.fr",
  "plan": "pro",
  "limits": {
    "max_sites": 1,
    "max_tracked_prompts": 30,
    "max_competitors": 10,
    "ai_runs_per_month": 3000,
    "history_days": 365,
    "audit_pages": 100
  },
  "usage": {
    "sites": { "used": 1, "limit": 1, "remaining": 0 },
    "ai_runs_month": {
      "used": 420, "limit": 3000, "remaining": 2580, "bonus_credits": 0
    }
  }
}

GET/usage

Same as the "usage" part of /me: quota and consumption, remaining bonus AI credits.

Response codes

200Success
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "plan": "pro",
  "limits": { "max_sites": 1, "ai_runs_per_month": 3000, "...": "..." },
  "usage": {
    "sites": { "used": 1, "limit": 1, "remaining": 0 },
    "ai_runs_month": {
      "used": 420, "limit": 3000, "remaining": 2580, "bonus_credits": 0
    }
  }
}

Sites

GET/sites

The list of your tracked sites.

Response codes

200Success
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "data": [
    {
      "id": "site_8f2…",
      "url": "https://exemple.fr",
      "label": "Exemple",
      "is_active": true,
      "created_at": "2026-06-01T10:00:00+00:00"
    }
  ]
}

Technical GEO audit

POST/sites/{id}/audit/run

Runs a GEO audit of the homepage and returns the result (synchronous).

Returns 201 Created.

Response codes

201Audit created and returned
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (201)

{
  "data": {
    "total": 78,
    "grade": "B",
    "final_url": "https://exemple.fr/",
    "checks": {
      "schema": { "score": 10, "max": 15, "label": "Données structurées" },
      "llms": { "score": 0, "max": 10, "label": "llms.txt" },
      "...": "..."
    },
    "created_at": "2026-06-21T12:00:00+00:00"
  }
}

GET/sites/{id}/audit

Latest technical GEO audit. Returns data: null if no audit exists.

Response codes

200Success
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "data": {
    "total": 78,
    "grade": "B",
    "final_url": "https://exemple.fr/",
    "checks": { "schema": { "score": 10, "max": 15 }, "...": "..." },
    "created_at": "2026-06-21T12:00:00+00:00"
  }
}

AI visibility

POST/sites/{id}/visibility/run

Runs an AI analysis of all the site's tracked questions (asynchronous, queued).

Returns 202 Accepted. Consumes the monthly AI-run quota (plan + bonus credits).

Response codes

202Analysis accepted (queued, asynchronous)
403Monthly AI-run quota reached
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (202)

{
  "queued": true,
  "mode": "rq"
}

GET/sites/{id}/visibility

AI visibility summary: KPIs, per engine, per theme/city, competitor ranking, sentiment, sources, recent citations.

Response codes

200Success
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "kpis": {
    "citation_rate": 62,
    "share_of_voice": 34.5,
    "avg_position": 2.1,
    "engines_cited": 6,
    "engines_total": 8,
    "mentions": 41,
    "sentiment_positive": 71,
    "prompts": 30
  },
  "timeseries": [{ "date": "2026-06-01", "value": 55 }],
  "per_engine": [
    { "engine": "openai", "label": "ChatGPT", "color": "#10a37f", "pct": 70 }
  ],
  "per_theme":    [{ "name": "plomberie", "pct": 60, "count": 12 }],
  "per_location": [{ "name": "Lyon", "pct": 58, "count": 10 }],
  "ranking": [
    { "name": "Votre marque", "share": 34, "you": true },
    { "name": "Concurrent A", "share": 21, "you": false }
  ],
  "sentiment": { "positive": 71, "neutral": 24, "negative": 5 },
  "top_sources": [{ "domain": "pagesjaunes.fr", "count": 9 }],
  "recent_mentions": [
    {
      "engine": "openai", "label": "ChatGPT", "color": "#10a37f",
      "prompt": "meilleur plombier à Lyon", "mentioned": true,
      "position": 2, "sentiment": "positive",
      "created_at": "2026-06-21T08:00:00+00:00"
    }
  ]
}

GET/sites/{id}/runs

The last 100 raw AI runs (one per question × engine).

Response codes

200Success
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "data": [
    {
      "engine": "perplexity",
      "mentioned": true,
      "position": 1,
      "share_of_voice": 40.0,
      "sentiment": "positive",
      "cited_sources": [{ "domain": "exemple.fr", "url": "https://exemple.fr/" }],
      "created_at": "2026-06-21T08:00:00+00:00"
    }
  ]
}

Competitors

GET/sites/{id}/competitors

The competitors tracked for this site.

Response codes

200Success
404Site not found or not owned by your account
401API key missing, invalid or revoked
429Too many requests (rate limit exceeded)

Response (200)

{
  "data": [
    { "name": "Concurrent A", "domain": "concurrent-a.fr" }
  ]
}

4. Path parameters

{id} = the site identifier (the id field returned by GET /sites, e.g. site_8f2…).

5. Status codes & errors

Code	Meaning
`200`	Success (read).
`201`	Resource created (audit run).
`202`	Accepted — asynchronous processing started (AI analysis).
`401`	API key missing or invalid / revoked.
`403`	Quota reached (e.g. monthly AI runs exhausted).
`404`	Resource not found (site missing or not owned by you).
`429`	Too many requests (see limits below).

All errors follow the same format:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Quota de runs IA atteint ce mois-ci (3000/3000).",
    "details": { "used": 3000, "limit": 3000 },
    "request_id": "a1b2c3…"
  }
}

6. Rate limits

Read: 120 requests/minute per key. Audit trigger: 30/hour. AI analysis trigger: 20/hour (also limited by your monthly AI-run quota, visible via GET /usage).

Generate my API key →

Legal notice · Terms of Sale / Use · Privacy