POST /v1/discover

Generate up to 50 query candidates that real users ask about a brand. Each candidate is scored 0–1 and tagged with intent (informational, commercial, comparison, transactional). Use the output to seed /v1/check calls or to schedule a watch.

POST/v1/discover— Discover query candidates for a brand

Pricing — 165 credits / call

Flat per-call price. Cache is 7-day per (brand + industry + language); cache hits still cost 165 credits because the value is the answer, not the upstream call. The result set is an LLM-curated set of candidates derived from a our web search infrastructure /search pass over recent web content + an Anthropic theme-extraction pass.

Quickstart

bash

curl https://api.mentionsapi.com/v1/discover \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "HubSpot",
    "industry": "CRM software",
    "count": 10
  }'

Request body

Field	Type	Description
`brand` required	`string`	Brand name. 1–120 chars. Example: 'HubSpot'.
`industry`optional	`string`	Industry or category hint, used to narrow our web search infrastructure's web search. 1–120 chars. Example: 'CRM software'.
`count`optional	`number`	Number of candidates to return. 1–100. Default 50. Default: `50`
`language`optional	`string`	ISO language code passed to our web search infrastructure `/search`. 2–8 chars. Defaults to 'en'. Default: `en`

Response

json

{
  "request_id": "req_01JBQ2K8H...",
  "brand": "HubSpot",
  "industry": "CRM software",
  "candidates": [
    {
      "query": "best CRM for small business",
      "intent": "comparison",
      "score": 0.92,
      "rationale": "Common comparison query — HubSpot frequently surfaced in answers.",
      "ai_search_volume": 2400,
      "ai_search_trend": [
        { "month": "2026-04", "volume": 1900 },
        { "month": "2026-05", "volume": 2000 },
        { "month": "2026-06", "volume": 2100 },
        { "month": "2026-07", "volume": 2200 },
        { "month": "2026-08", "volume": 2300 },
        { "month": "2026-09", "volume": 2400 }
      ]
    },
    {
      "query": "HubSpot vs Salesforce",
      "intent": "comparison",
      "score": 0.88,
      "rationale": "Direct competitor query, high commercial intent.",
      "ai_search_volume": 880,
      "ai_search_trend": [
        { "month": "2026-07", "volume": 720 },
        { "month": "2026-08", "volume": 810 },
        { "month": "2026-09", "volume": 880 }
      ]
    },
    {
      "query": "HubSpot CRM free tier features",
      "intent": "informational",
      "score": 0.81,
      "rationale": "Brand-specific feature query.",
      "ai_search_volume": null
    }
  ],
  "total": 10,
  "cached": false,
  "cost_cents": 165,
  "balance_after_cents": 9835
}

Each candidate carries a rationale field (≤140 chars) so you can audit why it surfaced. The cached flag tells you whether this was a fresh our web search infrastructure pass or an L2 KV hit.

Candidate fields

Field	Type	Description
`query`optional	`string`	The prompt to track.
`intent`optional	`'informational' \| 'commercial' \| 'comparison' \| 'transactional'`	Intent class.
`score`optional	`number`	Heuristic relevance + commercial-value score, 0–1. Used as the tiebreaker in the ordering.
`rationale`optional	`string`	Why this candidate surfaced (≤140 chars).
`ai_search_volume`optional	`number \| null`	Estimated number of AI-assistant prompts per month matching this exact query. null when no estimate is available — the lookup is best-effort and a null never fails the call.
`ai_search_trend`optional	`{ month: "YYYY-MM", volume: number }[]`	Up to the last 6 months of AI search volume for this query, oldest first. Omitted when no history is available.

Ordering

Candidates are sorted by ai_search_volume descending — the prompts with the most AI-search demand come first — with null volumes last and score as the tiebreaker. Take the top of the list when you want the queries that are actually being asked, not just the ones that read well.

Error codes

Field	Type	Description
`400 invalid_request`optional	`Error`	Schema validation failed.
`402 insufficient_balance`optional	`Error`	Balance below 165 credits.
`503 discover_no_context`optional	`Error`	our web search infrastructure returned 0 snippets for this brand+industry. Refunded automatically; try again with a more specific industry hint.

Full error catalog at /docs/errors.