FullMention Public API Reference

01. Overview

FullMention tracks how AI assistants (such as OpenAI's ChatGPT and Google Gemini) recommend brands, websites, products, services, platforms, and related entities for real user-style recommendation queries.

The API is built around AI recommendation snapshots. Rather than forcing you to poll and track simple keywords one-by-one, you attach descriptive tags to your keywords, trigger asynchronous batch runs for matching scopes, and pull the consolidated, structured findings.

Proprietary Extraction: FullMention does not expose its internal prompt or extraction methods. Treat returned data and mappings as proprietary AI recommendation intelligence.

02. Authentication

Authenticate your API requests by sending your API key as a Bearer token in the standard HTTP Authorization header.

 Required Header 
 Authorization: Bearer fm_live_YOUR_API_KEY
Content-Type: application/json 

Live Keys

fm_live_xxxxxxxxx

Live keys execute production queries, consume real account credits, and return live data. During private beta, invitations are required to access live mode.

Test Keys

fm_test_xxxxxxxxx

Test keys let you integrate sandbox environments. Sandbox execution uses mock fixtures, does not charge Stripe accounts, and is isolated.

03. Core Concepts

Keyword

A keyword represents a search query intent in a specific geographical market context. Includes fields such as keyword, countryCode, languageCode, and location.

Run

An asynchronous background job submitted to execute FullMention's recommendation engine for a filtered set of keywords. Runs are processed using provider batch pipelines to reduce cost.

Result Snapshot

The latest completed AI recommendation result for a keyword and engine. The API is snapshot-first; to capture historic timelines, integrations should fetch latest results and archive downstream.

Method Version

Every result snapshot includes a methodVersion field (e.g. "rec_snapshot_v1"). This identifies the internal prompt and extraction strategy without exposing prompts. If the version changes, results and extraction characteristics might also evolve.

04. Idempotency

Recommended

To prevent duplicate creation of resources (such as duplicate runs or keywords) due to network retries, FullMention supports idempotency.

Send an Idempotency-Key header containing a unique UUID key with any mutation request (POST, PATCH, or DELETE).

 Example cURL with Idempotency Key 
 curl -X POST "https://api.fullmention.com/v1/runs" \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Idempotency-Key: 3f6f6b8d-6f10-4bcf-9f4d-7a0a9c9e2c2a" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["client:acme"]}' 

05. Quota & Rate Limits

Quota & Credits Math

Every successful API response includes custom quota tracking headers. Quota represents monthly execution credits.

X-Quota-Limit: 1000

X-Quota-Used: 120

X-Quota-Extra: 50

X-Quota-Remaining: 930

Cost Logic:

1 Successful Engine Execution = 1 Base Credit. A selected engine executed for a keyword only costs 1 credit if it succeeds and produces recommendation snapshot data. Failed, empty, or API provider-error executions are not charged.
Optional OpenAI Web Fanout = +1 Fanout Credit. If web-search fanout is enabled and produces sources, it costs an additional credit. If fanout fails or is empty, only the base credit is charged.

Rate Limits

Rate limits protect API throughput volume. These are distinct from quota limits. Standard headers:

X-RateLimit-Limit: 60

X-RateLimit-Remaining: 57

X-RateLimit-Reset: 1778673600

Resource Path	Default Limits
/keywords	60 requests/minute
/tags	120 requests/minute
/runs	10 requests/minute
/results	60 requests/minute

Request & Run Caps (V1)

Max Keywords / Run 1,000

Max Engines / Keyword 2

Max Executions / Run 2,000

Max Keywords / Request 500

Max Tags / Keyword 25

Max Tag Length 80 chars

06. Test Mode & Sandbox

FullMention provides a robust test-key integration mode. Requests initiated with a test key (fm_test_...) operate inside an isolated sandbox environment:

Demo execution: Runs are simulated or fixture-backed (returns `executionMode: "demo"` in payloads) instead of submitting live jobs.
Free sandbox quota: Sandbox operations do not consume live plan credits or incur payment charges.
Public Demo Dataset: Read-only access to preset keywords and results for quick onboarding.
Writable Sandbox: Sandbox users can write, edit, delete, and trigger runs, isolated to their test key. Sandbox data may be reset nightly.

07. Tag Filtering

List endpoints that accept tag filters use OR matching by default:

GET /v1/keywords?tags=client:acme,market:dk

This returns keywords carrying either the client:acme tag OR the market:dk tag.

To request AND matching, supply the tagMode=and parameter:

GET /v1/keywords?tags=client:acme,market:dk&tagMode=and

This matches only keywords that hold BOTH tags simultaneously.

08. Keywords Reference

Create, retrieve, update, and soft-delete tracked search queries.

GET

/keywords

List all keywords created in your account. Supports cursor pagination.

Query Parameters

Name	Type	Description
tags	string	Comma-separated tags scope filter.
tagMode	string	Match logic: `and` or `or`.
limit	number	Max records per page. Defaults to 100.
cursor	string	Cursor offset from `meta.nextCursor`.

List Keywords

curl "https://api.fullmention.com/v1/keywords?tags=client:acme&limit=1" \
  -H "Authorization: Bearer fm_live_xxx"

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

POST

/keywords

Add one or more keywords. Creating keywords is idempotent; duplicate intents in the same market return the existing record.

Create Keywords

curl -X POST "https://api.fullmention.com/v1/keywords" \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": [
      {
        "keyword": "seo tool",
        "country": "Denmark",
        "countryCode": "DK",
        "language": "Danish",
        "languageCode": "da",
        "location": "Copenhagen",
        "engines": ["openai"],
        "tags": ["client:acme", "market:dk"]
      }
    ]
  }'

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

PATCH

/keywords/:keywordId

Update specific fields or tags. Changing intent details affects future runs.

Update Keyword

curl -X PATCH "https://api.fullmention.com/v1/keywords/kw_12345" \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "seo software",
    "tags": ["client:acme", "priority:high"]
  }'

{
  "data": {
    "id": "kw_12345",
    "keyword": "seo software",
    "country": "Denmark",
    "countryCode": "DK",
    "language": "Danish",
    "languageCode": "da",
    "location": "Copenhagen",
    "engines": ["openai"],
    "tags": ["client:acme", "priority:high"],
    "active": true,
    "updatedAt": "2026-05-13T13:00:00Z"
  },
  "meta": {}
}

DELETE

/keywords/:keywordId

Soft-deactivates a keyword, hiding its historic results and de-scheduling it from future runs.

Delete Keyword

curl -X DELETE "https://api.fullmention.com/v1/keywords/kw_12345" \
  -H "Authorization: Bearer fm_live_xxx"

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

09. Tags Reference

Query active tags utilized inside your account.

GET

/tags

Retrieve list of tags currently attached to active keywords. Returns counts.

List Tags

curl "https://api.fullmention.com/v1/tags?prefix=client:" \
  -H "Authorization: Bearer fm_live_xxx"

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

10. Runs Reference

Submit cost estimates and trigger asynchronous double-engine processing jobs.

POST

/runs/estimate

Calculate keyword scopes and credit metrics for a tag filter combination without starting a job.

Estimate Run Cost

curl -X POST "https://api.fullmention.com/v1/runs/estimate" \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["client:acme", "market:dk"],
    "tagMode": "or",
    "options": {
      "fanout": true
    }
  }'

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

POST

/runs

Start an asynchronous batch execution. Only one active run with overlapping scope is permitted. Returns 409 Conflict if a matching run is processing.

Trigger Asynchronous Run

curl -X POST "https://api.fullmention.com/v1/runs" \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run_req_12345" \
  -d '{
    "tags": ["client:acme", "market:dk"],
    "tagMode": "or",
    "options": {
      "fanout": true
    }
  }'

{
  "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",
    "failureSummary": null,
    "createdAt": "2026-05-13T12:15:00Z",
    "startedAt": null,
    "completedAt": null
  },
  "meta": {}
}

GET

/runs

List historical runs created in your workspace.

List Runs

curl "https://api.fullmention.com/v1/runs?status=success&limit=1" \
  -H "Authorization: Bearer fm_live_xxx"

{
  "data": [
    {
      "id": "run_555",
      "status": "success",
      "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",
      "failureSummary": {
        "failedEngineExecutions": 3,
        "emptyEngineExecutions": 2
      },
      "createdAt": "2026-05-13T12:15:00Z",
      "startedAt": "2026-05-13T12:15:00Z",
      "completedAt": "2026-05-13T12:18:22Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

GET

/runs/:runId

Check status, timeline stamps, and results counters of a particular run.

Get Single Run

curl "https://api.fullmention.com/v1/runs/run_555" \
  -H "Authorization: Bearer fm_live_xxx"

{
  "data": {
    "id": "run_555",
    "status": "success",
    "scope": {
      "tags": ["client:acme", "market:dk"],
      "tagMode": "or",
      "options": {
        "fanout": true
      }
    },
    "logicalKeywordCount": 42,
    "engineExecutionCount": 84,
    "fanoutExecutionCount": 42,
    "resultCount": 84,
    "estimatedBaseCreditCost": 84,
    "estimatedFanoutCreditCost": 42,
    "estimatedMaxCreditCost": 126,
    "executionMode": "batch",
    "failureSummary": {
      "failedEngineExecutions": 3,
      "emptyEngineExecutions": 2
    },
    "createdAt": "2026-05-13T12:15:00Z",
    "startedAt": "2026-05-13T12:15:00Z",
    "completedAt": "2026-05-13T12:18:22Z"
  },
  "meta": {}
}

11. Results Reference

Fetch processed structured findings and full web source attribution references.

GET

/results/latest

Get the latest completed snapshot records. OpenAI results include a small preview of web-search sources (fanoutSourcesPreview) for dashboard visual utility; to obtain the full list of web links, use the sub-resource endpoint.

Fetch Latest Snapshots

curl "https://api.fullmention.com/v1/results/latest?tags=client:acme&engine=openai&limit=1" \
  -H "Authorization: Bearer fm_live_xxx"

{
  "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_v1",
      "tags": ["client:acme", "market:dk"],
      "recommendations": [
        {
          "rank": 1,
          "name": "Ahrefs",
          "type": "brand",
          "description": "SEO platform known for backlink analysis, keyword research, and competitor research.",
          "popularProductsOrVariations": ["Site Explorer", "Rank Tracker"],
          "onlineAvailability": ["ahrefs.com"],
          "relatedEntities": ["Semrush", "Moz"],
          "websites": ["ahrefs.com"]
        }
      ],
      "entities": {
        "brands": ["Ahrefs", "Semrush"],
        "websites": ["ahrefs.com", "semrush.com"],
        "products": ["Site Explorer"],
        "categories": ["SEO software"]
      },
      "rankings": {
        "brands": ["Ahrefs"],
        "websites": ["ahrefs.com"]
      },
      "fanoutSummary": {
        "queryCount": 35,
        "sourceCount": 437,
        "previewSourceCount": 1,
        "hasMoreSources": true
      },
      "fanoutSourcesPreview": [
        {
          "rank": 1,
          "url": "https://stripe.com/us/payment-method/mobilepay",
          "domain": "stripe.com",
          "title": null,
          "query": "Stripe Denmark MobilePay support",
          "sourceType": "web_search"
        }
      ],
      "metrics": {
        "recommendationCount": 1,
        "brandCount": 1,
        "websiteCount": 1,
        "fanoutQueryCount": 35,
        "fanoutSourceCount": 437
      },
      "updatedAt": "2026-05-13T12:18:22Z"
    }
  ],
  "meta": {
    "nextCursor": null
  }
}

GET

/results/:resultId/fanout-sources

Fetch complete, paginated lists of evolved web search sources referenced by OpenAI batch runs. Returns 422 fanout_not_enabled if the source run opted out of fanout.

Get Full Fanout Sources

curl "https://api.fullmention.com/v1/results/res_123/fanout-sources?limit=1" \
  -H "Authorization: Bearer fm_live_xxx"

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

12. Webhooks Reference

Subscribe to automated completion events to bypass heavy API polling loops.

Configure HTTP endpoint endpoints to consume push notification hooks when asynchronous jobs succeed, fail, or credit balances deplete.

GET /webhooks

POST /webhooks

PATCH /webhooks/:id

DEL /webhooks/:id

Supported Event Types

run.completed - Run finished and results are ready.
run.failed - Run encountered unexpected fatal pipeline exceptions.
quota.low - Remaining monthly credit allowance fell below threshold boundaries.

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

13. Recommendation Object

Each snapshot result contains an array of normalized recommendation objects structured sequentially according to extracted recommendation ranking.

Field	Type	Description
rank	number	Extraction order sequence rank, beginning at 1.
name	string	Captured Brand, Product, Platform, or Vendor name.
type	string	One of: `brand`, `product`, `service`, `website`, `tool`, `platform`, `provider`, `category`, `marketplace`, or `local_provider`.
description	string	Brief context statement regarding the recommendation.
popularProductsOrVariations	string[]	Identified plans, sub-products, or key featured features.
onlineAvailability	string[]	Extracted signup page URLs, retailers, or directories.
relatedEntities	string[]	Alternatives or related brands extracted concurrently.
websites	string[]	Normalized official domains compiled by mapping signals.

14. Fanout Source Object

Fanout records represent external web publications, citations, reviews, and links analyzed by web-search-enabled engines to compile recommendation results.

Field	Type	Description
rank	number	Observation index order inside the returned fanout array.
id	string	Unique row ID assigned in paginated listings.
url	string	Exact target URL with tracking parameters stripped where possible.
domain	string	Normalized clean root publisher domain (e.g. `stripe.com`).
title	string \| null	Document title when captured.
query	string \| null	Underlying engine search query triggered to surface this source.
sourceType	string	Observation origin origin. Defaults to `web_search`.

15. Errors Reference

API failures return standard HTTP status code bounds accompanied by descriptive structured error envelopes.

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

Common Error Codes

invalid_payload RequestBody fails standard validation checks.

quota_exceeded Low workspace balance for matching run estimation.

run_already_processing Overlapping active scope execution is ongoing.

idempotency_conflict Conflicting mutations match key retry logic.

16. Recommended Integration Flow

Maximize execution efficiency and avoid unnecessary resource consumption by building your applications around this asynchronous pipeline:

Add Tracked Keywords

Post keyword intents categorized using filters (e.g. client:acme, market:dk).

Estimate Run Cost

Before initiating jobs, query the estimate endpoint to ensure matching keyword counts and credit capacities align.

Trigger Batch Job

Post keyword tags to start asynchronous processing. Returns a run ID immediately.

Poll or Receive Webhooks

Poll the run status endpoint with reasonable backoff, or subscribe endpoint handlers to run.completed webhooks.

Fetch Structured Snapshots

Once successfully completed, query the latest snapshots endpoint to retrieve structured rankings and competitor mappings.

Developer API Portal

01. Overview

02. Authentication

Live Keys

Test Keys

03. Core Concepts

Keyword

Tags

Run

Result Snapshot

Method Version

04. Idempotency

05. Quota & Rate Limits

Quota & Credits Math

Cost Logic:

Rate Limits

Request & Run Caps (V1)

06. Test Mode & Sandbox

07. Tag Filtering

08. Keywords Reference

/keywords

Query Parameters

/keywords

/keywords/:keywordId

/keywords/:keywordId

09. Tags Reference

/tags

10. Runs Reference

/runs/estimate

/runs

/runs

/runs/:runId

11. Results Reference

/results/latest

/results/:resultId/fanout-sources

12. Webhooks Reference

Supported Event Types

13. Recommendation Object

14. Fanout Source Object

15. Errors Reference

Common Error Codes

16. Recommended Integration Flow

Add Tracked Keywords

Estimate Run Cost

Trigger Batch Job

Poll or Receive Webhooks

Fetch Structured Snapshots