Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

AI Traffic Summary

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>'

Returns aggregate AI referral traffic metrics for the selected period, scope, and filters. AI Traffic is the one AI Visibility block with previous-period comparison; the change fields appear only when comparison is included, and are null when the previous value was zero.

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

Which AI Traffic dataset to summarise: overview for the channel comparison, ai_sources for the AI referral breakdown.

include_comparison
boolean
default: true

Return previous-period values alongside the current ones.

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

Metrics for AI chat referrals alone.

object
sessions
integer
key_events

GA4 key events recorded in these sessions.

integer
session_key_event_rate

Key events per session, as a percentage. The canonical conversion-style metric for AI Traffic.

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

Mean session length in seconds.

number format: float
sessions_change

Percentage change in sessions against the previous period.

number format: float
nullable
key_events_change

Percentage change in key events against the previous period.

number format: float
nullable
session_key_event_rate_change

Percentage change in the key event rate against the previous period.

number format: float
nullable
bounce_rate_change

Percentage change in bounce rate against the previous period.

number format: float
nullable
engagement_rate_change

Percentage change in engagement rate against the previous period.

number format: float
nullable
average_session_duration_change

Percentage change in average session duration against the previous period.

number format: float
nullable
total_metrics

Metrics for all channels combined, the denominator of the share fields.

object
sessions
integer
key_events

GA4 key events recorded in these sessions.

integer
session_key_event_rate

Key events per session, as a percentage. The canonical conversion-style metric for AI Traffic.

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

Mean session length in seconds.

number format: float
sessions_change

Percentage change in sessions against the previous period.

number format: float
nullable
key_events_change

Percentage change in key events against the previous period.

number format: float
nullable
session_key_event_rate_change

Percentage change in the key event rate against the previous period.

number format: float
nullable
bounce_rate_change

Percentage change in bounce rate against the previous period.

number format: float
nullable
engagement_rate_change

Percentage change in engagement rate against the previous period.

number format: float
nullable
average_session_duration_change

Percentage change in average session duration against the previous period.

number format: float
nullable
channel_breakdown

One row per channel group, each with its share of the total.

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
integer
key_events

GA4 key events recorded in these sessions.

integer
session_key_event_rate

Key events per session, as a percentage. The canonical conversion-style metric for AI Traffic.

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

Mean session length in seconds.

number format: float
sessions_change

Percentage change in sessions against the previous period.

number format: float
nullable
key_events_change

Percentage change in key events against the previous period.

number format: float
nullable
session_key_event_rate_change

Percentage change in the key event rate against the previous period.

number format: float
nullable
bounce_rate_change

Percentage change in bounce rate against the previous period.

number format: float
nullable
engagement_rate_change

Percentage change in engagement rate against the previous period.

number format: float
nullable
average_session_duration_change

Percentage change in average session duration against the previous period.

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

Standard AI Traffic meta block: the request scope echoed back, GA4 availability and data freshness. date_from / date_to are the dates actually used after clamping to the GA4 window, so they can differ from the requested ones. resolved_compare_* appear only when include_comparison=true.

object
project_id

Project the response was built for.

integer
date_from

Start of the period the response covers.

string format: date
date_to

End of the period the response covers.

string format: date
scope

The dataset that was queried, echoed back from the request.

string
Allowed values: overview ai_sources pages
resolved_compare_from

Start of the previous period the *_change fields were computed against. Present only when comparison was included.

string format: date
resolved_compare_to

End of the previous period the *_change fields were computed against. Present only when comparison was included.

string format: date
source_status

Whether GA4 is connected and usable for this project.

object
key
additional properties
string
data_freshness

Latest GA4 data date available for this project, null when there is none.

object
key
additional properties
string
nullable
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
      }
    ]
  },
  "meta": {
    "project_id": 12345,
    "date_from": "2026-05-01",
    "date_to": "2026-05-31",
    "scope": "overview",
    "resolved_compare_from": "2026-04-01",
    "resolved_compare_to": "2026-04-30",
    "source_status": {
      "ga4": "connected"
    },
    "data_freshness": {
      "ga4_date": "2026-06-30"
    }
  }
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json

Returned as INVALID_API_KEY when the key is missing or unknown, and as REVOKED_API_KEY when the key exists but was revoked — the latter needs a new key.

object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "INVALID_API_KEY",
    "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 MISSING_PUBLIC_API_ACCESS when the account has no active API entitlement, and as ACCESS_DENIED 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "MISSING_PUBLIC_API_ACCESS",
    "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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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 (including a query parameter the endpoint does not accept), or INVALID_DATE_RANGE / INVALID_FILTER / INVALID_EVENT_TYPE / UNSUPPORTED_FILTER / UNSUPPORTED_DIMENSION / UNSUPPORTED_METRIC / 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error."
  }
}