FullMention Public API v2

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

FullMention is a simplified, stateless, asynchronous API designed to make it incredibly easy for developers to run AI reputation and visibility simulations. The API is entirely payload-driven: you send the keywords directly in the request, choose your parameters and engines, and poll or receive the results when they are ready.

Overview Highlights

• Stateless: No database CRUD endpoints required. You send your list of keywords directly in the payload.
• 24-Hour TTL Data Retention: All run data and results generated via the v2 API are temporary and are automatically deleted after exactly 24 hours. Developers should store results in their own database downstream.
• Inline Webhooks: Configure webhook callbacks per-run directly inside the POST body payload.

Authentication

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

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

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

Core Concepts

Integrations interact with two primary entities:

1. Run

An asynchronous processing job executing FullMention's proprietary AI recommendation extraction method across a list of keywords. Runs leverage provider batch systems (like OpenAI Batch) to secure a 50% discount on LLM tokens, meaning completion typically takes 5 to 15 minutes.

2. Result Snapshot

The structured outcome of a 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):

• 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.
• Pre-Sorted Order: The elements in these lists are strictly ordered by visibility prominence and AI association weight. Do not sort these lists alphabetically, as that discards the visibility intelligence.

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 per keyword): Costs 1 base credit. Lightning-fast basic recommendation snapshot. Does not support search fanout in V2.
• GPT-5-mini (1 base + 1 fanout = 2 credits per keyword): Costs 1 base credit plus a lightweight +1 credit fanout add-on if requested. Best value for high-volume standard web search tracking.
• GPT-5 (1 base + 9 fanout = 10 credits per keyword): Costs 1 base credit plus a premium +9 credit fanout add-on. Essential for premium localized market audits with rich inline citation links.

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 Budgets

API responses include standard headers describing your remaining request budget. Standard budgets:

• v2 Runs API: 10 requests/minute
• v2 Results/Fanout API: 60 requests/minute

Idempotency

For mutation endpoints (like POST /runs), 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.

Trigger a Run

Submit a list of keywords to run across selected engines with global market parameters. This is an asynchronous operation.

Request Body Schema

Example Request Payload

{
  "keywords": ["running shoes", "trail shoes"],
  "engines": ["openai-mini", "gemini"],
  "country": "Denmark",
  "language": "Danish",
  "location": "Aarhus",
  "options": {
    "fanout": false
  },
  "webhookUrl": "https://api.mybrand.com/webhooks/fullmention"
}

Response (202 Accepted)

{
  "id": "run_98765xyz",
  "status": "queued",
  "progress": {
    "status": "queued",
    "totalRequests": 4,
    "completedRequests": 0,
    "failedRequests": 0,
    "percentage": 0
  },
  "estimatedCredits": 4,
  "statusUrl": "https://api.fullmention.com/v2/runs/run_98765xyz",
  "webhookUrl": "https://api.mybrand.com/webhooks/fullmention",
  "expiresAt": "2026-06-11T20:41:00.000Z",
  "createdAt": "2026-06-10T20:41:00.000Z"
}

Get Run Status & Results

Check the current status of a run. If the run is finished, it returns the complete results payload.

Response (200 OK - Run Still In Progress)

{
  "id": "run_98765xyz",
  "status": "processing",
  "progress": {
    "status": "processing",
    "totalRequests": 4,
    "completedRequests": 2,
    "failedRequests": 0,
    "percentage": 50
  },
  "estimatedCredits": 4,
  "createdAt": "2026-06-10T20:41:00.000Z",
  "expiresAt": "2026-06-11T20:41:00.000Z"
}

Response (200 OK - Run Succeeded)

{
  "id": "run_98765xyz",
  "status": "success",
  "progress": {
    "status": "success",
    "totalRequests": 4,
    "completedRequests": 4,
    "failedRequests": 0,
    "percentage": 100
  },
  "estimatedCredits": 4,
  "createdAt": "2026-06-10T20:41:00.000Z",
  "completedAt": "2026-06-10T20:52:12.000Z",
  "expiresAt": "2026-06-11T20:41:00.000Z",
  "results": [
    {
      "id": "res_kw1_openai_mini",
      "keyword": "running shoes",
      "engine": "openai-mini",
      "country": "Denmark",
      "language": "Danish",
      "location": "Aarhus",
      "description": "Here is an overview of popular running shoes in Denmark based on recommendations...",
      "categorySuggestions": ["Sports", "Running"],
      "brandRankings": [
        { "position": 1, "name": "Nike" },
        { "position": 2, "name": "Asics" }
      ],
      "websiteRankings": [
        { "position": 1, "domain": "runningshoegeeks.com" },
        { "position": 2, "domain": "runningx.com" }
      ],
      "productRankings": [
        { "position": 1, "name": "Nike Pegasus 40" }
      ],
      "metrics": {
        "brandCount": 2,
        "websiteCount": 2,
        "productCount": 1,
        "fanoutQueryCount": 0,
        "fanoutSourceCount": 0
      },
      "updatedAt": "2026-06-10T20:52:08.000Z"
    }
  ]
}

Retrieve Fanout Sources

If fanout was enabled, retrieve the full paginated list of crawl/search citation sources for a specific result snapshot.

Query Parameters

Response (200 OK)

{
  "data": [
    {
      "domain": "runningshoegeeks.com",
      "url": "https://runningshoegeeks.com/guides/running-shoes-guide",
      "title": "The Ultimate Guide to Choosing Running Shoes - Running Shoe Geeks",
      "snippet": "Read about how to choose the right running shoes and see the most popular products...",
      "crawledAt": "2026-06-10T20:51:44.000Z"
    }
  ],
  "meta": {
    "nextCursor": "eyJza2lwIjoxfQ=="
  }
}

Get Available Quota

Retrieve the credit quota and billing status details for your account.

Response (200 OK)

{
  "data": {
    "limit": 5000,
    "used": 1200,
    "extra": 500,
    "remaining": 4300
  },
  "meta": {
    "requestId": "req_1a2b3c4d5e",
    "timestamp": "2026-06-10T20:41:00.000Z"
  }
}

Health Check

Check system and application environment health details.

Response (200 OK)

{
  "data": {
    "status": "ok",
    "service": "fullmention-api",
    "environment": "production",
    "region": "europe-west1",
    "version": "0.1.0"
  },
  "meta": {
    "requestId": "req_health123",
    "timestamp": "2026-06-10T20:41:00.000Z"
  }
}

Get System Status

Get dynamic status indicators for underlying search engines and FullMention services.

Response (200 OK)

{
  "data": {
    "status": "operational",
    "services": {
      "api": "operational",
      "worker": "operational"
    },
    "engines": {
      "openai": {
        "status": "operational",
        "message": "Operational"
      },
      "openaiMini": {
        "status": "operational",
        "message": "Operational"
      },
      "gemini": {
        "status": "operational",
        "message": "Operational"
      }
    }
  },
  "meta": {
    "requestId": "req_status123",
    "timestamp": "2026-06-10T20:41:00.000Z"
  }
}

Webhooks

FullMention v2 supports inline webhooks. By supplying a webhookUrl when calling POST /runs, FullMention will automatically issue an HTTP POST callback as soon as the run is fully processed.

Webhook Signature Verification

Every webhook request contains an X-FullMention-Signature header. This is a cryptographic HMAC-SHA256 signature calculated on the raw request body payload using your account's webhook signing secret.

Signature Header Format

X-FullMention-Signature: sha256=HEX_HMAC_SHA256_VALUE

Webhook Body Example

{
  "event": "run.completed",
  "timestamp": "2026-06-10T20:52:13.000Z",
  "data": {
    "id": "run_98765xyz",
    "status": "success",
    "progress": {
      "status": "success",
      "totalRequests": 4,
      "completedRequests": 4,
      "failedRequests": 0,
      "percentage": 100
    },
    "estimatedCredits": 4,
    "createdAt": "2026-06-10T20:41:00.000Z",
    "completedAt": "2026-06-10T20:52:12.000Z",
    "expiresAt": "2026-06-11T20:41:00.000Z",
    "results": [
      {
        "id": "res_kw1_openai_mini",
        "keyword": "running shoes",
        "engine": "openai-mini",
        "country": "Denmark",
        "language": "Danish",
        "location": "Aarhus",
        "description": "Here is an overview of popular running shoes in Denmark based on recommendations...",
        "brandRankings": [
          { "position": 1, "name": "Nike" }
        ],
        "websiteRankings": [
          { "position": 1, "domain": "runningshoegeeks.com" }
        ],
        "productRankings": [],
        "metrics": {
          "brandCount": 1,
          "websiteCount": 1,
          "productCount": 0,
          "fanoutQueryCount": 0,
          "fanoutSourceCount": 0
        },
        "updatedAt": "2026-06-10T20:52:08.000Z"
      }
    ]
  }
}

Error Format

If an API request fails, the server returns an appropriate HTTP status code along with a structured JSON error body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has insufficient credits to trigger a run with this scope.",
    "details": null
  }
}

Common Error Codes

Example cURL

Trigger a new stateless tracking run using cURL:

curl -X POST https://api.fullmention.com/v2/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d" \
  -d '{
    "keywords": ["running shoes", "trail shoes"],
    "engines": ["openai-mini", "gemini"],
    "country": "Denmark",
    "language": "Danish",
    "options": {
      "fanout": true
    },
    "webhookUrl": "https://api.mybrand.com/webhooks"
  }'