POST /v1/extract_brands

Pass any text and an optional brand list; get back the same mentions shape /v1/ask produces. No LLM round-trip — useful for batch-processing existing content.

Legacy endpoint. This documents an older surface kept for back-compat with existing integrations. New integrations should use /v1/check instead — see the quickstart for the modern API.

POST/v1/extract_brands— Extract brand mentions from arbitrary text

Request body

Field	Type	Description
`text` required	`string`	The text to scan. 1–50,000 characters.
`track_brands`optional	`string[]`	Brand names to look for. Max 50 entries, each 1–80 characters. Omit for automatic extraction (all recognizable brands).
`source_provider`optional	`'openai' \| 'anthropic' \| 'gemini' \| 'perplexity' \| 'unknown'`	Tag the call with the originating provider for analytics. Defaults to "unknown", in which case the returned mentions omit the provider field. Default: `'unknown'`

Example request

bash

curl https://api.mentionsapi.com/v1/extract_brands \
  -H "Authorization: Bearer $MENTIONSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "When choosing a vector database, Qdrant and Weaviate are the most-recommended open-source options...",
    "track_brands": ["Qdrant", "Weaviate", "Pinecone"]
  }'

Response

Field	Type	Description
`request_id`optional	`string`	Unique id for this call.
`mentions`optional	`BrandMention[]`	One entry per matched brand occurrence: { brand, rank (1-indexed), sentiment, context }. If source_provider is set to a real provider, each entry also includes provider.
`usage`optional	`{ billable_units: number, latency_ms: number }`	Latency and a constant billable_units = 1. This endpoint does not draw against your credit balance at this time.

json

{
  "request_id": "a7f0…",
  "mentions": [
    { "brand": "Qdrant",   "rank": 1, "sentiment": "positive", "context": "Qdrant and Weaviate are the most-recommended…" },
    { "brand": "Weaviate", "rank": 2, "sentiment": "positive", "context": "Qdrant and Weaviate are the most-recommended…" }
  ],
  "usage": { "billable_units": 1, "latency_ms": 87 }
}

Use cases

Re-extract brands over historical /v1/ask archives within the 30-day window.
Process transcripts, support tickets, community posts, or scraped content.
Backfill a new competitor into your brand-monitoring setup without re-querying every prompt.

Response headers

Header	Description
X-RateLimit-Limit	Your plan's token-bucket capacity.
X-RateLimit-Remaining	Tokens remaining in the current window.
Retry-After	Seconds to wait before retrying. Only on `429`.

The unique call identifier is returned in the JSON body as request_id.

Errors

See the full Errors reference for payload shape and retry guidance.

Status	error.code	When	Recovery
400	`invalid_request`	Body failed Zod validation — e.g. empty `text`, text over 50,000 chars, or more than 50 entries in `track_brands`.	Fix the request payload. Inspect `error.details` for the field path.
401	`unauthorized`	Missing, malformed, or revoked `Authorization: Bearer` token.	Send a valid `lvk_live_…` or `lvk_test_…` key.
429	`rate_limited`	Per-key token-bucket rate limit exceeded.	Honor `Retry-After`. Use exponential backoff with jitter.
500	`internal_error`	Brand-extraction pipeline threw an unhandled exception.	Retry with backoff. If persistent, include `request_id` in support.