FullMention Public API Docs

FullMention tracks how AI assistants recommend brands, products, websites, services, and categories for real user-style recommendation queries.

Our platform is built around **AI recommendation snapshots**. You specify query keywords, trigger batch tracking runs, and fetch the latest structured results.

Overview Highlights

The API has been fully optimized for the new snapshot-first pipeline versioned under methodVersion: "rec_snapshot_v3".

• Same Capabilities: All pricing plans include the identical API surface. There are no features gated by plans—you only choose a plan based on monthly request volume.
• JSON over HTTPS: All request bodies and response payloads use clean, structured JSON over secure HTTPS.
• Snapshot-First: The API is optimized to return the latest known visibility state for a query/market, rather than hosting expensive chronological databases.

Authentication

Authenticate all requests by sending your API key as a bearer token in the Authorization header.

Authorization: Bearer fm_live_YOUR_API_KEY
Content-Type: application/json

Your API key represents your credentials. Live keys use production systems and capture real quota. Test keys are not supported.

Core Concepts

Integrations interact with three primary entities:

1. Keyword

A tracked search intent containing a keyword, a targeted market context (country, language, and optional location), and the engines to track (e.g. openai, openai-mini, gemini).

2. Run

An asynchronous processing job executing FullMention's proprietary extraction method across a targeted set of keywords. Runs are batch-oriented to optimize cost, capacity, and rate limits.

3. Result Snapshot

The structured, parsed outcome of the latest successful engine execution for a keyword. It contains explicit brand, website, and product ranking lists, category suggestions, and a root-level summary description.

Explicit Ranking System

FullMention delivers AI visibility intelligence utilizing flat ranking lists (brandRankings, websiteRankings, productRankings). Recognizing the importance of this structure is critical for properly interpreting the returned data:

• Explicit Position: Each item in these lists includes a position property (integer starting at 1). Position 1 represents the top recommendation / most prominent suggestion within the LLM context, followed sequentially by lower rankings.
• Pre-Sorted Order: The elements in these lists are strictly ordered by relevance, visibility prominence, and AI association weight. Maintaining this sequence in your application allows you to analyze visibility trends, brand dominance, and fine-grained AI shifts over time.

Rate Limits & Quota

FullMention separates rate limits (protecting API request volume) from quota credits (the currency consumed by processing runs).

Quota Credits & Engine Options

Successful runs consume credits transactionally based on the selected AI engines and whether web search fanout is enabled and successful:

• Gemini (1 credit total): Costs 1 base credit. Lightning-fast basic recommendation snapshot. Does not support search fanout in V1.
• GPT-5-mini (1 base + 1 fanout = 2 credits total): Costs 1 base credit plus a lightweight +1 credit fanout add-on if requested. Best value for high-volume standard web search tracking, capturing an average of 3.7 search queries and 91.6 source URLs per run.
• GPT-5 (1 base + 9 fanout = 10 credits total): Costs 1 base credit plus a premium +9 credit fanout add-on. Essential for premium localized market audits (e.g. EU/Danish compliance), capturing an average of 6.7 search queries and 164.6 source URLs (80% more search calls and sources than mini!) with rich inline citation links and compliancy page anchors.

Zero-Cost Search Protection: Fanout add-on credits are only captured if the web search successfully retrieves source URLs. If recommendation data is returned but search fails or returns zero sources, you are billed only the 1 base credit!

Quota Headers

Every successful API response includes quota headers describing remaining credits in your billing cycle:

Rate Limit Headers

API responses include standard headers describing your remaining request budget protecting the API request volume. Rate limits are bucketed by endpoint type:

Standard Rate Limit Budgets:

• Keywords API: 60 requests/minute
• Tags API: 120 requests/minute
• Runs API: 10 requests/minute
• Results API: 60 requests/minute

Idempotency

For mutation endpoints (like run creation), you should send an Idempotency-Key header containing a unique UUID.

If network connection fails, you can safely retry the request with the identical key. The server will return the original completed response without duplicate queueing or double-charging your quota.

Pagination

List endpoints support cursor-based pagination. If more results exist, the response will include a meta.nextCursor string.

To fetch the next page, pass this value in the cursor query parameter. When nextCursor is null, you have retrieved the final page.

Keywords API

Keywords represent the search queries or intent you want to track across AI engines in specific country, language, and optional location contexts.

POST /keywords

Adds one or more keywords to be tracked. This endpoint is idempotent. If a keyword with the same query text, country, language, and location already exists, the server returns the existing record instead of creating a duplicate.

Request Body

Keyword Object Fields

Example Request

{
  "keywords": [
    {
      "keyword": "seo tool",
      "country": "Denmark",
      "countryCode": "DK",
      "language": "Danish",
      "languageCode": "da",
      "location": "Copenhagen",
      "engines": ["openai-mini", "gemini"],
      "tags": ["client:acme", "market:dk"]
    }
  ]
}

Example Response (201 Created)

{
  "data": [
    {
      "id": "kw_12345",
      "keyword": "seo tool",
      "country": "Denmark",
      "countryCode": "DK",
      "language": "Danish",
      "languageCode": "da",
      "location": "Copenhagen",
      "engines": ["openai-mini", "gemini"],
      "tags": ["client:acme", "market:dk"],
      "active": true,
      "created": true
    }
  ],
  "meta": {
    "createdCount": 1,
    "existingCount": 0
  }
}

GET /keywords

Lists active keywords matching optional query filters.

Query Parameters

Example Response (200 OK)

{
  "data": [
    {
      "id": "kw_12345",
      "keyword": "seo tool",
      "country": "Denmark",
      "countryCode": "DK",
      "language": "Danish",
      "languageCode": "da",
      "location": "Copenhagen",
      "engines": ["openai-mini"],
      "tags": ["client:acme", "market:dk"],
      "active": true,
      "createdAt": "2026-05-13T12:00:00Z",
      "updatedAt": "2026-05-13T12:00:00Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

DELETE /keywords/{keywordId}

Soft-deletes/deactivates a keyword. Inactive keywords are excluded from future runs, and their cached results are hidden from standard snapshot queries.

Example Response (200 OK)

{
  "data": {
    "id": "kw_12345",
    "deleted": true
  },
  "meta": {}
}

Tags API

Tags are simple, flexible string labels attached to keywords to partition and filter them (e.g. by client, market, or category).

GET /tags

Returns all unique tags used across your account's active keywords along with their respective keyword counts.

Query Parameters

Example Response (200 OK)

{
  "data": [
    {
      "tag": "client:acme",
      "keywordCount": 42
    },
    {
      "tag": "market:dk",
      "keywordCount": 120
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

Runs Estimate API

Before executing a tracking run, you should estimate its cost to verify you have sufficient quota credits remaining.

POST /runs/estimate

Calculates execution counts and credit estimates for a run scope without scheduling or executing any jobs.

Request Body

Example Request

{
  "tags": ["client:acme", "market:dk"],
  "tagMode": "or",
  "options": {
    "fanout": true
  }
}

Example Response (200 OK)

{
  "data": {
    "logicalKeywordCount": 42,
    "engineExecutionCount": 84,
    "fanoutExecutionCount": 42,
    "estimatedBaseCreditCost": 84,
    "estimatedFanoutCreditCost": 42,
    "estimatedMaxCreditCost": 126,
    "quotaRemaining": 5400,
    "canRun": true
  },
  "meta": {}
}

POST /runs

Creates a new batch processing job to execute AI recommendation tracking across your scope.

Request Body

Example Request

{
  "tags": ["client:acme", "market:dk"],
  "tagMode": "or",
  "options": {
    "fanout": true
  }
}

Example Response (201 Created)

{
  "data": {
    "id": "run_555",
    "status": "queued",
    "scope": {
      "tags": ["client:acme", "market:dk"],
      "tagMode": "or",
      "options": {
        "fanout": true
      }
    },
    "logicalKeywordCount": 42,
    "engineExecutionCount": 84,
    "fanoutExecutionCount": 42,
    "estimatedBaseCreditCost": 84,
    "estimatedFanoutCreditCost": 42,
    "estimatedMaxCreditCost": 126,
    "executionMode": "batch",
    "createdAt": "2026-05-13T12:15:00Z"
  }
}

GET /runs/{id}

Retrieves the status, metrics, and progress updates for a batch run.

Response Fields

The response contains a unified progress sub-object that details active execution:

• status: Active processing state ("queued", "submitted", "processing", "success", or "failed").
• progress.percentage: Integer from 0 to 100 showing progress across underlying provider jobs.

GET /results/latest

Fetch the structured AI visibility snapshot results representing the latest completed runs.

Query parameters are available to filter the snapshots by tags, engine ("openai", "openai-mini", "gemini"), country, language, location, or a specific keywordId.

Example Response Snapshot (200 OK)

{
  "data": [
    {
      "id": "res_123",
      "keywordId": "kw_12345",
      "keyword": "seo tool",
      "country": "Denmark",
      "countryCode": "DK",
      "language": "Danish",
      "languageCode": "da",
      "location": "Copenhagen",
      "engine": "openai",
      "runId": "run_555",
      "methodVersion": "rec_snapshot_v3",
      "tags": ["client:acme", "market:dk", "category:seo"],
      "description": "Ahrefs is recommended as the top SEO platform for backlink analysis, followed by Semrush for visibility and keyword research.",
      "categorySuggestions": ["SEO software", "keyword research tools", "competitor analysis tools"],
      "brandRankings": [
        {
          "position": 1,
          "name": "Ahrefs"
        },
        {
          "position": 2,
          "name": "Semrush"
        }
      ],
      "websiteRankings": [
        {
          "position": 1,
          "domain": "ahrefs.com"
        },
        {
          "position": 2,
          "domain": "semrush.com"
        }
      ],
      "productRankings": [
        {
          "position": 1,
          "name": "Site Explorer"
        },
        {
          "position": 2,
          "name": "Keyword Magic Tool"
        }
      ],
      "fanout": {
        "queryCount": 35,
        "totalSourcesFound": 437,
        "sources": [
          {
            "rank": 1,
            "url": "https://stripe.com/us/payment-method/mobilepay",
            "domain": "stripe.com",
            "title": null,
            "query": "Stripe Denmark supported payment methods Denmark Klarna availability MobilePay",
            "sourceType": "web_search"
          },
          {
            "rank": 2,
            "url": "https://docs.stripe.com/payments/mobilepay?locale=en-GB",
            "domain": "docs.stripe.com",
            "title": null,
            "query": "Stripe Denmark supported payment methods Denmark Klarna availability MobilePay",
            "sourceType": "web_search"
          }
        ]
      },
      "metrics": {
        "brandCount": 2,
        "websiteCount": 2,
        "productCount": 2,
        "fanoutQueryCount": 35,
        "fanoutSourceCount": 437
      },
      "truncated": {
        "brandRankings": false,
        "websiteRankings": false,
        "productRankings": false,
        "fanoutSourcesPreview": false
      },
      "updatedAt": "2026-05-13T12:18:22Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

GET /results/{resultId}/fanout-sources

OpenAI web-search enabled runs produce third-party citations and grounding web URLs that influence the recommended items. While a summary and a short preview are embedded directly inside the main snapshot payload, you can query this endpoint to retrieve the complete, paginated list of all extracted fanout sources.

Query Parameters

Example Response (200 OK)

{
  "data": [
    {
      "id": "src_1",
      "rank": 1,
      "url": "https://stripe.com/us/payment-method/mobilepay",
      "domain": "stripe.com",
      "title": "MobilePay Support on Stripe",
      "query": "Stripe Denmark supported payment methods Klarna availability MobilePay",
      "sourceType": "web_search"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

System Status & Engines

FullMention provides public, unauthenticated health and status endpoints to track system and external AI engine availability. Use these to check whether external providers (such as OpenAI's batch services) are operating stably.

GET /status

Returns the unified operational status of internal systems (API, worker) and external engine providers.

GET /engines/status

An alias endpoint that returns the identical system and engine availability payload for developer convenience.

Caching & Timeout Rules

To ensure peak API performance and guard against high-traffic load, both endpoints implement an in-memory caching mechanism. The dynamic check to external APIs (e.g. OpenAI's public status API) is cached for 60 seconds.

Additionally, external network requests are guarded by a 2-second timeout. If the request to a provider's status API hangs or fails, the endpoint returns a cached or fallback operational state immediately rather than blocking.

Response Fields

Example Response (200 OK)

{
  "data": {
    "status": "operational",
    "services": {
      "api": "operational",
      "worker": "operational"
    },
    "engines": {
      "openai": {
        "status": "operational",
        "message": "OpenAI: All Systems Operational"
      },
      "openaiMini": {
        "status": "operational",
        "message": "OpenAI: All Systems Operational"
      },
      "gemini": {
        "status": "operational",
        "message": "Gemini Vertex AI systems are fully operational."
      }
    }
  },
  "meta": {
    "requestId": "req_8471203bca",
    "timestamp": "2026-05-21T10:52:00.000Z"
  }
}

Webhooks

Webhooks allow integrations to receive asynchronous run lifecycle events without polling. When configured, FullMention will send HTTP POST payloads directly to your endpoint when runs finish or quota is low.

Supported Events

• run.completed: Triggered when a tracking run successfully finishes and at least one execution produced snapshot data.
• run.failed: Triggered when a run fails without producing any usable recommendation snapshots.
• quota.low: Triggered when your remaining quota drops below a configured threshold.

Example Payload (run.completed)

{
  "id": "evt_123",
  "type": "run.completed",
  "createdAt": "2026-05-13T12:18:22Z",
  "data": {
    "runId": "run_555",
    "status": "success",
    "failureSummary": {
      "failedEngineExecutions": 3,
      "emptyEngineExecutions": 2
    }
  }
}

Webhook Security & Signing

All webhook requests include a signature header (e.g. FullMention-Signature) calculated using your endpoint's signing secret and the request body. Always verify this signature in your endpoints to prevent spoofing.

Error Format

Errors use a consistent JSON format with structured codes and unique request IDs for debugging.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Insufficient quota to execute this run.",
    "requestId": "req_abc123"
  }
}

Best Practices

• Persist Downstream: FullMention only maintains the *latest snapshot* of query recommendations. If you need history, trend analysis, or SOV metrics over time, you should store fetched snapshot data locally.
• Do Not Poll Aggressively: Snapshot updates only happen when runs successfully complete. Avoid calling /results/latest in rapid loops; instead, fetch after a completed run callback or on a regular hourly/daily schedule.
• Handle Retries Gracefully: Implement exponential backoff for transient 5xx errors. Do not retry indefinitely on rate limits or quota depletion.

Example cURL

Get up and running with a simple terminal command:

curl -X GET "https://api.fullmention.com/v1/results/latest?tags=client:acme" \
  -H "Authorization: Bearer fm_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

Support & Integration QA

If you encounter issues or have questions regarding integrations:

• Check that your API key is correctly structured and active.
• Always log the requestId from error payloads for support review.
• Email our engineering desk at hi@fullmention.com.