Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

AI Traffic History

GET
/api/v1/ai-visibility/ai-traffic/history
curl --request GET \
  --url 'https://sitechecker.pro/api/v1/ai-visibility/ai-traffic/history?project_id=12345&date_from=2026-02-19&date_to=2026-05-19&scope=overview&dimension=none&metric=sessions&history_grouping=daily&include_comparison=false' \
  --header 'Authorization: Bearer <token>'

Returns time-series points for one selected AI referral traffic metric over the selected date range. One metric per request, and the previous-period series is returned only when comparison is included.

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 pages

Which AI Traffic dataset to chart: overview compares AI chats against the other channels, ai_sources breaks AI referrals down by source, pages charts landing pages.

dimension
required
string
Allowed values: none channel_group ai_source page

How the series is split: none for a single total line, or one line per channel group, AI source or page.

metric
required

Engagement_rate not available for scope=overview

string
Allowed values: sessions key_events session_key_event_rate bounce_rate engagement_rate average_session_duration_seconds

The single metric to chart. One request returns one metric.

history_grouping
string
Allowed values: daily weekly monthly

Bucket size for the returned points.

include_comparison

Adds previous_series[] (previous same-length period).

boolean

Also return the previous-period series. It doubles the payload, so it is off by default.

series

Overview only: ai_chats,organic_search,other_channels,total

string

For scope=overview, which lines to return: ai_chats, organic_search, other_channels, total.

ai_sources

Ai_sources+ai_source only: chatgpt,perplexity,…

string

For scope=ai_sources, comma-separated ai_source values to chart.

ai_source

Pages scope only

string

Filter to one AI referral source.

country

Pages scope only (alpha-2)

string

Filter by country.

page

Pages scope only

string

Filter to one landing page URL.

dimension_limit

Pages scope: top-N pages cap

integer

Maximum number of lines to return when the series is split by a dimension.

Responses

Section titled “Responses”

200

Section titled “200”

AI Traffic time-series

Media typeapplication/json
object
data

AI Traffic time-series for one requested metric. previous_series appears only when include_comparison=true (previous same-length period).

object
scope

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

string
Allowed values: overview ai_sources pages
dimension

How the series was split, echoed back from the request.

string
Allowed values: none channel_group ai_source page
metric

The metric that was charted. One request returns one metric.

string
Allowed values: sessions key_events session_key_event_rate bounce_rate engagement_rate average_session_duration_seconds
series

One entry per line in the chart.

Array<object>

One time-series line. series_type is dimension_value for a real dimension value, synthetic for the overview Total series, or aggregate for the all-AI-sources total.

object
series_key

Machine value the line is keyed on — the AI source, channel group or page.

string
series_label

Display label for the line.

string
series_type

Dimension_value for a real dimension value, synthetic for the overview Total line, aggregate for an undivided series.

string
Allowed values: dimension_value synthetic aggregate
points

The line itself, one point per bucket.

Array<object>
object
date

First day of the bucket.

string format: date
value

Value of the requested metric in this bucket.

number format: float
previous_series

The same lines over the previous period, present only when comparison was requested.

Array<object>
nullable

One time-series line. series_type is dimension_value for a real dimension value, synthetic for the overview Total series, or aggregate for the all-AI-sources total.

object
series_key

Machine value the line is keyed on — the AI source, channel group or page.

string
series_label

Display label for the line.

string
series_type

Dimension_value for a real dimension value, synthetic for the overview Total line, aggregate for an undivided series.

string
Allowed values: dimension_value synthetic aggregate
points

The line itself, one point per bucket.

Array<object>
object
date

First day of the bucket.

string format: date
value

Value of the requested metric in this bucket.

number format: float
meta

AI Traffic meta block for the history endpoint: the standard block plus the bucket size that was applied to the points.

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
history_grouping

Bucket size the points were grouped by.

string
Allowed values: daily weekly monthly
Example
{
  "data": {
    "scope": "overview",
    "dimension": "none",
    "metric": "sessions",
    "series": [
      {
        "series_key": "chatgpt",
        "series_label": "chatgpt",
        "series_type": "dimension_value",
        "points": [
          {
            "date": "2026-05-02",
            "value": 1240
          }
        ]
      }
    ],
    "previous_series": [
      {
        "series_key": "chatgpt",
        "series_label": "chatgpt",
        "series_type": "dimension_value",
        "points": [
          {
            "date": "2026-05-02",
            "value": 1240
          }
        ]
      }
    ]
  },
  "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"
    },
    "history_grouping": "daily"
  }
}

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 / dimension / metric

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."
  }
}