Get AI activity report REST API

GET

/api/sites/{id}/ai-activity

const url = 'http://127.0.0.1:25737/api/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ai-activity';
const options = {method: 'GET', headers: {cookie: 'hk_token=<hk_token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://127.0.0.1:25737/api/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ai-activity \
  --cookie hk_token=<hk_token>

Returns the unified AI activity report for a site: one merged view over tracked AI hits (classified at query time from the user agent and referrer) and server-log AI fetch records. Every count is tracked hits plus fetch records, and each row keeps the provenance split. Repeatable filter=type:value params narrow both sides where the dimension exists on both: ai_bot maps to the fetch assistant name, ai_bot_category to the fetch assistant category (falling back to the agent name for records ingested before that column existed), and path to both. An ai_source filter excludes the fetch side outright because fetch records carry no referrer, while hit-only dimensions such as country or device leave the fetch side unrestricted. The pageviews denominator applies the non-AI filters only.

Authorizations

Parameters

Path Parameters

required

string format: uuid

Query Parameters

from

string format: date-time

filter

string

Filter in form type:value (repeatable). Supported types: path, hostname, referrer, referrer_host, device, country, city, provider, asn, browser, language, ai_bot, ai_bot_category, ai_source, utm_campaign, utm_content, utm_medium, utm_source, utm_term, qr_code_id.

filter_type

string

filter_value

string

compare_from

string format: date-time

Start of an optional comparison window. Malformed values are ignored rather than rejected.

compare_to

string format: date-time

End of an optional comparison window.

Responses

200

AI activity report

application/json

Unified AI activity report merging tracked AI hits with server-log AI fetch records. Every count follows one rule: tracked hits plus fetch records. Depth metrics describe the fetch side only, because tracked hits carry no status code, response time, or transferred bytes.

object

ai_requests

integer

comparison

Merged counters for the compare_from/compare_to window. Absent unless a comparison range is requested.

object

ai_requests

integer

fetch_count

integer

pageviews

integer

paths_crawled

integer

referral_visits

integer

tracked_hits

integer

unique_agents

integer

error_rate_4xx

number

error_rate_5xx

number

fetch_count

integer

median_response_ms

integer

pageviews

Total hits for the range under the non-AI filters only, so the AI share of a segment stays comparable while an AI dimension is drilled into.

integer

paths_crawled

Distinct paths seen on either side, counted before the top-list cap.

integer

referral_visits

Distinct sessions referred by a known AI surface across the whole range.

integer

series

Array<object>

object

ai_requests

Tracked AI bot hits plus AI fetch records in the bucket.

integer

fetch_count

integer

referral_visits

Distinct sessions referred by a known AI surface inside the bucket. Buckets are not additive: a session spanning two buckets counts in both.

integer

time

string format: date-time

tracked_hits

integer

top_agents

Array<object>

One row of a merged AI activity top list. value is always tracked_hits + fetch_count. Dimensions only one source carries report zero on the other side: families and resource types exist only in server-log fetch records, referral sources only in tracked hits.

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_agents_by_category

Merged agent top list per AI agent category, keyed by category.

object

key

additional properties

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_categories

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_error_paths

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_families

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_paths

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_resource_types

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

top_sources

Array<object>

object

fetch_count

integer

name

string

tracked_hits

integer

value

integer

total_bytes

integer

tracked_hits

integer

unique_agents

integer

Example^generated

{
  "ai_requests": 1,
  "comparison": {
    "ai_requests": 1,
    "fetch_count": 1,
    "pageviews": 1,
    "paths_crawled": 1,
    "referral_visits": 1,
    "tracked_hits": 1,
    "unique_agents": 1
  },
  "error_rate_4xx": 1,
  "error_rate_5xx": 1,
  "fetch_count": 1,
  "median_response_ms": 1,
  "pageviews": 1,
  "paths_crawled": 1,
  "referral_visits": 1,
  "series": [
    {
      "ai_requests": 1,
      "fetch_count": 1,
      "referral_visits": 1,
      "time": "2026-04-15T12:00:00Z",
      "tracked_hits": 1
    }
  ],
  "top_agents": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_agents_by_category": {
    "additionalProperty": [
      {
        "fetch_count": 1,
        "name": "example",
        "tracked_hits": 1,
        "value": 1
      }
    ]
  },
  "top_categories": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_error_paths": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_families": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_paths": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_resource_types": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "top_sources": [
    {
      "fetch_count": 1,
      "name": "example",
      "tracked_hits": 1,
      "value": 1
    }
  ],
  "total_bytes": 1,
  "tracked_hits": 1,
  "unique_agents": 1
}

Get AI activity report REST API

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Examplegenerated

Example^generated