# POST /v1/ai/visibility

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

**Credits:** 10 credits per call.

**Timeout:** 60s

## Parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `domain` | string | yes | — | Domain to check AI-assistant mentions for (bare hostname, lowercased). Required, max 255 chars, no spaces. |
| `providers` | array | no | ["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 | no | "week" | One of: day, week. Optional, default "week". |
| `date_from` | string | no | — | ISO YYYY-MM-DD, inclusive. Optional, default 90 days ago. |
| `date_to` | string | no | — | ISO YYYY-MM-DD, inclusive. Optional, default today. |

## Request

```http
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.

```json
{
  "id": "ai_v_owpw3xxmdoiznmbtpenu6eto",
  "request_id": "req_5nwoa3qs4rbo7bphlndg26foaa",
  "object": "ai_visibility",
  "created_at": "2026-08-09T08:28:43Z",
  "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.

| Field | Description |
| --- | --- |
| `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. |