POST /v1/compare

Head-to-head comparison of two brands (same query) or two queries (same brand) across all 4 LLM APIs. Returns per-provider mentions for each side plus a normalized delta percentage and a winner ('a' | 'b' | 'tie').

POST/v1/compare— Two-way delta between brands or queries

Pricing — $1.50 / call

Flat per-call price. Internally runs 8 LLM API calls (2 sides × 4 providers) plus delta math. Failures on any side trigger a proportional refund — if 0 of 4 providers succeed on side A, you only pay for side B.

Quickstart

bash

curl https://api.mentionsapi.com/v1/compare \
  -H "Authorization: Bearer lvk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best CRM for small business",
    "brand_a": "HubSpot",
    "brand_b": "Salesforce"
  }'

Request body

Three valid request shapes. Pick the one that matches the comparison you want:

Same query, two brands: { query, brand_a, brand_b }
Same brand, two queries: { query_a, query_b, brand }
Two queries × two brands: { query_a, query_b, brand_a, brand_b }

Field	Type	Description
`query`optional	`string`	1–500 chars. Required if query_a/query_b not provided.
`query_a / query_b`optional	`string`	1–500 chars each. Use these to compare two different queries.
`brand`optional	`string`	1–120 chars. Required if brand_a/brand_b not provided.
`brand_a / brand_b`optional	`string`	1–120 chars each. Use these to compare two different brands.
`mode`optional	`string`	'quick' (default — 4 LLM APIs) or 'perplexity_live' (UI scrape, both sides hit Perplexity).
`region`optional	`string`	Two-letter region code. 'us' default.

Response

json

{
  "request_id": "req_01JBQ2K8H...",
  "id": "cmp_a8d2c...",
  "mode": "compare",
  "query_a": "best CRM for small business",
  "query_b": "best CRM for small business",
  "brand_a": "HubSpot",
  "brand_b": "Salesforce",
  "providers": {
    "chatgpt": {
      "a": { "mentioned": true, "rank": 6, "context": "..." },
      "b": { "mentioned": true, "rank": 8, "context": "..." }
    },
    "claude": {
      "a": { "mentioned": true, "rank": 4, "context": "..." },
      "b": { "mentioned": false, "rank": null, "context": "" }
    }
  },
  "delta_pct": 28.57,
  "winner": "a",
  "interpretation": "HubSpot mentioned in 4 of 4 successful providers; Salesforce in 3 of 4. Average rank: HubSpot 5.0, Salesforce 7.5.",
  "citations": [
    {
      "url": "https://zapier.com/blog/best-crms-for-small-business/",
      "title": "Zapier — Best CRMs",
      "branding": null
    }
  ],
  "created_at": "2026-04-25T12:00:00Z",
  "duration_ms": 5210,
  "cost_cents": 150,
  "balance_after_cents": 9850
}

delta_pct is computed as (rate_a - rate_b) / max(rate_a, rate_b) × 100 where each rate is mentions / successful_providers. winner is 'a' | 'b' | 'tie' based on which side has the higher rate (or tie if rates are equal). The interpretation field is a plain-English summary safe to render to dashboards.

Error codes

Field	Type	Description
`400 invalid_request`optional	`Error`	Schema validation failed. Body includes details on which of the three valid shapes you tried to use.
`402 insufficient_balance`optional	`Error`	Balance below $1.50.
`429 rate_limited`optional	`Error`	Hit the per-key compare bucket. Retry-After header tells you when.

Full error catalog at /docs/errors.