Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

Scoped AI Traffic aggregate widgets.

GET
/api/v1/ai-visibility/ai-traffic/summary
curl --request GET \
  --url 'https://sitechecker.pro/api/v1/ai-visibility/ai-traffic/summary?project_id=12345&date_from=2026-02-19&date_to=2026-05-19&scope=overview&include_comparison=true' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
project_id
required
integer
Example
12345

Project ID.

date_from
required
string format: date
Example
2026-02-19

Start of the monitoring period (inclusive), ISO date (UTC).

date_to
required
string format: date
Example
2026-05-19

End of the monitoring period (inclusive), ISO date (UTC).

scope
required
string
Allowed values: overview ai_sources
include_comparison
boolean
default: true

Responses

Section titled “Responses”

200

Section titled “200”

AI Traffic summary widgets

Media typeapplication/json
object
data
One of:

Summary data payload for scope=overview: the Channel Performance widgets from the live GA4 channel computation. ai_traffic mirrors the AI Chats channel figures.

object
ai_traffic

Shared AI Traffic metric block. engagement_rate is the exact GA4 complement of bounce_rate (1 - bounce_rate). The *_change fields (percentage deltas vs the previous period) are present only when include_comparison=true and may be null when the previous value is zero.

object
sessions

OpenAPI response schemas for the AI Traffic block of the AI Visibility Public API (summary / history / pages / filter-values). Property names are string literals that mirror the exact keys produced by the AI Traffic services, so the documented contract and the runtime response shapes stay in lock-step. The generic envelope schemas (PaginationMeta, ErrorEnvelope) live in PublicApiSchemas and are referenced by ref here.

integer
key_events
integer
session_key_event_rate
number format: float
bounce_rate

Fraction 0..1.

number format: float
engagement_rate

Fraction 0..1 (1 - bounce_rate).

number format: float
average_session_duration_seconds
number format: float
sessions_change
number format: float
nullable
key_events_change
number format: float
nullable
session_key_event_rate_change
number format: float
nullable
bounce_rate_change
number format: float
nullable
engagement_rate_change
number format: float
nullable
average_session_duration_change
number format: float
nullable
total_metrics

Shared AI Traffic metric block. engagement_rate is the exact GA4 complement of bounce_rate (1 - bounce_rate). The *_change fields (percentage deltas vs the previous period) are present only when include_comparison=true and may be null when the previous value is zero.

object
sessions

OpenAPI response schemas for the AI Traffic block of the AI Visibility Public API (summary / history / pages / filter-values). Property names are string literals that mirror the exact keys produced by the AI Traffic services, so the documented contract and the runtime response shapes stay in lock-step. The generic envelope schemas (PaginationMeta, ErrorEnvelope) live in PublicApiSchemas and are referenced by ref here.

integer
key_events
integer
session_key_event_rate
number format: float
bounce_rate

Fraction 0..1.

number format: float
engagement_rate

Fraction 0..1 (1 - bounce_rate).

number format: float
average_session_duration_seconds
number format: float
sessions_change
number format: float
nullable
key_events_change
number format: float
nullable
session_key_event_rate_change
number format: float
nullable
bounce_rate_change
number format: float
nullable
engagement_rate_change
number format: float
nullable
average_session_duration_change
number format: float
nullable
channel_breakdown
Array

One Channel Performance row (scope=overview). Extends the shared metric block with the channel group and its share of the Total row.

object
channel_group
string
Allowed values: organic_search ai_chats other_channels
sessions

OpenAPI response schemas for the AI Traffic block of the AI Visibility Public API (summary / history / pages / filter-values). Property names are string literals that mirror the exact keys produced by the AI Traffic services, so the documented contract and the runtime response shapes stay in lock-step. The generic envelope schemas (PaginationMeta, ErrorEnvelope) live in PublicApiSchemas and are referenced by ref here.

integer
key_events
integer
session_key_event_rate
number format: float
bounce_rate

Fraction 0..1.

number format: float
engagement_rate

Fraction 0..1 (1 - bounce_rate).

number format: float
average_session_duration_seconds
number format: float
sessions_change
number format: float
nullable
key_events_change
number format: float
nullable
session_key_event_rate_change
number format: float
nullable
bounce_rate_change
number format: float
nullable
engagement_rate_change
number format: float
nullable
average_session_duration_change
number format: float
nullable
sessions_share

Percentage of Total sessions.

number format: float
key_event_share

Percentage of Total key events.

number format: float
meta
object
Example
{
  "data": {
    "ai_traffic": {
      "sessions": 1240,
      "key_events": 87,
      "session_key_event_rate": 7.02,
      "bounce_rate": 0.4213,
      "engagement_rate": 0.5787,
      "average_session_duration_seconds": 92.4,
      "sessions_change": 12.5,
      "key_events_change": -3.1,
      "session_key_event_rate_change": 1.4,
      "bounce_rate_change": -2,
      "engagement_rate_change": 2,
      "average_session_duration_change": 5.7
    },
    "total_metrics": {
      "sessions": 1240,
      "key_events": 87,
      "session_key_event_rate": 7.02,
      "bounce_rate": 0.4213,
      "engagement_rate": 0.5787,
      "average_session_duration_seconds": 92.4,
      "sessions_change": 12.5,
      "key_events_change": -3.1,
      "session_key_event_rate_change": 1.4,
      "bounce_rate_change": -2,
      "engagement_rate_change": 2,
      "average_session_duration_change": 5.7
    },
    "channel_breakdown": [
      {
        "channel_group": "organic_search",
        "sessions": 1240,
        "key_events": 87,
        "session_key_event_rate": 7.02,
        "bounce_rate": 0.4213,
        "engagement_rate": 0.5787,
        "average_session_duration_seconds": 92.4,
        "sessions_change": 12.5,
        "key_events_change": -3.1,
        "session_key_event_rate_change": 1.4,
        "bounce_rate_change": -2,
        "engagement_rate_change": 2,
        "average_session_duration_change": 5.7,
        "sessions_share": 12.34,
        "key_event_share": 9.87
      }
    ]
  }
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403

Section titled “403”

No active API entitlement for the account, or the project belongs to another account

Media typeapplication/json

Returned as api_access_denied when the account has no active API entitlement, and as forbidden when the requested project belongs to another account.

object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "api_access_denied",
    "message": "API access is not available: the account has no active API entitlement."
  }
}

404

Section titled “404”

Project not found

Media typeapplication/json

The exact missing resource is in error.code: project_not_found, segment_not_found, crawl_not_found, keyword_not_found, opportunity_not_found, snapshot_unavailable or not_found.

object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "project_not_found",
    "message": "Project not found."
  }
}

409

Section titled “409”

GA4 is not connected

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "ga4_not_connected",
    "message": "Google Analytics 4 is not connected for this project."
  }
}

422

Section titled “422”

Validation error, unsupported scope or filter

Media typeapplication/json

Rejected query parameters. error.code is validation_error for parameter validation, or invalid_date_range / invalid_filter / invalid_event_type / unsupported_filter / unsupported_dimension / unsupported_scope / segment_filter_unsupported for module-specific rules.

object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "validation_error",
    "message": "project_id is required."
  }
}

429

Section titled “429”

Rate limit exceeded — retry after the interval in the Retry-After header

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later."
  }
}

500

Section titled “500”

Internal server error

Media typeapplication/json
object
error
required
object
code
required
string
Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable
message
required
string
Example
{
  "error": {
    "code": "internal_error",
    "message": "Internal server error."
  }
}