AI Visibility

REST endpoints for AI Visibility. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

Get latest AI visibility data

GET/v1/projects/{projectId}/ai-visibility

Get the latest AI visibility data for a project. Returns AI Visibility Scores, mention rates, and per-provider breakdowns for all competitors found across ChatGPT, Claude, and Gemini. Use this to understand how AI models perceive and recommend your brand vs competitors.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "lastUpdatedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "customer": {
        "domain": "mycompany.com",
        "mentionRate": 66.7,
        "avgRank": 2.5,
        "mentionCount": 6,
        "aiScore": 73,
        "perProvider": {
          "openai": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "claude": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "gemini": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          }
        }
      },
      "topCompetitor": {
        "domain": "competitor.com",
        "name": "Competitor Inc",
        "mentionRate": 88.9,
        "avgRank": 1.8
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 9,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "openaiAvgRank": 2,
          "claudeAvgRank": 1.7,
          "geminiAvgRank": 3,
          "overallAvgRank": 2.2,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68
        }
      ]
    }
  }
}

Fields

item — object

Field	Type	Description
`lastUpdatedAt`	`string`	When this data was last updated (ISO-8601)
`summary`	`object`	Summary statistics. See `item.summary`.

item.summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `item.summary.topCompetitor`.
`mentionRateGap`	`number`	Gap between customer and top competitor mention rate (negative means customer is behind)
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number`	Total queries executed (3 prompts x 3 providers = 9)
`totalEntries`	`number`	Total brand entries across all query results
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `item.summary.competitorRankings[]`.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number`	Mention rate as percentage (mentions / total queries * 100)
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Total number of mentions across all queries
`aiScore`	`number`	AI Visibility Score — weighted 0-100 composite score
`perProvider`	`object`	Per-provider breakdown. See `item.summary.customer.perProvider`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number`	Top competitor mention rate percentage
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

item.summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across all queries
`mentionRate`	`number`	Mention rate as percentage
`aiScore`	`number`	AI Visibility Score (0-100)

item.summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`project_not_found`	No `project` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get AI visibility check history

GET/v1/projects/{projectId}/ai-visibility/history

Get paginated history of AI visibility checks for a project. Each entry includes check timing and summary statistics with customer metrics, top competitor, and competitor rankings.

Returns · { items, pagination }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Required	Description
`page`	`number`		Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`		Number of items per page. Default `20`. Range `1`–`100`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/history?page=1&limit=20" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "checkId": "507f1f77bcf86cd799439011",
      "completedAt": "2026-03-15T10:00:00.000Z",
      "summary": {
        "customer": {
          "domain": "mycompany.com",
          "mentionRate": 66.7,
          "avgRank": 2.5,
          "mentionCount": 6,
          "aiScore": 73,
          "perProvider": {
            "openai": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            },
            "claude": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            },
            "gemini": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            }
          }
        },
        "topCompetitor": {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "mentionRate": 88.9,
          "avgRank": 1.8
        },
        "mentionRateGap": -22.2,
        "totalCompetitorsFound": 8,
        "totalQueries": 9,
        "totalEntries": 45,
        "competitorRankings": [
          {
            "domain": "competitor.com",
            "name": "Competitor Inc",
            "isOwn": false,
            "openaiAvgRank": 2,
            "claudeAvgRank": 1.7,
            "geminiAvgRank": 3,
            "overallAvgRank": 2.2,
            "mentionCount": 7,
            "mentionRate": 77.8,
            "aiScore": 68
          }
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Fields

items[] — each entry

Field	Type	Description
`checkId`	`string`	Check ID
`completedAt`	`string`	When this check completed (ISO-8601)
`summary`	`object`	Check summary statistics. See `items[].summary`.

pagination — object

Field	Type	Description
`page`	`number`	Current page number (1-indexed)
`limit`	`number`	Number of items per page
`total`	`number`	Total number of items across all pages
`totalPages`	`number`	Total number of pages
`hasMore`	`boolean`	Whether more pages exist after the current page

items[].summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `items[].summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `items[].summary.topCompetitor`.
`mentionRateGap`	`number`	Gap between customer and top competitor mention rate (negative means customer is behind)
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number`	Total queries executed (3 prompts x 3 providers = 9)
`totalEntries`	`number`	Total brand entries across all query results
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `items[].summary.competitorRankings[]`.

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number`	Mention rate as percentage (mentions / total queries * 100)
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Total number of mentions across all queries
`aiScore`	`number`	AI Visibility Score — weighted 0-100 composite score
`perProvider`	`object`	Per-provider breakdown. See `items[].summary.customer.perProvider`.

items[].summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number`	Top competitor mention rate percentage
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

items[].summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across all queries
`mentionRate`	`number`	Mention rate as percentage
`aiScore`	`number`	AI Visibility Score (0-100)

items[].summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

Paginated — pass page and limit query parameters and follow pagination.hasMore to page through the full set.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get AI visibility data for a specific check

GET/v1/projects/{projectId}/ai-visibility/history/{checkId}

Get full AI visibility data for a specific historical check, including per-competitor rankings across all three AI providers with mention rates and AI Visibility Scores.

Returns · { item }

Path parameters

Name	Type	Description
`checkId`	`string`	Check ID
`projectId`	`string`	Project ID

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/history/507f1f77bcf86cd799439012" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "checkId": "507f1f77bcf86cd799439011",
    "completedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "customer": {
        "domain": "mycompany.com",
        "mentionRate": 66.7,
        "avgRank": 2.5,
        "mentionCount": 6,
        "aiScore": 73,
        "perProvider": {
          "openai": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "claude": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "gemini": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          }
        }
      },
      "topCompetitor": {
        "domain": "competitor.com",
        "name": "Competitor Inc",
        "mentionRate": 88.9,
        "avgRank": 1.8
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 9,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "openaiAvgRank": 2,
          "claudeAvgRank": 1.7,
          "geminiAvgRank": 3,
          "overallAvgRank": 2.2,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68
        }
      ]
    },
    "competitors": [
      {
        "domain": "competitor.com",
        "name": "Competitor Inc",
        "isOwn": false,
        "openaiAvgRank": 2,
        "claudeAvgRank": 1.7,
        "geminiAvgRank": 3,
        "overallAvgRank": 2.2,
        "mentionCount": 7,
        "mentionRate": 77.8,
        "aiScore": 68
      }
    ]
  }
}

Fields

item — object

Field	Type	Description
`checkId`	`string`	Check ID
`completedAt`	`string`	When this check completed (ISO-8601)
`summary`	`object`	Check summary statistics. See `item.summary`.
`competitors`	`array<object>`	Per-competitor AI visibility rankings for this check. See `item.competitors[]`.

item.summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `item.summary.topCompetitor`.
`mentionRateGap`	`number`	Gap between customer and top competitor mention rate (negative means customer is behind)
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number`	Total queries executed (3 prompts x 3 providers = 9)
`totalEntries`	`number`	Total brand entries across all query results
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `item.summary.competitorRankings[]`.

item.competitors[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across all queries
`mentionRate`	`number`	Mention rate as percentage
`aiScore`	`number`	AI Visibility Score (0-100)

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number`	Mention rate as percentage (mentions / total queries * 100)
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Total number of mentions across all queries
`aiScore`	`number`	AI Visibility Score — weighted 0-100 composite score
`perProvider`	`object`	Per-provider breakdown. See `item.summary.customer.perProvider`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number`	Top competitor mention rate percentage
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

item.summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across all queries
`mentionRate`	`number`	Mention rate as percentage
`aiScore`	`number`	AI Visibility Score (0-100)

item.summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`check_not_found`	No `check` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get AI visibility trend data

GET/v1/projects/{projectId}/ai-visibility/trend

Get AI visibility trend data over time for chart visualization. Returns time-series data points with customer and top competitor mention rates and AI Visibility Scores. Optionally filter by date range or specific AI provider — the provider filter applies to mention rates only; the AI Visibility Score is a single weighted composite across all providers, so customerAiScore/topCompetitorAiScore are null when a provider filter is applied. Returns up to 200 data points — use dateFrom/dateTo to narrow the range for longer histories.

Returns · { items }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`dateFrom`	`string`	Start date for trend data (ISO-8601)
`dateTo`	`string`	End date for trend data (ISO-8601)
`provider`	`string`	Filter by AI provider. Omit to get aggregated trend across all providers. Values: `openai`, `claude`, `gemini`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/trend?dateFrom=2026-01-01&dateTo=2026-03-15&provider=openai" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "date": "2026-03-15T10:00:00.000Z",
      "customerMentionRate": 66.7,
      "topCompetitorMentionRate": 88.9,
      "topCompetitorDomain": "competitor.com",
      "gap": -22.2,
      "customerAiScore": 73,
      "topCompetitorAiScore": 85
    }
  ]
}

Field	Type	Description
`date`	`string`	Data point date (ISO-8601)
`customerMentionRate`	`number`	Customer mention rate percentage (0-100)
`topCompetitorMentionRate`	`number`	Top competitor mention rate percentage (0-100)
`topCompetitorDomain`	`string \| null`	Top competitor domain at this data point. Nullable.
`gap`	`number`	Gap between customer and top competitor (negative means customer is behind)
`customerAiScore`	`number \| null`	Customer AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists. Nullable.
`topCompetitorAiScore`	`number \| null`	Top competitor AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists. Nullable.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}