docs / endpoint

POST /v1/ai/visibility

How often AI assistants mention a domain, per provider, over time.

Credits: 10 credits per call. Timeout: 60s

Parameters

NameTypeRequiredDefaultDescription
domain string required — Domain to check AI-assistant mentions for (bare hostname, lowercased). Required, max 255 chars, no spaces.
providers array optional ["chatgpt", "perplexity", "gemini", "copilot", "lechat"] Optional, default all five (order preserved). Must be non-empty when present; unknown or internal-only lanes are rejected, never exposed. Array of: chatgpt, perplexity, gemini, copilot, lechat.
granularity string optional "week" One of: day, week. Optional, default "week".
date_from string optional — ISO YYYY-MM-DD, inclusive. Optional, default 90 days ago.
date_to string optional — ISO YYYY-MM-DD, inclusive. Optional, default today.

Request

→ requestPOST /v1/ai/visibility
POST /v1/ai/visibility HTTP/1.1
Authorization: Bearer sof_live_your_key_here
Content-Type: application/json

{
  "domain": "example.com",
  "providers": [
    "chatgpt",
    "perplexity"
  ],
  "date_from": "2026-06-01",
  "date_to": "2026-07-28",
  "granularity": "week"
}

Response

Wrapped in the standard envelope -- id, object, created_at, elapsed_ms, cache, credits -- documented once on The Contract. The body below is a real envelope with this endpoint's data shape; values vary per request, and a … marks an array cut short for display.

← response200
{
  "id": "ai_v_sn4jrhw5it6qdf24te2hicp7",
  "request_id": "req_mmnga7hv7bgkvoirgqfg4eruqm",
  "object": "ai_visibility",
  "created_at": "2026-08-09T07:21:48Z",
  "elapsed_ms": 180,
  "cache": "miss",
  "credits": {
    "charged": 10,
    "balance": 9857
  },
  "data": {
    "domain": "example.com",
    "providers": {
      "chatgpt": {
        "mentions": 41,
        "prompts_seen": 380,
        "avg_rank": 2.6,
        "avg_sentiment": 0.31,
        "series": [
          {
            "period": "2026-07-14",
            "mentions": 6,
            "prompts_seen": 55,
            "avg_rank": 2.2
          },
          {
            "period": "2026-07-21",
            "mentions": 9,
            "prompts_seen": 61,
            "avg_rank": 2.9
          }
        ]
      },
      "perplexity": {
        "mentions": 12,
        "prompts_seen": 140,
        "avg_rank": 3.4,
        "avg_sentiment": 0.12,
        "series": []
      }
    },
    "coverage": {
      "from": "2026-06-01",
      "observations": 520,
      "note": "mentions are drawn from prompts run through this API; not a census of all AI traffic"
    }
  }
}

Response fields

What each field in data (above) means.

FieldDescription
data.domain The domain you requested.
data.providers Per-provider mention stats, keyed by provider name (only the providers you requested).
data.providers.chatgpt Stats for one provider (chatgpt shown here; every requested provider has this same shape).
data.providers.chatgpt.mentions Number of times this domain was mentioned by this provider in the window.
data.providers.chatgpt.prompts_seen Number of prompts run through this provider in the window.
data.providers.chatgpt.avg_rank Average position of this domain's mention among an answer's cited sources, or null if never mentioned.
data.providers.chatgpt.avg_sentiment Average sentiment of mentions, roughly -1 (negative) to 1 (positive), or null if never mentioned.
data.providers.chatgpt.series Per-period breakdown, bucketed by the requested granularity (day or week).
data.providers.chatgpt.series[].period Start date of this bucket, YYYY-MM-DD.
data.providers.chatgpt.series[].mentions Mentions in this period.
data.providers.chatgpt.series[].prompts_seen Prompts run through this provider in this period.
data.providers.chatgpt.series[].avg_rank Average mention rank in this period, or null if none.
data.coverage How much of the AI-observation archive this response drew from.
data.coverage.from Start of the requested date window.
data.coverage.observations Number of prompts observed across all requested providers in the window.
data.coverage.note Caveat on what "mentions" means -- read the value itself for the exact wording.