AI Search Monitoring API, CLI, and MCP Guide

Why API-First Matters for AI Monitoring

Most AI visibility tools give you a dashboard and expect you to check it. That model breaks down fast. Your SEO data lives in Looker. Your alerts go to Slack. Your content calendar runs in Notion or Asana. If AI search data sits in a silo, nobody looks at it until something goes wrong.

Foglift makes the core monitoring data available programmatically: technical audit results, AI Readiness Scores, prompt-level AI Visibility results, sentiment, crawler analytics, and competitor mentions. You choose where it goes and how it gets there. Build a custom Slack bot that pings your team when a competitor overtakes you in ChatGPT. Feed visibility scores into your Tableau dashboard alongside organic traffic. Trigger content workflows automatically when scores drop.

This isn't a nice-to-have. For teams that already run on data pipelines, an API-first monitoring tool is the difference between AI search data that gets acted on and data that gets ignored. See our enterprise monitoring guide for the broader organizational framework.

API, CLI, and MCP Availability by Tool

Developer access is no longer a checkbox. If AI visibility data feeds a warehouse, an alerting pipeline, or an agent workflow, the plan boundary matters as much as the feature name. The table below reflects public pricing and product pages checked on July 30, 2026.

Foglift API Overview

The Foglift API is organized around the same surfaces developers use in the product: scans for technical audits, AI Visibility for model fan-out checks across ChatGPT, Perplexity, Claude, Gemini, and Google AI Overview, prompts for tracked query libraries, and monitoring summaries for history, sentiment, competitor movement, and crawler analytics. All public v1 endpoints return JSON and use standard HTTP methods. Full reference at /docs; see the technical documentation optimization guide for making API references easier for AI engines to cite.

Verified Endpoint Surface

These production routes cover the core monitoring loop. The examples below use the public v1 base URL and the method implemented by each route.

Dashboard-Ready Data Contract

The Search Console query ai visibility tool with api access so i can pipe metrics into my bi dashboard is the clearest statement of intent on this URL. A useful API should return rows that are already stable enough for a warehouse table. Nested dashboard payloads create extra reverse-engineering work. At minimum, keep these fields in your sync.

Authentication

The public technical scan can run without a key, subject to the free per-IP limit. Authenticated requests use API keys that start with sk_fog_. Pass the key as X-API-Key for v1 endpoints, or as Authorization: Bearer sk_fog_... where the docs note Bearer support. Launch, Growth, and Enterprise workspaces can generate keys in the dashboard under Settings or Developer. Multi-brand accounts should pass brand_id when an endpoint needs a workspace.

curl "https://foglift.io/api/v1/scan?url=https://example.com" \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json"

Technical Scan Endpoint

Run a technical audit and retrieve results programmatically. The audit analyzes SEO health, schema markup, AI Readiness signals, page performance, security headers, accessibility, and AI crawler access.

# Public scan, no key required within the free per-IP allowance
      curl "https://foglift.io/api/v1/scan?url=https://example.com"

      # Authenticated scan, higher plan allowance
      curl "https://foglift.io/api/v1/scan?url=https://example.com" \
        -H "X-API-Key: sk_fog_your_api_key"

      # Batch scan, Launch+ plan
      curl -X POST "https://foglift.io/api/v1/scan/batch" \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{"urls": ["https://example.com", "https://example.com/pricing"]}'

AI Visibility Endpoints

Check how your brand appears across AI search engines. Submit one prompt or an array of prompts, specify which models to query, and get back structured visibility data including citations, sentiment, positions, competitors, and per-model responses. If you omit prompts, Foglift uses the saved prompt library for the requested brand.

# Run one AI Visibility check
      curl -X POST https://foglift.io/api/v1/ai-visibility \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "brand_id": "WS_UUID",
          "prompt": "Best website optimization tools for SaaS companies",
          "domain": "yourbrand.com",
          "models": ["chatgpt", "perplexity", "claude", "gemini"],
          "dry_run": false
        }'

      # Pull recent results for dashboards or warehouse sync
      curl -H "X-API-Key: sk_fog_your_api_key" \
        "https://foglift.io/api/v1/ai-visibility/results?brand_id=WS_UUID&days=30&model=chatgpt&limit=100"

Batch Operations

For prompt libraries, use POST /api/v1/prompts to save up to 50 tracked prompts, then call POST /api/v1/ai-visibility without a prompt body to run the saved set. For page libraries, use the scan batch or sitemap endpoints.

curl -X POST https://foglift.io/api/v1/prompts \
        -H "X-API-Key: sk_fog_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "brand_id": "WS_UUID",
          "prompts": [
            { "text": "Best CRM for startups", "category": "comparison" },
            { "text": "Top project management tools 2026", "category": "industry" },
            { "text": "YourBrand vs CompetitorX", "category": "comparison" }
          ]
        }'

Example: Building a Slack Bot for AI Visibility Alerts

One of the most common integrations is a Slack bot that notifies your team when AI visibility changes. Here's a complete example using Foglift webhooks and a small Node.js server.

Step 1: Register a Webhook

Tell Foglift where to send scan and score events. Webhook registration is managed from the authenticated dashboard because each endpoint belongs to a user account. URLs must use HTTPS.

# Dashboard configuration
      Endpoint URL: https://your-server.com/webhooks/foglift
      Events: scan.completed, score.changed, score.dropped, visibility.changed

      # The receiver below is plain HTTP, so it works with Express, Next.js,
      # Cloudflare Workers, Fastify, or any framework that can parse JSON.

Step 2: Handle the Webhook and Post to Slack

A minimal Express server that receives Foglift webhook events and forwards them to a Slack channel via the Slack Web API:

import express from "express";

      const app = express();
      app.use(express.json());

      const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK_URL;

      app.post("/webhooks/foglift", async (req, res) => {
        const { event, data } = req.body;

        // Optional: verify a shared secret if your receiver requires one.
        // const isValid = verifySharedSecret(req);

        let message = "";

        if (event === "score.dropped") {
          message = [
            ":chart_with_downwards_trend: *AI Visibility Drop Detected*",
            `Brand: ${data.brand}`,
            `Page or prompt: ${data.target}`,
            `Previous score: ${data.previous_score}`,
            `Current score: ${data.current_score}`,
            `<https://foglift.io/dashboard|View details>`,
          ].join("\n");
        }

        if (event === "visibility.changed") {
          message = [
            ":warning: *AI Visibility Changed*",
            `Prompt: "${data.prompt}"`,
            `Engine: ${data.engine}`,
            `Mentioned: ${data.mentioned ? "yes" : "no"}`,
            `Citation count: ${data.citations?.length ?? 0}`,
          ].join("\n");
        }

        if (message) {
          await fetch(SLACK_WEBHOOK, {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ text: message }),
          });
        }

        res.status(200).json({ received: true });
      });

      app.listen(3001);

That's it. Your team now gets real-time Slack alerts whenever a monitored prompt shows a significant visibility change. No need to check a separate dashboard.

Connecting AI Search Data to Your BI Dashboard

AI search visibility belongs in the same dashboard where your team already tracks organic traffic, paid media performance, and conversion rates. Here's how to connect Foglift data to the most common BI tools.

Looker / Looker Studio

Create a custom data source that pulls from the Foglift API on a schedule. Use the /api/v1/ai-visibility/results endpoint for prompt-level history or /api/v1/monitor for a 7, 14, or 30-day summary.

// Fetch 30-day visibility history for Looker ingestion
      const response = await fetch(
        "https://foglift.io/api/v1/ai-visibility/results?" +
          new URLSearchParams({
            brand_id: "WS_UUID",
            days: "30",
            model: "chatgpt",
            limit: "100",
          }),
        {
          headers: {
            "X-API-Key": "sk_fog_your_api_key",
          },
        }
      );

      const data = await response.json();
      // Flatten the JSON into rows before loading your warehouse or BI source.

Metabase

Metabase supports REST API data sources via its native query interface or through a sync layer. The simplest approach is writing the Foglift data to your Postgres or BigQuery warehouse on a nightly cron, then pointing Metabase at the table. This gives you full SQL access to AI visibility data alongside every other metric you track.

Tableau

Use Tableau's Web Data Connector or its REST API integration to pull Foglift data directly. The JSON response format maps cleanly to Tableau's data model. Build cross-source dashboards that correlate AI citation rate with organic traffic, pipeline stage, or content publish dates to identify what drives AI visibility.

Webhook-Driven Workflows

Webhooks let you build automated responses to scan and score changes. Instead of polling the API on a schedule, register a webhook and Foglift pushes matching events to your endpoint.

Trigger Content Updates When Scores Drop

The highest-value webhook workflow is automatic content flagging. When an AI Readiness Score drops below a threshold or a monitored visibility event changes, the webhook fires and your system creates a ticket in Jira, Linear, or Asana with the affected URL or prompt, the prior score, the current score, and a link to the evidence.

// Webhook handler: auto-create Linear ticket on visibility drop
      app.post("/webhooks/foglift", async (req, res) => {
        const { event, data } = req.body;

        if (event === "score.dropped" && data.score_change <= -15) {
          await fetch("https://api.linear.app/graphql", {
            method: "POST",
            headers: {
              Authorization: `Bearer ${process.env.LINEAR_API_KEY}`,
              "Content-Type": "application/json",
            },
            body: JSON.stringify({
              query: `mutation {
                issueCreate(input: {
                  teamId: "${process.env.LINEAR_TEAM_ID}",
                  title: "AI visibility drop: ${data.target}",
                  description: "Score dropped ${data.score_change} points.\n\nTarget: ${data.target}\nPrevious score: ${data.previous_score}\nCurrent score: ${data.current_score}\n\n[View in Foglift](https://foglift.io/dashboard)",
                  priority: 2
                }) { issue { id url } }
              }`
            }),
          });
        }

        res.status(200).json({ ok: true });
      });

Available Webhook Events

CLI and MCP for Developer Workflows

Not every workflow needs a webhook or a dashboard. Sometimes you just want to check your AI visibility from the terminal. The Foglift CLI (foglift-scan) wraps the API in a developer-friendly interface that works in scripts, CI/CD pipelines, and interactive sessions.

CLI Quick Start

# Install
      npm install -g foglift-scan

      # Authenticate (env var; generate a key at foglift.io/dashboard/settings)
      export FOGLIFT_API_KEY=sk_fog_your_api_key

      # Scan a single URL (no API key required for the basic scan)
      foglift scan https://example.com
      foglift scan https://example.com --json --threshold=80

      # Run an AI visibility check across engines
      foglift scan ai-check --prompt "best project management tools" \
        --models chatgpt,perplexity,claude,gemini \
        --domain yourbrand.com

      # Pull recent visibility results and sentiment
      foglift scan results --days 7 --model chatgpt --json > results.json
      foglift scan sentiment --days 30 --json

      # Manage tracked prompts
      foglift scan prompts list
      foglift scan prompts add "best tools to rank in ChatGPT"

      # Scan history for a URL
      foglift scan history https://example.com --json

CI/CD Integration

Add a Technical Audit to your deployment pipeline so every push is graded across SEO, AI Readiness, performance, security, and accessibility. --threshold=N returns exit code 1 if the overall score drops below N, which gives you a clean pipeline gate.

# GitHub Actions example
      - name: Technical Audit post-deploy
        env:
          FOGLIFT_API_KEY: ${{ secrets.FOGLIFT_API_KEY }}
        run: |
          npm install -g foglift-scan
          # Fail the build if AI Readiness drops below 80
          foglift scan https://example.com --threshold=80

          # Optional: capture structured results for reporting
          foglift scan https://example.com --json > ai-readiness.json
          foglift scan ai-check --prompt "best tools in your category" \
            --models chatgpt,perplexity --domain example.com --json > visibility.json

MCP Server: Foglift Inside Claude, Cursor, and Windsurf

Foglift has two MCP paths. Use the published local npm server (foglift-mcp@1.2.0) for stdio clients such as Cursor, Windsurf, and Claude Desktop that expect a command-based MCP server. Version 1.2.0 exposes 15 tools, with whoami at position 14 and recipe_run at position 15. Use the hosted OAuth endpoint for remote MCP clients that support a URL-based server. The hosted endpoint carries a separate 29-tool inventory, including Technical Audits, AI Visibility checks, stored page-score trends, source-gap evidence, observed competitor-mention evidence, recommendations, content briefs, setup guidance, recipes, and account utilities. The competitor tool reports mention counts and the percentage of selected industry-prompt results that mention each entity; it does not measure overall market or brand share of voice. Once either path is registered, an AI assistant can scan your site, pull visibility results, and run sentiment checks without leaving the chat. See the MCP integration comparison for how that agent loop differs from dashboard-only connectors.

The practical agent pattern is broader than a dashboard export. An agent can read prompt-level visibility, inspect cited source URLs, compare recurring competitors, and draft the next action from the same evidence. The canonical workflow lives at foglift.io/for-ai.

# Run on demand (no install)
      npx foglift-mcp

      # Or run as a long-lived HTTP server (for Claude.ai remote MCP)
      npx foglift-mcp --transport http --port 3001

      # Hosted OAuth endpoint for remote MCP clients
      https://mcp.foglift.io/api/mcp

      # Example registration in claude_desktop_config.json
      {
        "mcpServers": {
          "foglift": {
            "command": "npx",
            "args": ["foglift-mcp"],
            "env": { "FOGLIFT_API_KEY": "sk_fog_your_api_key" }
          }
        }
      }

The canonical hosted tool list and configuration examples live at foglift.io/integrations/mcp. That page keeps the hosted and local inventories separate. The local fallback package is published as foglift-mcp on npm.

Rate Limits, Authentication, and Best Practices

Rate Limits

Rate limits are enforced per endpoint and plan. Rate-limited responses include headers your integration can use for backoff:

X-RateLimit-Limit: 60
      X-RateLimit-Remaining: 47
      X-RateLimit-Reset: 1742662800

Authentication Best Practices

• Use separate keys: Create separate API keys for each integration (Slack bot, BI sync, CI pipeline). If one key is compromised, revoke it without disrupting other integrations.
• Store keys securely: Use environment variables or a secrets manager. Never commit API keys to version control.
• Rotate regularly: Set a quarterly rotation schedule. Paid accounts support multiple active keys, so you can replace one integration key without interrupting another.
• Protect webhook receivers: Store any webhook secret in your secrets manager, validate incoming requests before side effects, and rotate the endpoint if the receiver URL leaks.

Error Handling

The API uses standard HTTP status codes. All error responses include a machine-readable code field and a human-readable message:

// 429 Too Many Requests
      {
        "error": {
          "code": "rate_limit_exceeded",
          "message": "Rate limit exceeded. Retry after 23 seconds.",
          "retry_after": 23
        }
      }

      // Recommended: exponential backoff with jitter
      async function apiCallWithRetry(url, options, maxRetries = 3) {
        for (let i = 0; i < maxRetries; i++) {
          const res = await fetch(url, options);
          if (res.status === 429) {
            const retryAfter = res.headers.get("Retry-After") || 2 ** i;
            const jitter = Math.random() * 1000;
            await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
            continue;
          }
          return res;
        }
        throw new Error("Max retries exceeded");
      }

Pagination

History endpoints accept explicit limits and filters. Use the smallest window that answers the dashboard question, then paginate or repeat by model if you need a complete warehouse sync.

# Recent visibility results, scoped to one brand and model
      curl "https://foglift.io/api/v1/ai-visibility/results?brand_id=WS_UUID&days=30&model=chatgpt&limit=100" \
        -H "X-API-Key: sk_fog_your_api_key"

      # Monitoring summary for a 30-day dashboard window
      curl "https://foglift.io/api/v1/monitor?brand_id=WS_UUID&period=30d" \
        -H "X-API-Key: sk_fog_your_api_key"

Frequently Asked Questions

Fundamentals: Learn about GEO (Generative Engine Optimization) and AEO (Answer Engine Optimization) (the two frameworks for optimizing your content for AI search engines).