# Dismiss Actionable Source: https://docs.geogen.io/api-reference/actions-dismiss post /entities/actions/dismiss Dismiss an actionable recommendation so it no longer appears in the active feed. Dismissed actionables free up slots for new ones to be generated on the next mention check (max 30 active per entity). # Get Actions Source: https://docs.geogen.io/api-reference/actions-get get /entities/actions Get AI-generated actionable recommendations and their associated tasks for an entity. Actionables are SEO improvement suggestions generated after each mention check. Tasks are actionables that have been moved to the kanban board for tracking. # Update Task Status Source: https://docs.geogen.io/api-reference/actions-update-status post /entities/actions/update-status Update the status of a task on the kanban board. Move tasks through the workflow: not_started → in_progress → in_review → done. # Authentication Source: https://docs.geogen.io/api-reference/authentication Learn how to authenticate your API requests ## API Key Authentication All API requests require authentication using a workspace API key. ### Obtaining an API Key 1. Navigate to **Settings** → **Workspaces** → **Your Workspace** → **API Keys** in your dashboard 2. Click **Create API Key** 3. Give your key a descriptive name 4. Copy and securely store your API key - it will only be shown once Keep your API key secret! Never expose it in client-side code or public repositories. ### Using Your Workspace API Key Authenticate requests using either header: | Header | Format | | --------------- | ------------------------- | | `Authorization` | `Bearer wsk_your_api_key` | | `X-API-Key` | `wsk_your_api_key` | ### API Key Format ``` wsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` * **Prefix:** `wsk_` (Workspace Key) * **Body:** 32 random alphanumeric characters ### Authentication Errors | Status | Error | | ------ | ---------------------- | | `401` | Missing API key | | `401` | Invalid API key | | `401` | API key is deactivated | ### Best Practices * Store API keys in environment variables * Use separate keys for development and production * Rotate keys periodically * Monitor API key usage in your dashboard # Check Domain Availability Source: https://docs.geogen.io/api-reference/check-domain get /entities/check-domain Check if a domain is available for tracking before creating an entity. Returns whether the domain is available, already in your workspace, or tracked by another user. # Get Entity Citations Source: https://docs.geogen.io/api-reference/citations get /entities/citations Get top cited domains for an entity. # Get Citation Details Source: https://docs.geogen.io/api-reference/citations-details get /entities/citations/details Get detailed URLs for a specific cited domain. Use the citedEntityUuid from the Get Citations endpoint to retrieve the individual citation URLs. # Get Competitors Source: https://docs.geogen.io/api-reference/competitors get /competitors Get competitors visibility leaderboard. # Create Domain Group Source: https://docs.geogen.io/api-reference/domain-groups-create post /domain-groups Create a domain group that merges analytics for multiple entities representing the same brand. Entity references in `primaryEntity` and `entities` may be either: - an `entityId` returned by `GET /v1/entities` (a tracking ID for an entity in this workspace), or - an entity UUID returned as `entityUuid` by `GET /v1/competitors` (any entity in the system). At least 2 entities are required, and `primaryEntity` must be included in the `entities` array. Each entity may belong to at most one group at a time. Additional non-primary entities count toward your workspace entity limit. # Delete Domain Group Source: https://docs.geogen.io/api-reference/domain-groups-delete delete /domain-groups Delete a domain group. Analytics for the previously merged entities will be reported separately again. # List Domain Groups Source: https://docs.geogen.io/api-reference/domain-groups-list get /domain-groups List all domain groups in the workspace. A domain group merges analytics for multiple entities that represent the same brand into a single entry. Provide the optional `groupId` query parameter to fetch a single group by its ID, or `entityId` to filter to groups scoped to a specific entity tracking. # Update Domain Group Source: https://docs.geogen.io/api-reference/domain-groups-update patch /domain-groups Update an existing domain group. Only the fields provided in the request body are changed. When `entities` is supplied, the same validation rules apply as when creating: at least 2 entities, the primary entity must be a member, entities must not overlap with other groups in the workspace, and the workspace entity limit must not be exceeded. # Create Entity Source: https://docs.geogen.io/api-reference/entities-create post /entities Create a new entity with AI-generated prompts and start tracking. # Get Entities Source: https://docs.geogen.io/api-reference/entities-get get /entities Get all entities in the workspace. # Entities remove Source: https://docs.geogen.io/api-reference/entities-remove delete /entities # Entities update Source: https://docs.geogen.io/api-reference/entities-update patch /entities # Introduction Source: https://docs.geogen.io/api-reference/introduction Welcome to the Geogen API ## Overview The Geogen API allows you to programmatically access your LLM visibility data, manage entities, and track AI mentions. This API is currently in beta, and its endpoints and data structures may change. Thank you for your understanding as we continue to refine and improve it. ## Base URL All API requests should be made to: ``` https://api.geogen.io/v1 ``` ## Quick Start 1. Generate an API key from **Settings** → **Workspaces** → **Your Workspace** → **API Keys** 2. Add the key to your request headers 3. Make your first API call ```bash theme={null} curl -X GET "https://api.geogen.io/v1/entities" \ -H "Authorization: Bearer wsk_your_api_key" ``` ## Response Format All responses are returned in JSON format: ```json theme={null} { "success": true, "data": [...], "pagination": { "total": 100, "limit": 20, "offset": 0 } } ``` ## Need Help? Contact us at [contact@geogen.io](mailto:contact@geogen.io) # Get Models Source: https://docs.geogen.io/api-reference/models get /models Get all available LLM models. # Get Name Request Status Source: https://docs.geogen.io/api-reference/name-request-status get /entities/name-request Check the status of a name change request for an entity. Returns the most recent request with its current status (pending, approved, or rejected). # Submit Name Change Request Source: https://docs.geogen.io/api-reference/name-request-submit post /entities/name-request Submit a request to correct an entity's display name. Entity names are global shared data and cannot be changed directly. Instead, submit a name correction request that will be reviewed by an admin. **Limit:** One pending request per entity per workspace. # Add Prompt Source: https://docs.geogen.io/api-reference/prompts-add post /entities/addprompt Create a new prompt for an entity. # Delete Prompt(s) Source: https://docs.geogen.io/api-reference/prompts-delete delete /entities/deleteprompt Delete one or more prompts. Supply either `promptId` (single) or `promptIds` (batch) via query parameters, or a JSON body with `{ "promptId": "..." }` or `{ "promptIds": ["...", "..."] }`. Maximum 100 IDs per batch request. # Get Entity Prompts Source: https://docs.geogen.io/api-reference/prompts-get get /entities/prompts Get prompts for a specific entity with performance stats. # Update Prompt(s) Source: https://docs.geogen.io/api-reference/prompts-update patch /entities/updateprompt Update one or more prompts in a single request. **Single mode** — supply `promptId` plus any subset of editable fields (`prompt`, `language`, `geolocation`, `isActive`). Returns the updated prompt. **Batch mode** — supply `updates: [...]` where each entry carries its own `promptId` and the fields to change for that prompt. Different prompts can receive different patches in the same call. Maximum 100 updates per request. Set `isActive` to `false` to pause tracking for a prompt without deleting it. # Get Query Fanouts Source: https://docs.geogen.io/api-reference/query-fanouts get /query-fanouts Get web search queries that LLMs performed during response generation. These are the queries that AI models use to search the web while generating their responses. # Rate Limits Source: https://docs.geogen.io/api-reference/rate-limits Understand API rate limits ## Overview The API implements rate limiting to ensure fair usage and protect against abuse. ## Rate Limits | Operation Type | Rate Limit | Scope | | -------------------------------- | ---------------- | ------------- | | **Read** (GET requests) | 100 requests/min | Per API Key | | **Write** (POST/DELETE requests) | 20 requests/min | Per API Key | | **Entity Creation** | 10 entities/hour | Per Workspace | ## Rate Limit Response When you exceed a rate limit, you'll receive a `429 Too Many Requests` response: ```json theme={null} { "error": "Rate limit exceeded. Please slow down your requests.", "retryAfter": 30 } ``` The `Retry-After` header indicates how many seconds to wait before retrying. ## Handling Rate Limits ```python theme={null} import time import requests response = requests.get(url, headers=headers) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 60)) time.sleep(retry_after) # Retry the request ``` ## Best Practices * **Cache responses** to reduce API calls * **Batch operations** when possible * **Implement retry logic** with exponential backoff ## Need Higher Limits? Contact us at [contact@geogen.io](mailto:contact@geogen.io) to discuss enterprise options. # Get LLM Responses Source: https://docs.geogen.io/api-reference/responses get /responses Get LLM responses with mention status. # Get Response Details Source: https://docs.geogen.io/api-reference/responses-details get /responses/details Get comprehensive details for a single LLM response, including all mentions, citations, and query fanouts associated with it. # Get Tracking Status Source: https://docs.geogen.io/api-reference/tracking-status get /entities/tracking-status Get the mention check status for an entity. Returns when the last check completed, when the next check is scheduled, and whether a check is currently in progress. Useful for syncing — poll this endpoint to know when new data is available. # Get Citations Trend Source: https://docs.geogen.io/api-reference/trends-citations get /trends/citations Get daily citation trend for top cited domains over time. Returns time-series data showing how many times each of the top domains was cited per day, useful for tracking citation patterns and identifying emerging or declining sources. # Get Sentiment Trend Source: https://docs.geogen.io/api-reference/trends-sentiment get /trends/sentiment Get sentiment trend over time. # Get Visibility Trend Source: https://docs.geogen.io/api-reference/trends-visibility get /trends/visibility Get visibility trend over time. # Get Workspace Source: https://docs.geogen.io/api-reference/workspace get /workspace Get workspace information, usage limits, and credit balance. # Get Workspace Members Source: https://docs.geogen.io/api-reference/workspace-members get /workspace/members Get all team members in the workspace. # Get Workspace Tags Source: https://docs.geogen.io/api-reference/workspace-tags get /workspace/tags Get all tags in the workspace. # Actions Source: https://docs.geogen.io/cli/actions AI-generated recommendations and kanban tasks GeoGen generates **actionables** (AI-suggested SEO improvements) and lets you promote them to **tasks** on a kanban board. The CLI exposes both surfaces. ## `geogen actions list` List actionables and tasks for an entity. Maps to [`GET /v1/entities/actions`](/api-reference/actions-get). ```bash theme={null} geogen actions list --entity ent_123 ``` Options: | Flag | Description | | ------------------ | ------------------------------------------------------- | | `--entity ` | Entity ID (required) | | `--status ` | Filter actionables: `active`, `dismissed`, or `in_task` | The output renders two tables: one for actionables, one for tasks. ## `geogen actions dismiss` Dismiss an actionable so it no longer appears in the active feed. Dismissed actionables free up slots for new ones on the next mention check. Maps to [`POST /v1/entities/actions/dismiss`](/api-reference/actions-dismiss). ```bash theme={null} geogen actions dismiss --actionable-id act_abc ``` ## `geogen actions update-status` Move a task through the kanban workflow. Maps to [`POST /v1/entities/actions/update-status`](/api-reference/actions-update-status). ```bash theme={null} geogen actions update-status --task-id task_xyz --status in_progress ``` Valid `--status` values: * `not_started` * `in_progress` * `in_review` * `done` # Authentication Source: https://docs.geogen.io/cli/authentication How the CLI logs in and stores your API key The CLI authenticates with the same workspace API keys as the `/v1` REST API. The fastest way to get set up is the browser-based login flow. No copy-pasting keys. ## Browser-based login (recommended) ```bash theme={null} geogen login ``` Here's what happens: A page on the GeoGen dashboard asks you to authorize the CLI. If you're not signed in, you'll be prompted to sign in first. The dashboard shows a workspace picker. The CLI will only get access to the workspace you select. A new API key is minted with a label like `CLI: (2026-05-22)` so you can identify and revoke it from **Settings → API Keys** later. The dashboard hands the key back to the CLI through a temporary local listener (bound to `127.0.0.1` only). The CLI writes it to `~/.geogen/config.json` and the browser shows "✓ GeoGen CLI authorized". The flow times out after 5 minutes if you don't complete it. ### Login flags | Flag | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | Skip the browser flow and store this key directly (for scripts, CI, or when you already have a key). | | `--device ` | Override the device label used in the new key's name. Defaults to your machine's hostname. | | `--no-browser` | Start the local listener and print the auth URL, but don't try to open a browser. Useful over SSH or in containers. Copy the URL to a browser on another machine. | | `--base-url ` | Override the API base URL (default: `https://api.geogen.io`). | | `--dashboard-url ` | Override the dashboard URL used for the consent page. By default it's derived from `--base-url`: `api.geogen.io` → `app.geogen.io`. | ### Examples ```bash theme={null} # Default: browser flow geogen login # Scripts / CI: paste a pre-existing key, no browser needed geogen login --api-key wsk_your_api_key_here # Over SSH: get the URL, paste it into a browser on your laptop geogen login --no-browser # Custom device label (shows up in Settings → API Keys) geogen login --device "macbook-pro" ``` ## Credential resolution order For any command (other than `login`), the CLI resolves credentials in this order. The first match wins: ```bash theme={null} geogen workspace --api-key wsk_your_api_key_here ``` Per-command override. Use it to run against a different workspace without changing anything else. ```bash theme={null} export GEOGEN_API_KEY=wsk_your_api_key_here export GEOGEN_BASE_URL=https://api.geogen.io # optional geogen workspace ``` Best for CI/CD secrets. The key written by `geogen login`, stored at `~/.geogen/config.json` (chmod 600 on POSIX). ## Logout Clears the stored credentials: ```bash theme={null} geogen logout ``` This only removes the local copy. To fully revoke access, also delete the key from **Settings → API Keys** in the dashboard. ## Inspect resolved config `geogen config` prints the effective configuration and where each value came from: ```bash theme={null} $ geogen config Config file: /Users/you/.geogen/config.json ┌──────────┬─────────────┬────────┐ │ setting │ value │ source │ ├──────────┼─────────────┼────────┤ │ api key │ wsk_…ab12 │ file │ │ base url │ https://api.geogen.io │ default │ └──────────┴─────────────┴────────┘ ``` The API key is masked. Only the first and last four characters are shown. ## Config file format `~/.geogen/config.json` is plain JSON: ```json theme={null} { "apiKey": "wsk_your_api_key_here", "baseUrl": "https://api.geogen.io" } ``` You can edit it manually if you prefer. Missing fields fall through to env vars, then defaults. Never commit `~/.geogen/config.json` or your API key to source control. For CI pipelines, use `GEOGEN_API_KEY` as a secret instead. ## Multiple workspaces Each `geogen login` mints a new API key bound to whichever workspace you pick on the consent screen. To switch which workspace the CLI talks to, you have two options: ```bash theme={null} # Re-run login and pick a different workspace geogen login # Or pass a different key per command GEOGEN_API_KEY=wsk_other_workspace_key geogen entities list ``` ## Security notes The browser-based flow is designed so your API key never leaves your machine in plain text any longer than necessary: * The local HTTP listener binds to **`127.0.0.1` only** (not exposed on your network). * The listener accepts callbacks from **only the configured dashboard origin** (CORS-locked). * A **cryptographically random `state` token** is exchanged through the URL. Any callback with the wrong state is rejected, defeating local-process impersonation. * The listener **shuts down immediately** after receiving the key, or after a 5-minute timeout. The API key itself is stored unencrypted in `~/.geogen/config.json` (chmod 600). If that's not acceptable for your environment, use `GEOGEN_API_KEY` env var injection from a secrets manager instead. ## Errors | Symptom | Likely cause | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | `Login timed out after 300s.` | Browser flow didn't complete within 5 minutes. Re-run `geogen login`. | | `Could not reach the CLI listener on your machine.` | The browser tab is using a stale port and the CLI process already exited. Re-run `geogen login`. | | `Callback state mismatch: refusing key.` | Another process tried to send a key to the listener. Very unusual; re-run `geogen login`. | | `Only workspace owners and admins can create API keys` | The dashboard requires owner/admin role to mint API keys. Ask a workspace owner. | | `Maximum of 5 API keys allowed per workspace.` | Delete stale `CLI: ...` keys in **Settings → API Keys**, then retry. | | `No API key found.` | None of the three credential sources resolved a key. Run `geogen login`. | | `Invalid API key format` / `HTTP 401` | Key was rejected by the server. Try `geogen login` again. | # Citations Source: https://docs.geogen.io/cli/citations See which domains and URLs LLMs cite when answering about your entity Citations are the external links LLMs reference when answering prompts. The CLI exposes both the aggregated top-domains view and per-domain URL drill-downs. ## `geogen citations list` Top cited domains for an entity. Maps to [`GET /v1/entities/citations`](/api-reference/citations). ```bash theme={null} geogen citations list --entity ent_123 --period 30d --limit 20 ``` Options: | Flag | Description | | ----------------------------------------- | --------------------------- | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range | | `--models ` | Comma-separated model UUIDs | | `--tags ` | Comma-separated tag IDs | | `--prompt-ids ` | Comma-separated prompt IDs | | `--limit ` | Max results | | `--offset ` | Pagination offset | The result includes a `uuid` for each cited domain. Use that with `citations details` to drill in. ## `geogen citations details` Show exact URLs LLMs cited on a specific domain. Maps to [`GET /v1/entities/citations/details`](/api-reference/citations-details). ```bash theme={null} geogen citations details \ --entity ent_123 \ --cited \ --period 30d \ --limit 50 ``` | Flag | Description | | ----------------------------------------- | -------------------------------------------------- | | `--entity ` | Entity ID (required) | | `--cited ` | Cited domain UUID from `citations list` (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range | | `--models ` | Comma-separated model UUIDs | | `--limit ` | Max results | | `--offset ` | Pagination offset | ### Pipeline example ```bash theme={null} # Top cited domain → drill into its URLs TOP_UUID=$(geogen --json citations list --entity ent_123 --limit 1 | jq -r '.data[0].citedEntityUuid') geogen citations details --entity ent_123 --cited "$TOP_UUID" ``` # Competitors Source: https://docs.geogen.io/cli/competitors See how your entity ranks against competitors in LLM mentions ## `geogen competitors` Competitor visibility leaderboard. Maps to [`GET /v1/competitors`](/api-reference/competitors). ```bash theme={null} geogen competitors --entity ent_123 --period 30d ``` Options: | Flag | Description | | ----------------------------------------- | -------------------------------------------- | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range | | `--models ` | Comma-separated model UUIDs | | `--competitors-only` | Exclude your own entity from the leaderboard | | `--limit ` | Max results | | `--offset ` | Pagination offset | Columns: `rank`, `name`, `visibility%`, `mentions`. ```bash theme={null} # Top 10 competitors only, last 14 days, JSON output geogen --json competitors \ --entity ent_123 \ --period 14d \ --competitors-only \ --limit 10 ``` # Domain Groups Source: https://docs.geogen.io/cli/domain-groups Group sibling/aliased entities under a single primary A **domain group** lets you tie several entity records together. For example, when one brand is tracked under multiple domains (`acme.com`, `acme.io`, `getacme.com`) and you want their analytics merged behind a single primary. Each group has one **primary entity** and two or more **member entities**. ## `geogen domain-groups list` List domain groups in the workspace. Maps to [`GET /v1/domain-groups`](/api-reference/domain-groups-list). ```bash theme={null} geogen domain-groups list geogen domain-groups list --entity ent_123 # only groups scoped to this tracking ``` | Flag | Description | | --------------- | ----------------------------------------------- | | `--entity ` | Filter to groups scoped to this entity tracking | ## `geogen domain-groups get` Fetch a single domain group with its full member detail. The detailed payload is printed as JSON. ```bash theme={null} geogen domain-groups get --group-id grp_abc ``` ## `geogen domain-groups create` Create a new group from 2+ entities. Maps to [`POST /v1/domain-groups`](/api-reference/domain-groups-create). ```bash theme={null} geogen domain-groups create \ --primary ent_primary \ --entities ent_primary,ent_alias_io,ent_alias_get \ --name "Acme (all domains)" ``` | Flag | Description | | ------------------- | --------------------------------------------------------------------- | | `--primary ` | Primary entity, given as `entityTrackingId` or entity UUID (required) | | `--entities ` | Comma-separated entity refs, must include `--primary` (required, 2+) | | `--name ` | Group name. Defaults to the primary entity's name. | | `--entity ` | Optional entity tracking to scope the group to | You can pass either an `entityTrackingId` (the `id` from `geogen entities list`) or a raw entity UUID. The API resolves both forms. ## `geogen domain-groups update` Update a group's name, primary, or member list. Maps to [`PATCH /v1/domain-groups`](/api-reference/domain-groups-update). ```bash theme={null} geogen domain-groups update \ --group-id grp_abc \ --name "Acme (renamed)" \ --entities ent_primary,ent_alias_io,ent_alias_get,ent_alias_co ``` | Flag | Description | | ------------------- | --------------------------------------------------------------- | | `--group-id ` | Domain group ID (required) | | `--name ` | New name | | `--primary ` | New primary entity ref | | `--entities ` | New comma-separated member list (replaces the existing set; 2+) | If you pass `--entities`, the new list must contain the (possibly new) primary entity. ## `geogen domain-groups delete` Delete a domain group. Maps to [`DELETE /v1/domain-groups`](/api-reference/domain-groups-delete). ```bash theme={null} geogen domain-groups delete --group-id grp_abc ``` Deleting a group does not delete any of its member entities, only the grouping. Their individual analytics remain intact. # Entities Source: https://docs.geogen.io/cli/entities Create, list, update, and remove tracked entities Entities are the websites or brands you track. Every analytics command needs an entity ID. Get one from `geogen entities list`. ## `geogen entities list` List all tracked entities in the workspace. Maps to [`GET /v1/entities`](/api-reference/entities-get). ```bash theme={null} geogen entities list ``` The `id` column is the `entityTrackingId`. Use it with every other command that takes `--entity`. ## `geogen entities create` Create a new tracked entity. **This consumes credits.** Maps to [`POST /v1/entities`](/api-reference/entities-create). ```bash theme={null} geogen entities create \ --name "Acme" \ --domain acme.com \ --description "B2B CRM for small business" \ --language en \ --geolocation us ``` Options: | Flag | Description | | ------------------------ | ------------------------------------------------------- | | `--name ` | Display name (required) | | `--domain ` | Domain to track, e.g. `example.com` (required) | | `--description ` | Free-text description for context | | `--language ` | Language code, e.g. `en`, `fr` | | `--geolocation ` | Geolocation code, e.g. `global`, `us` | | `--models ` | Comma-separated model UUIDs (see `geogen models`) | | `--tracking-type ` | `website` (default) or `individual` | | `--no-generate-prompts` | Skip automatic AI prompt generation | | `--no-start-tracking` | Do not start tracking immediately | | `--prompt ` | Provide your own prompts. Repeat the flag for multiple. | ### With your own prompts ```bash theme={null} geogen entities create \ --name "Acme" --domain acme.com \ --prompt "best CRM for small business" \ --prompt "alternatives to Salesforce" \ --prompt "CRM with HubSpot-style automation" ``` When `--prompt` is supplied, automatic generation is skipped automatically. ## `geogen entities update` Update fields on an existing entity. Maps to [`PATCH /v1/entities`](/api-reference/entities-update). ```bash theme={null} geogen entities update \ --entity ent_123 \ --description "Updated description" \ --models uuid-a,uuid-b ``` | Flag | Description | | ---------------------- | ------------------------------------------------------- | | `--entity ` | Entity ID to update (required) | | `--name ` | New display name | | `--target ` | New domain/target | | `--description ` | New description | | `--language ` | Language code | | `--geolocation ` | Geolocation code | | `--models ` | Comma-separated model UUIDs (replaces the existing set) | ## `geogen entities delete` Remove an entity (or a single tracking instance) from the workspace. Maps to [`DELETE /v1/entities`](/api-reference/entities-remove). ```bash theme={null} geogen entities delete --entity ent_123 ``` Deletion soft-deletes the workspace's prompts and removes the tracking. The shared entity record (used by other workspaces tracking the same domain) is preserved. ## `geogen entities check-domain` Check whether a domain can be added to your workspace. Maps to [`GET /v1/entities/check-domain`](/api-reference/check-domain). ```bash theme={null} geogen entities check-domain --domain acme.com ``` The response tells you whether the domain is already tracked in your workspace, globally elsewhere, or fully available. ## `geogen entities tracking-status` Show when the last mention check completed, when the next is scheduled, and whether one is running right now. Maps to [`GET /v1/entities/tracking-status`](/api-reference/tracking-status). ```bash theme={null} geogen entities tracking-status --entity ent_123 ``` # Global Options Source: https://docs.geogen.io/cli/global-options Flags that work on every CLI command These flags apply to every `geogen` subcommand. They must appear **before** the subcommand (e.g. `geogen --json entities list`, not `geogen entities list --json`). | Flag | Description | | ------------------ | -------------------------------------------------------------------------------------------------- | | `--json` | Print raw JSON output instead of human-readable tables. Errors are printed as `{ "error": "…" }`. | | `--api-key ` | Override the API key for this invocation only. Takes precedence over env vars and the config file. | | `--base-url ` | Override the API base URL for this invocation only. Default: `https://api.geogen.io`. | | `-V`, `--version` | Print the CLI version. | | `-h`, `--help` | Print help text. Works on every subcommand too: `geogen entities create --help`. | ## `--json` The default output is a formatted table optimized for humans. Pass `--json` for clean structured output: ```bash theme={null} geogen --json entities list | jq '.[].entity.name' ``` This is the recommended mode for scripts and CI jobs. Table rendering may evolve between minor versions, but JSON output mirrors the underlying `/v1` API and is stable. ## `--api-key` and `--base-url` These exist for two cases: 1. **Multi-workspace scripts**: pass a different key per call without juggling env vars. 2. **Staging or self-hosted backends**: point at a non-production base URL. ```bash theme={null} geogen --api-key wsk_prod entities list geogen --base-url https://staging.geogen.io workspace ``` See [Authentication](/cli/authentication) for the full resolution order. ## Exit codes | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------- | | `0` | Command succeeded. | | `1` | Command failed. Error message printed to stderr, or to stdout as JSON when `--json` is set. | Standard output is reserved for command results; status, info, and error messages go to stderr. That means `geogen --json entities list > entities.json` produces a clean JSON file even if status messages would otherwise be printed. # Introduction Source: https://docs.geogen.io/cli/introduction Use the GeoGen CLI to query your LLM visibility data from any terminal # GeoGen CLI The GeoGen CLI is a terminal client for the GeoGen `/v1` API. It lets you query LLM visibility data, manage entities and prompts, and inspect citations and competitors, all from a shell. The CLI is a thin wrapper over the same public API used by the dashboard and MCP server, so anything you can do with curl, you can do with `geogen`. The CLI prints human-readable tables by default and supports `--json` on every command for piping into `jq`, scripts, or CI jobs. ## Prerequisites * **Node.js v18+** (check with `node -v`). [Download Node.js](https://nodejs.org) if it's missing. * A **GeoGen API key**. See **Settings → Workspaces → Your Workspace → API Keys**. ## Install Installs the `geogen` command on your PATH so you can run it like any other CLI: ```bash theme={null} npm install -g @geogenio/cli geogen --help geogen workspace ``` Run without installing globally. Use the explicit `-p ... geogen` form. The short `npx @geogenio/cli` form only resolves on newer npm/npx versions: ```bash theme={null} npx -p @geogenio/cli geogen --help npx -p @geogenio/cli geogen workspace ``` ## Quick start ```bash theme={null} # 1. Authenticate (opens your browser, pick a workspace, click Authorize) geogen login # 2. Verify the connection geogen workspace # 3. List your tracked entities geogen entities list # 4. Inspect visibility for an entity geogen trends visibility --entity ent_123 --period 7d ``` That's it. Every other command follows the same shape: `geogen [--flags]`. For scripts and CI where opening a browser isn't an option, pass an API key directly: `geogen login --api-key wsk_...`, or set `GEOGEN_API_KEY` as an environment variable. See [Authentication](/cli/authentication) for all three modes. ## Command map Usage, limits, credits, members, and tags Create, list, update, delete tracked entities Add, update, delete tracking prompts Submit and check entity name-change requests Group sibling entities under a single primary Browse available LLM models and their UUIDs LLM responses with mention status Top cited domains and per-domain URLs Competitor visibility leaderboard Daily visibility, sentiment, and citation trends Web search queries LLMs run while answering Actionable recommendations and kanban tasks ## Why a CLI? * **Scriptable**: drop `geogen` calls into any bash/PowerShell script or CI pipeline. * **Pipe-friendly**: pass `--json` and you get clean JSON for `jq`, `yq`, or any downstream tool. * **No SDK lock-in**: the CLI talks to the same `/v1` REST API documented under [Public APIs](/api-reference/introduction). You can swap to raw `curl` at any time. * **Same auth model as MCP**: your existing workspace API key works without any new setup. ## Need help? * Run `geogen --help` or `geogen --help` for inline reference. * See [Authentication](/cli/authentication) for credential storage and precedence. * See [Global Options](/cli/global-options) for flags that work on every command. * Email [contact@geogen.io](mailto:contact@geogen.io) if you hit a wall. # Models Source: https://docs.geogen.io/cli/models List available LLM models you can track against ## `geogen models` List every LLM model GeoGen can run mention checks against (ChatGPT, Claude, Perplexity, Gemini, etc.). Maps to [`GET /v1/models`](/api-reference/models). ```bash theme={null} geogen models ``` Columns: `id`, `name`, `description`. Use the `id` (a UUID) with the `--models` flag on commands like `geogen entities create`, `geogen entities update`, `geogen responses list`, and the trend commands. ```bash theme={null} # Pick the two model UUIDs you want and pass them comma-separated geogen entities update --entity ent_123 --models , ``` # Name Requests Source: https://docs.geogen.io/cli/name-request Submit and check name-change requests for an entity Entity names can't be edited directly. They go through a review workflow. The `name-request` group lets you submit a proposed name and check its status. ## `geogen name-request submit` Submit a name-change request. Maps to [`POST /v1/entities/name-request`](/api-reference/name-request-submit). ```bash theme={null} geogen name-request submit \ --entity ent_123 \ --name "Acme Corp." \ --reason "Trademark update from 'Acme Inc.'" ``` | Flag | Description | | ----------------- | --------------------------------- | | `--entity ` | Entity ID (required) | | `--name ` | Suggested new name (required) | | `--reason ` | Optional context for the reviewer | An admin reviews the request before the entity's display name actually changes. ## `geogen name-request status` Check the status of an outstanding request. Maps to [`GET /v1/entities/name-request`](/api-reference/name-request-status). ```bash theme={null} geogen name-request status --entity ent_123 ``` The response includes the suggested name, reason, current status, and timestamps. If there's no pending or recent request, the CLI reports `no pending request`. # Prompts Source: https://docs.geogen.io/cli/prompts Add, update, and delete tracking prompts Prompts are the questions LLMs are tested against to surface mentions of your entity. Each entity can have many prompts, each with its own language and geolocation. ## `geogen prompts list` List prompts for an entity with visibility, sentiment, and average position stats. Maps to [`GET /v1/entities/prompts`](/api-reference/prompts-get). ```bash theme={null} geogen prompts list --entity ent_123 --period 30d ``` Options: | Flag | Description | | -------------------- | ------------------------------------------ | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` (default: `30d`) | | `--start-date ` | Custom range start (use with `--end-date`) | | `--end-date ` | Custom range end | | `--tags ` | Comma-separated tag IDs | ## `geogen prompts add` Add one or more prompts to an entity. Maps to [`POST /v1/entities/addprompt`](/api-reference/prompts-add). ### Single prompt ```bash theme={null} geogen prompts add \ --entity ent_123 \ --prompt "best CRM for small business" ``` ### Multiple prompts in one call ```bash theme={null} geogen prompts add \ --entity ent_123 \ --prompt "best CRM for small business" \ --prompt "alternatives to Salesforce" \ --prompt "CRM with HubSpot-style automation" ``` The CLI automatically uses bulk mode when you pass more than one `--prompt`. | Flag | Description | | ---------------------- | ---------------------------------------------- | | `--entity ` | Entity ID (required) | | `--prompt ` | Prompt text. Repeat for multiple. | | `--language ` | Default language code for all added prompts | | `--geolocation ` | Default geolocation code for all added prompts | ## `geogen prompts update` Edit an existing prompt. Maps to [`PATCH /v1/entities/updateprompt`](/api-reference/prompts-update). ```bash theme={null} geogen prompts update \ --prompt-id pr_abc \ --text "new prompt wording" \ --active true ``` | Flag | Description | | ---------------------- | ---------------------------------------------- | | `--prompt-id ` | Prompt ID (required) | | `--text ` | New prompt text | | `--language ` | Language code | | `--geolocation ` | Geolocation code | | `--active ` | `true` / `false` to pause or resume the prompt | ## `geogen prompts delete` Soft-delete a prompt by ID. Maps to [`DELETE /v1/entities/deleteprompt`](/api-reference/prompts-delete). ```bash theme={null} geogen prompts delete --prompt-id pr_abc ``` # Query Fanouts Source: https://docs.geogen.io/cli/query-fanouts Inspect web search queries LLMs run while answering ## `geogen query-fanouts` When an LLM performs web search while answering a prompt, the search queries it issues are captured as **query fanouts**. They tell you what an LLM actually goes looking for when asked about your entity. Maps to [`GET /v1/query-fanouts`](/api-reference/query-fanouts). ```bash theme={null} geogen query-fanouts --entity ent_123 --period 30d --limit 50 ``` Options: | Flag | Description | | ----------------------------------------- | ------------------------------------- | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range | | `--models ` | Comma-separated model UUIDs | | `--tags ` | Comma-separated tag IDs | | `--search ` | Full-text search filter on query text | | `--limit ` | Max results | | `--offset ` | Pagination offset | Columns: `query`, `count`, `models`. ### Find queries mentioning a topic ```bash theme={null} geogen query-fanouts \ --entity ent_123 \ --search "pricing" \ --period 30d ``` For more context on what fanouts are and how to interpret them, see the [Query Fanouts concept guide](/concepts/query-fanouts). # Responses Source: https://docs.geogen.io/cli/responses Inspect raw LLM responses and their mention status Responses are the raw LLM outputs collected during mention checks. Each response is tied to a prompt and a model, and may or may not mention your entity. ## `geogen responses list` List responses with mention status. Maps to [`GET /v1/responses`](/api-reference/responses). ```bash theme={null} geogen responses list --entity ent_123 --period 7d ``` Options: | Flag | Description | | ----------------------------------------- | -------------------------------------- | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range | | `--models ` | Comma-separated model UUIDs | | `--tags ` | Comma-separated tag IDs | | `--prompt-ids ` | Comma-separated prompt IDs | | `--mention-status ` | `all`, `mentioned`, or `not-mentioned` | | `--limit ` | Max results | | `--offset ` | Pagination offset | ### Common filters ```bash theme={null} # Only responses that mentioned my entity in the last 14 days geogen responses list --entity ent_123 --period 14d --mention-status mentioned # Responses from two specific models geogen responses list --entity ent_123 --models , # Responses to a specific prompt geogen responses list --entity ent_123 --prompt-ids pr_abc ``` ## `geogen responses details` Show the full payload for a single response, including mentions, citations, and query fanouts. Maps to [`GET /v1/responses/details`](/api-reference/responses-details). ```bash theme={null} geogen responses details --response-id resp_xyz --entity ent_123 ``` The detail payload is rich and varies by model, so this command always prints JSON. Pair it with `jq` for ergonomic inspection: ```bash theme={null} geogen responses details --response-id resp_xyz --entity ent_123 \ | jq '.citations[].url' ``` # Trends Source: https://docs.geogen.io/cli/trends Daily visibility, sentiment, and citation trends over time The `trends` group exposes daily time-series for visibility, sentiment, and citations. All three subcommands accept the same time-range and filter flags. ## Shared options | Flag | Description | | ----------------------------------------- | ---------------------------- | | `--entity ` | Entity ID (required) | | `--period ` | `7d`, `14d`, or `30d` | | `--start-date ` / `--end-date ` | Custom date range (use both) | | `--models ` | Comma-separated model UUIDs | | `--tags ` | Comma-separated tag IDs | ## `geogen trends visibility` Daily visibility percentage, mention count, and total responses. Maps to [`GET /v1/trends/visibility`](/api-reference/trends-visibility). ```bash theme={null} geogen trends visibility --entity ent_123 --period 30d ``` Extra flag: `--prompt-ids ` to scope the trend to specific prompts. ## `geogen trends sentiment` Daily average sentiment score and mention count. Maps to [`GET /v1/trends/sentiment`](/api-reference/trends-sentiment). ```bash theme={null} geogen trends sentiment --entity ent_123 --period 14d ``` ## `geogen trends citations` Daily citation count for top cited domains. Maps to [`GET /v1/trends/citations`](/api-reference/trends-citations). ```bash theme={null} geogen trends citations --entity ent_123 --period 30d --top-n 5 ``` Extra flags: | Flag | Description | | -------------------- | --------------------------------------------------- | | `--prompt-ids ` | Comma-separated prompt IDs | | `--top-n ` | Number of top cited domains to include in the trend | ## Piping into a chart `--json` output is ready for any plotting tool: ```bash theme={null} geogen --json trends visibility --entity ent_123 --period 30d \ | jq -r '.data[] | [.date, .visibility] | @csv' \ > visibility.csv ``` # Workspace Source: https://docs.geogen.io/cli/workspace Inspect workspace usage, members, and tags The `workspace` group surfaces metadata about the workspace tied to your current API key. ## `geogen workspace` Show workspace usage, plan, limits, and credit balance. Equivalent to the [`GET /v1/workspace`](/api-reference/workspace) endpoint. ```bash theme={null} geogen workspace ``` ```bash theme={null} geogen workspace --json ``` Example output: ```text theme={null} ┌─────────────────────────┬─────────────────────────┐ │ field │ value │ ├─────────────────────────┼─────────────────────────┤ │ workspace │ Acme │ │ plan │ Growth │ │ entities used / limit │ 12 / 25 │ │ prompts used / limit │ 248 / 500 │ │ team seats used / limit │ 3 / 5 │ │ credits balance │ 2840 │ └─────────────────────────┴─────────────────────────┘ ``` ## `geogen workspace members` List all active team members. Maps to [`GET /v1/workspace/members`](/api-reference/workspace-members). ```bash theme={null} geogen workspace members ``` Columns: `email`, `name`, `role`, `joined`. ## `geogen workspace tags` List workspace tags used to organize prompts. Maps to [`GET /v1/workspace/tags`](/api-reference/workspace-tags). ```bash theme={null} geogen workspace tags ``` Use the returned tag IDs with `--tags` filters on commands like `geogen prompts list` or `geogen trends visibility`. # MCP Server Source: https://docs.geogen.io/concepts/mcp-server Connect your AI assistant to GeoGen using the Model Context Protocol # GeoGen MCP Server The GeoGen MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, Windsurf, GitHub Copilot, and OpenAI agents query your LLM visibility data, manage entities, and analyze trends via natural language. With the MCP server, you can ask your AI assistant questions like *"What's my visibility trend over the last 30 days?"* or *"Which domains are citing my brand?"* and get answers directly from your GeoGen data. ## Prerequisites * A **GeoGen API key** — go to **Settings → Workspaces → Your Workspace → API Keys** to create one * **Node.js** v18 or higher — download from [nodejs.org](https://nodejs.org) (required for Claude Desktop, Claude Code, Cursor, and Windsurf) **Not sure if you have Node.js?** Open your terminal (Mac: Terminal app, Windows: Command Prompt) and type `node -v`. If you see a version number like `v18.0.0` or higher, you're good. If you get an error, [download and install it first](https://nodejs.org). ## Setup Choose your AI assistant below and follow the step-by-step instructions. Claude Desktop stores its configuration in a JSON file. We need to find it, open it, and add the GeoGen MCP server config to it. ### Step 1: Open the config file The config file is in a **hidden folder** that doesn't show up in Finder by default. To get there: 1. Open **Finder** 2. Press **Cmd + Shift + G** — this opens a "Go to Folder" dialog 3. Paste this path and press Enter: ``` ~/Library/Application Support/Claude ``` 4. Find and open `claude_desktop_config.json` in a text editor (right-click > Open With > TextEdit, or any code editor) If the file doesn't exist yet, create a new file called `claude_desktop_config.json` in that folder. The config file is in your AppData folder, which is hidden by default. To get there: 1. Press **Win + R** to open the Run dialog 2. Paste this path and press Enter: ``` %APPDATA%\Claude ``` 3. Find and open `claude_desktop_config.json` in a text editor (right-click > Open With > Notepad, or any code editor) If the file doesn't exist yet, create a new file called `claude_desktop_config.json` in that folder. ### Step 2: Add the GeoGen config **If the file is empty or doesn't exist yet**, paste this entire block and replace `your-api-key-here` with your actual GeoGen API key: ```json {7} theme={null} { "mcpServers": { "geogen": { "command": "npx", "args": ["-y", "@geogenio/mcp-server"], "env": { "GEOGEN_API_KEY": "your-api-key-here", "GEOGEN_BASE_URL": "https://api.geogen.io" } } } } ``` **If the file already has content** (which is common), you need to merge the GeoGen config into it. Your file probably looks something like this: ```json theme={null} { "someExistingSetting": "someValue" } ``` Add a **comma** after the last existing setting, then add the `mcpServers` block before the final closing brace: ```json {8} theme={null} { "someExistingSetting": "someValue", "mcpServers": { "geogen": { "command": "npx", "args": ["-y", "@geogenio/mcp-server"], "env": { "GEOGEN_API_KEY": "your-api-key-here", "GEOGEN_BASE_URL": "https://api.geogen.io" } } } } ``` **Don't forget the comma!** JSON requires a comma between each setting. Missing it is the most common cause of errors. Make sure there's a comma after every item except the last one before a closing brace `}` or bracket `]`. If you **already have other MCP servers** configured, add GeoGen inside the existing `mcpServers` block with a comma: ```json {10} theme={null} { "mcpServers": { "some-other-server": { "command": "..." }, "geogen": { "command": "npx", "args": ["-y", "@geogenio/mcp-server"], "env": { "GEOGEN_API_KEY": "your-api-key-here", "GEOGEN_BASE_URL": "https://api.geogen.io" } } } } ``` ### Step 3: Replace the API key Replace `your-api-key-here` with your actual GeoGen API key (from **Settings > API Keys** in the GeoGen dashboard). Keep the quotes around it. ### Step 4: Save and restart 1. Save the file 2. Fully quit Claude Desktop (not just close the window) 3. Reopen Claude Desktop 4. Look for the **MCP plug icon** (🔌) in the chat input area — click it to confirm GeoGen is listed and connected Claude Code is a command-line tool, so setup is a single terminal command. Run this in your terminal, replacing `your-api-key-here` with your actual API key: ```bash theme={null} claude mcp add geogen \ -e GEOGEN_API_KEY=your-api-key-here \ -e GEOGEN_BASE_URL=https://api.geogen.io \ -- npx -y @geogenio/mcp-server ``` Verify it was added: ```bash theme={null} claude mcp list ``` You should see `geogen` in the output. Start a new conversation to begin using it. **Do not use `export`** to set the environment variables in your shell. The MCP server runs in its own process and won't see shell exports. Always pass them with the `-e` flag as shown above. Cursor reads MCP configuration from a JSON file in your project or home directory. ### Step 1: Create or edit the config file Open or create the file `.cursor/mcp.json` in one of these locations: * **Project-level** (only this project): `.cursor/mcp.json` in your project's root folder * **Global** (all projects): `~/.cursor/mcp.json` in your home folder ### Step 2: Add the GeoGen config Paste the following (or merge it into your existing config — see the merging guidance in the Claude Desktop tab if you need help): ```json theme={null} { "mcpServers": { "geogen": { "command": "npx", "args": ["-y", "@geogenio/mcp-server"], "env": { "GEOGEN_API_KEY": "your-api-key-here", "GEOGEN_BASE_URL": "https://api.geogen.io" } } } } ``` ### Step 3: Replace the API key Replace `your-api-key-here` with your actual GeoGen API key. ### Step 4: Verify 1. Save the file 2. Open **Cursor Settings > MCP** 3. GeoGen should appear with a **green status indicator** If it doesn't appear, restart Cursor. Windsurf reads MCP configuration from a central config file. ### Step 1: Open the config file 1. Open **Finder** 2. Press **Cmd + Shift + G** 3. Paste this path and press Enter: ``` ~/.codeium/windsurf ``` 4. Open `mcp_config.json` in a text editor. If it doesn't exist, create it. 1. Press **Win + R** to open the Run dialog 2. Paste this path and press Enter: ``` %USERPROFILE%\.codeium\windsurf ``` 3. Open `mcp_config.json` in a text editor. If it doesn't exist, create it. ### Step 2: Add the GeoGen config Paste the following (or merge it into your existing config — see the merging guidance in the Claude Desktop tab if you need help): ```json theme={null} { "mcpServers": { "geogen": { "command": "npx", "args": ["-y", "@geogenio/mcp-server"], "env": { "GEOGEN_API_KEY": "your-api-key-here", "GEOGEN_BASE_URL": "https://api.geogen.io" } } } } ``` ### Step 3: Replace the API key Replace `your-api-key-here` with your actual GeoGen API key. ### Step 4: Verify 1. Save the file and restart Windsurf 2. Go to **Windsurf Settings > Cascade > MCP** — GeoGen should appear in the list GitHub Copilot connects to GeoGen through a remote cloud connection — no Node.js required on your machine. ### Step 1: Open your VS Code settings You can add the config to either: * **VS Code settings**: Open the command palette (Cmd/Ctrl + Shift + P) > "Preferences: Open User Settings (JSON)" * **Project-level**: Create or edit `.vscode/mcp.json` in your project root ### Step 2: Add the GeoGen config ```json theme={null} { "mcp": { "servers": { "geogen": { "type": "sse", "url": "https://mcp.geogen.io/sse", "headers": { "x-api-key": "your-api-key-here" } } } } } ``` If adding to an existing `settings.json`, merge the `"mcp"` block into your existing settings (add a comma before it, just like any other setting). ### Step 3: Replace the API key Replace `your-api-key-here` with your actual GeoGen API key. GitHub Copilot connects to GeoGen's cloud server directly, so your API key is sent as a secure header with each request. You don't need Node.js installed for this method. OpenAI agents connect to GeoGen through a remote cloud connection. In the OpenAI Agent Builder, add a new MCP tool with the following settings: | Setting | Value | | ------------------ | --------------------------- | | **Transport type** | SSE | | **URL** | `https://mcp.geogen.io/sse` | | **Authentication** | Custom header | | **Header name** | `x-api-key` | | **Header value** | Your GeoGen API key | ## Available Tools Once configured, your AI assistant has access to the following tools: ### Read Operations | Tool | Description | | ----------------------- | ---------------------------------------------------------------------- | | `get_entities` | List all tracked websites/entities | | `get_workspace` | Workspace usage, limits, and credit balance | | `get_workspace_members` | List team members | | `get_workspace_tags` | List all tags | | `get_models` | Available LLM models | | `get_entity_prompts` | Prompts with visibility and sentiment stats | | `get_tracking_status` | Mention check status: last completed, next scheduled, processing state | | `get_responses` | LLM responses with mention status | | `get_response_details` | Detailed response data including mentions, citations, and fanouts | | `get_citations` | Top cited domains for an entity | | `get_citation_details` | Detailed URLs for a cited domain | | `get_competitors` | Competitor visibility leaderboard | | `get_citations_trend` | Daily citation trend for top cited domains | | `get_visibility_trend` | Visibility trend over time | | `get_sentiment_trend` | Sentiment trend over time | | `get_query_fanouts` | Web search queries LLMs perform | | `get_entity_actions` | AI-generated actionable recommendations and tasks | ### Write Operations | Tool | Description | | -------------------- | ---------------------------------------------- | | `create_entity` | Create a new tracked entity (consumes credits) | | `add_prompts` | Add single or bulk prompts to an entity | | `delete_prompt` | Delete a prompt | | `dismiss_actionable` | Dismiss an actionable recommendation | | `update_task_status` | Move a task through the kanban workflow | ## Example Queries Once connected, try asking your AI assistant: *"What's the visibility trend for my website over the last 30 days?"* *"Which domains are LLMs citing when they talk about my brand?"* *"Show me the top competitors for my website"* *"What search queries are LLMs running about my entity?"* *"What actionable recommendations do I have for my website?"* More example prompts: * *"List all my tracked entities"* * *"Add a new tracking prompt: 'What is the best project management tool?'"* * *"Give me a full SEO report comparing my entity against competitors"* * *"What's the sentiment trend for my brand this month?"* ## Environment Variables | Variable | Required | Description | | ----------------- | -------- | ----------------------------------------------- | | `GEOGEN_API_KEY` | Yes | Your GeoGen workspace API key | | `GEOGEN_BASE_URL` | Yes | GeoGen API URL — always `https://api.geogen.io` | Keep your API key secure. Never commit it to version control or share it publicly. ## Troubleshooting On **Mac**, the `Library` folder is hidden by default in Finder. Use **Cmd + Shift + G** and paste the path to navigate directly. On **Windows**, `%APPDATA%` is similarly hidden — press **Win + R** and paste the path to open it. The most common cause is a **JSON formatting error** — usually a missing or extra comma. JSON is strict about commas: every item needs a comma after it *except* the last item before a closing `}` or `]`. Try pasting your config into [jsonlint.com](https://jsonlint.com) to check for syntax errors. * Make sure you saved the config file (not just edited it) * Fully **restart** your client — closing the window isn't always enough (especially Claude Desktop) * Confirm Node.js v18+ is installed: open a terminal and run `node -v` `npx` comes bundled with Node.js. Install or update Node.js from [nodejs.org](https://nodejs.org) (v18 or higher). If you use a version manager like nvm or fnm, make sure the right version is active in your shell. * Verify your API key is correct — go to **Settings → Workspaces → Your Workspace → API Keys** in the GeoGen dashboard and copy it again * Make sure the key is inside quotes in the config file: `"your-key-here"` not `your-key-here` * Check that you didn't accidentally include extra spaces around the key Make sure you have at least one tracked entity in your GeoGen workspace. Most tools need an entity to return results. Do **not** use `export` in your shell — the MCP server runs in its own separate process. Pass variables with the `-e` flag: ```bash theme={null} claude mcp add geogen \ -e GEOGEN_API_KEY=your-api-key-here \ -e GEOGEN_BASE_URL=https://api.geogen.io \ -- npx -y @geogenio/mcp-server ``` ## Advanced: Connection Methods Explained GeoGen's MCP server supports two connection methods. You don't need to understand these to get set up — the instructions above handle it for you — but here's what's happening behind the scenes: **Local (stdio)** — Used by Claude Desktop, Claude Code, Cursor, and Windsurf. Your client downloads and runs the GeoGen MCP server package on your computer. Communication happens locally between your AI client and the server process. Your API key stays on your machine. **Remote (SSE)** — Used by GitHub Copilot and OpenAI agents. Instead of running anything locally, your client connects to GeoGen's hosted server at `mcp.geogen.io`. Your API key is sent as a secure header with each request. No Node.js needed. Both methods give you access to the same tools and data. # Query Fanouts Source: https://docs.geogen.io/concepts/query-fanouts Understanding how AI models research your brand and why it matters for GEO # What are Query Fanouts? **Query Fanouts** are the web search queries that AI models like ChatGPT, Perplexity, and Google Gemini execute when generating responses to user prompts. When a user asks an AI a question, the model often performs real-time web searches to gather up-to-date information before formulating its answer. Query Fanouts give you unprecedented visibility into *how* AI models research your brand, competitors, and industry topics in real-time. ## How Query Fanouts Work When users ask AI assistants questions like *"What's the best project management tool?"* or *"Compare Monday.com vs Asana"*, the AI doesn't always rely solely on its training data. Instead, many modern AI models: 1. **Parse the user's intent** - Understanding what information is needed 2. **Generate search queries** - Creating one or more web searches to find current information 3. **Execute the searches** - Querying the web for relevant results 4. **Synthesize the results** - Combining the information into a coherent response Geogen captures step 2 and 3 - the actual search queries the AI generates and executes. These are your **Query Fanouts**. ## Example Query Fanouts For a prompt like *"What are the best CRM tools for small businesses?"*, an AI might generate these query fanouts: | Query | Purpose | | --------------------------------------- | ------------------------- | | `best CRM software small business 2024` | Find current rankings | | `HubSpot CRM pricing` | Research specific product | | `Salesforce small business reviews` | Gather user sentiment | | `CRM comparison small teams` | Find comparison content | ## Why Query Fanouts Matter for GEO Understanding Query Fanouts is crucial for **Generative Engine Optimization (GEO)** because they reveal: ### 1. 🔍 The Exact Searches AI Uses Unlike traditional SEO where you guess which keywords users might search, Query Fanouts show you the **exact queries** AI models use to research your topic. This is the ground truth of how AI gathers information. ### 2. 📊 Content Gap Opportunities If an AI is searching for `[your competitor] vs [your brand] comparison` but can't find quality comparison content, that's a content opportunity you can fill. ### 3. 🎯 Keyword Intelligence Query Fanouts reveal the language patterns AI models use when researching topics. These patterns often differ from human search behavior, giving you unique optimization opportunities. ### 4. 📈 Brand Monitoring See when and how often AI models are actively researching your brand, products, or industry. Spikes in query fanouts for your brand can indicate trending interest. ### 5. 🏆 Competitive Intelligence Discover which competitors are being researched alongside your brand and understand the competitive landscape from the AI's perspective. ## Optimizing for Query Fanouts Based on Query Fanout data, you can optimize your content strategy: If AIs frequently search for `[Brand A] vs [Brand B]`, create authoritative comparison pages that answer these queries. Build content that directly answers the specific questions AIs are searching for about your industry. Use the exact language patterns from query fanouts in your content to match what AIs are looking for. Create comprehensive content clusters around topics that trigger frequent query fanouts. ## Query Fanouts vs Citations It's important to understand the difference between Query Fanouts and Citations: | Aspect | Query Fanouts | Citations | | ---------------------- | -------------------------------- | ------------------------------- | | **What they are** | Search queries AI executes | URLs AI references in responses | | **When they occur** | Before the response is generated | Within the final response | | **What they show** | How AI researches topics | What sources AI trusts | | **Optimization focus** | Content discoverability | Source authority | **Pro Tip:** Cross-reference your Query Fanouts with Citations. If AI is searching for topics related to your brand but citing competitors, you have a clear optimization opportunity. ## Accessing Query Fanout Data You can access Query Fanout data in several ways: ### In the Dashboard Navigate to your entity's Query Fanouts tab to see all the search queries AI models are executing related to your prompts. ### Via the API Use the `/query-fanouts` endpoint to programmatically access Query Fanout data: ```bash theme={null} GET /v1/query-fanouts?entityId=YOUR_ENTITY_ID&period=30d ``` See the [API Reference](/api-reference/query-fanouts) for full documentation. ## Best Practices Query Fanout patterns can shift as AI models update. Check your data weekly to identify new trends. Different AI models (ChatGPT vs Perplexity vs Gemini) may use different search strategies. Analyze them separately. Historical Query Fanout data helps you understand seasonal trends and measure the impact of your GEO efforts. Use Query Fanouts alongside visibility scores and citation data for a complete picture of your AI presence. *** Query Fanouts are captured in real-time as our system monitors AI responses to your configured prompts. The more prompts you have active, the more Query Fanout data you'll collect. # GeoGen Introduction Source: https://docs.geogen.io/index GeoGen is one of the leading Generative Engine Optimization Platforms ## Introduction GeoGen is a Generative Engine Optimization (GEO) platform built for businesses that want to dominate AI search. Unlike traditional SEO tools that optimize only for Google organic search results, GeoGen analyzes how large language models like ChatGPT, Google AI Overviews, Perplexity and others currently respond to your brand and competitors. Powered by multiple LLMs responses, GeoGen runs automated checks daily, identifies brand mentions, citations, and rank in the responses. Agencies use it to offer GEO as a new revenue stream, while brands use it to future-proof their discoverability across conversational AI platforms. Put simply: If SEO was built for search engines, GEO is built for AI engines, and GeoGen is the tool that makes it happen. ## What we Actually do GeoGen answers one simple question: When a customer asks an AI for help, does your business get mentioned? We uncover your brand's true position in the new AI dialogue, whether people are asking about your industry, your specific products, or the problems you're known for solving. Our platform is designed for anyone who needs this intelligence. Use it to understand your rank within AI models, to improve your visibility via the insights provided, to verify your brand's reputation or as an agency to deliver critical insights across a portfolio of clients. We measure your impact in two fundamental ways: **Direct Endorsements:** The AI names your company as a direct answer or recommendation. **Content Influence:** Your website is used as a source to build an answer, positioning you as an authority even without a direct mention. Our system queries multiple AI models every single day. This provides you with a constant stream of data, showing you precisely how often you appear and where you stand against your competitors. ## How we Collect Responses AI Responses Data Here’s what makes our data different, and more accurate. Most analytics tools pull data using APIs. Think of this as a special back-door for computers to talk to each other. It's clean, but it isn't always what a real person sees. Peec AI doesn't use APIs. Instead, our technology interacts with AI models the same way a customer does: by visiting the website, typing a question into the chat box, and reading the answer on the screen. This "human" approach gives us a few major advantages: **You See What Your Customers See:** We capture the exact, unfiltered responses that are shown to a live user, not a sanitized version sent through a developer's API. **True-to-Life Data:** Our results reflect the real-world experience, warts and all. What you see in our reports is what your customers are seeing in their browsers. **Wider AI Coverage:** This method allows us to test almost any AI model, even those that don't have a public API or only offer limited access. The bottom line is you get a truer picture of your brand's presence in AI. Instead of relying on APIs or theoretical outputs, GeoGen mimics an actual user asking questions inside AI tools. We capture the responses exactly as they appear on screen, the same way your customers would see them. ## API Calls VS Web Responses Scraping ### The API Calls way Here's a big problem with how most AI analytics tools work: they rely on official APIs. Think of an API as a private, direct line to the AI's brain. It's clean and fast, but it has some serious blind spots that can give you a distorted view of reality. **First:** the answers it provides often don't match what people see on the actual website. An answer from the API might be structured differently or leave out important details that a real user gets in the public chat interface. **Second:** the sources the AI cites can be completely different. The API might reference one set of links, while a user asking the same question sees another. This means you're not getting a true picture of the information being used to form the AI's opinion. But here’s the biggest issue: the API is often pulling from a static, outdated library of information. It doesn't perform a live web search. So, if you've been working hard to improve your content and boost your visibility, an API-based tool won't see any of it until the entire model is retrained months later. You have no way of knowing if your efforts are paying off. The bottom line is that if your data comes from an API, you're not just seeing a different answer, you're likely seeing an old one. You're not seeing what your customers are seeing right now. ### Web Responses Scraping At GeoGen, our approach is built on a simple premise: to see what your customers see, you have to act like one. That’s why we don’t use APIs. Instead of using a private back-channel, our platform interacts with AI models through their public front door, the same web interface your customers use every day. We automate browsers to ask questions and capture the results directly from the screen. This commitment to replicating the real user experience delivers a fundamentally better class of data: **You get the ground truth.** The data we provide isn't a filtered or slightly different version from an API. It's an exact mirror of what your audience sees, giving you total confidence in its accuracy. **Our system is built to last.** Because we don't depend on APIs, our ability to gather intelligence isn't affected by a company's decision to change, restrict, or remove its API access. We are independent and resilient. This technical difference is our strategic advantage. It ensures the insights you get from GeoGen are a true reflection of your brand's position in the real world. ## Our Platform's Insights * **See When You’re Mentioned:** Get a clear signal every time your brand is named in AI-generated answers across different models. * **Map Out the Competition:** Discover which competitors are showing up in your space and measure how their visibility compares to yours. * **Find the "Kingmaker" Sources:** Uncover which websites and articles the AI trusts and references, showing you exactly where to build authority. * **Close Attribution Gaps:** Spot instances where your content is used as a source *without* your brand getting the credit it deserves. * **Track Your Progress:** Watch how your presence changes over time as you optimize and as the AI models evolve. * **Stop Guessing, Start Knowing:** Base your AI strategy on hard data showing the probability of you being mentioned for key customer questions. * **Learn What AI Prefers:** Understand which types of content and sources perform best, so you can create more of what works. * **Focus Your Efforts:** Pinpoint the exact topics and prompts that have the biggest impact on your visibility and ignore the noise. # #5 Citations Tab Source: https://docs.geogen.io/quick-start/citations-tab Analyze the top citations used throughout your industry. # Citations Tab Analyze the top citations used throughout your industry. ![Citations Tab](https://i.imgur.com/RDhgFlX.gif) ## Filter Your Results Use the **Citations** tab to see which citations are dominant in your industry. Use the filter tools to narrow down results by date range, specific tags, or models. ## Track Changes Over Time Toggle the **Timeline View** to see how citations change on a daily basis. This ensures you are always one step ahead regarding where to direct your attention. ## Inspect Citation Links Expand any citation to see the specific URLs that were used to generate the recommendation. Use these insights to determine which articles are driving results and to strategize where your brand should appear. # #7 Competitors Selection Source: https://docs.geogen.io/quick-start/competitors-selection GeoGen lets you see which competitors appear alongside you in AI-generated responses, using the same visibility metrics to reveal who the algorithms are favoring. ## Adding your Competitors GeoGen automatically detects and flags brands that frequently appear in your AI-generated results. By default, it displays a leaderboard ranking these brands by their visibility score, giving you an accurate snapshot of who dominates your space. If you’d like to adjust it, you can: 1. To select custom competitors to monitor, click on the **Select** button at the bottom of each competitor card on the **Manage Competitors** Slide 2. Click on the "**X**" icon which appears whilst hovering on each competitor card to remove it/hide it, this can be undone as needed just by going on the **Rejected** tab and clicking \*\*Restore \*\*at the bottom of each competitor card. 3. You can select as many competitors you wish from the **Manage Competitors** Slide, they will replace the default competitors on the leaderboard. Competitors Selection Gi # #2 Prompts Configuration Source: https://docs.geogen.io/quick-start/prompts-configuration Everything we measure begins with the real-world prompts you care about: the kinds of things your buyers would actually ask an AI assistant. This isn’t traditional SEO tracking. There’s no fixed ranking. AI models are probabilistic, so results can change slightly from day to day. That’s why GeoGen runs your prompts repeatedly, to surface patterns that matter, not one-off anomalies. ## About Prompts People don’t “search” anymore.\ They *converse.* They’re not typing **“project management software.”**\ They’re asking **“What’s the best tool for keeping my remote team organized?”** To win in AI results, your brand needs to show up in those conversational answers, either by being named directly or by having your content used as an implicit source. GeoGen simulates these conversations across multiple AI models every 24 hours. Every run reveals which brands the AI prefers, how it justifies those recommendations, and whether *you* are being positioned as a leader, or forgotten. ## Selecting Your First Prompts Select Prompts Gi After filling the Website Details, AI will generate a set of prompts, you can then edit them or leave them as they are and click the **Start Tracking** Button. # #3 Prompts Tab Source: https://docs.geogen.io/quick-start/prompts-tab Add or remove prompts, select languages and regions, and manage tags ![Prompts Tab](https://i.imgur.com/dg8cIiS.gif) ## Adding New Prompts If you need to add more prompts after completing your initial onboarding configuration, navigate to the **Prompts** tab in the left-hand menu. Click the **Create Prompts** dropdown menu and choose **Add Prompt** to create a single prompt and assign its specific language and region. Alternatively, you can select **Suggest Prompts** from the dropdown to have the AI generate ideas, then choose your favorites from the suggested list. You can also select **Bulk Upload** to import multiple prompts at once using a CSV file. ## Managing Tags To keep things organized, you can create, add, or remove tags for your prompts. This allows you to easily filter your analytics by specific products or services later on. ## Editing Prompts At any time, you can edit added or imported prompts. Simply check the boxes on the left side of a prompt to modify its text, language, or location. ![Prompts Tab](https://i.imgur.com/CXaZi3t.gif) ## Single Prompt Insights By clicking on any prompt, you can view its individual visibility metrics, including the list of responses and the citations used to provide recommendations for that specific prompt. # #6 Query Fanouts Tab Source: https://docs.geogen.io/quick-start/query-fanouts-tab Discover the background search queries that AI models perform to generate recommendations. # Query Fanouts Tab Discover the background search queries that AI models perform to generate recommendations. ![Query Fanouts Tab](https://i.imgur.com/vundgHG.gif) ## What are Query Fanouts? "Fanout Queries" are the specific searches AI models execute in the background whenever a user submits a prompt. These often differ significantly from the user's original question. Models may run searches on different engines or limit them to specific domains (e.g., `site:pcmag.com "search term"`). Analyzing these queries helps you understand how AI models gather information and where your brand needs to be present to maximize recommendations. Additionally, they provide excellent headline ideas for future content on your company blog. ## Filtering Query Fanouts You can filter fanout queries by search terms, date, tag, or model. Currently, only Grok, ChatGPT, and Perplexity expose these background queries. We will add support for other models as soon as they make this data available. # #1 Adding an Entity Source: https://docs.geogen.io/quick-start/quickstart Ready to see where your brand stands in the world of AI search? GeoGen is the clearest path to knowing. We show you exactly what happens when people ask AI assistants about your industry, your products, and your competitors. Getting started is straightforward: just set up your company profile, add the questions your customers are asking, and let GeoGen get to work. Our platform interacts with AI models the same way a person does, by using their public websites. This guarantees the data you see is authentic and truly reflects the live user experience. After you complete the quick setup, you’ll have your first report showing precisely how your brand is appearing across the AI landscape. Add Entity Gi 1. Click on **Select Entity** on the top left menu 2. Select **Add New Tracking** 3. Select **Website** (Default) or Individual (Beta) 4. Fill the **Website Name** field with your Company/Brand Name 5. Fill the **Website URL** field with your Company/Brand URL 6. **Create a Description for your Company/Brand (See Instructions Below)** \ Click the Sparkles Icon on at the Top-Right of the Description Field to have AI Crawl and Understand your Company/Brand and write a Description for it. Bare in mind that depending on your website structure, the Description Generated by AI may not be the most optimal for AI generated prompts afterwards, but it may be a good starting point, further tweak if necessary highlighting clearly the product/services offered by your company. \ **Instruction:** Enter a concise company + offering summary to improve prompt accuracy. **Format:** \[COMPANY NAME] provides/offers \[PRODUCT(S)/SERVICE(S)] \[in REGION(S) if applicable]. **Examples:** * • Acme Solar provides residential solar installation and maintenance. * • NordicFoods offers frozen vegan meals in Scandinavia. * • ByteGuard provides cybersecurity audits and managed SOC services. * • MedTour offers medical concierge services in the Gulf region. **Tip:** One sentence. Plain names, no slogans. Region only if it truly matters. # #4 Responses Tab Source: https://docs.geogen.io/quick-start/responses-tab Explore Responses for additional Insights. # Responses Tab Explore Responses for additional insights. ![Responses Tab](https://i.imgur.com/1UNs1Uv.gif) ## Filtering Responses In the **Responses** tab you can filter responses by **Mentioned/Not Mentioned**, by timeframe, by model and by tag. ## Exploring Additional Insights By clicking on a response you can select entities cited within the response and they get highlighted within the response content, plus you can view the citations the AI model used to provide the recommendations for that particular response.