Skip to content

k.analytics ​

Query site visitor, resource, and error analytics, and track custom goal events

Execution ContextPrerequisitesTypical Use
Api, CodeBlock, <script env="server">Site analytics enabled; track() requires matching goal names in AdminQuery visitor, resource, and error metrics, or record conversion events

Quick Start ​

js
k.api.get("analytics-quick", () => {
    const visitors = k.analytics.visitor.summary({ top: 5 })
    const errors = k.analytics.error.summary({ top: 5 })

    // Record a custom conversion goal for the current request
    k.analytics.track("api_health_check")

    return {
        range: visitors.startDate + " ~ " + visitors.endDate,
        pageViews: visitors.pageViews,
        uniqueVisitors: visitors.uniqueVisitors,
        totalErrors: errors.totalErrors
    }
})

Quick Reference ​

Method / PropertyDescriptionReturns
k.analytics.visitor.list(filter?)Paginated visitor logs with anonymized IP addressesPagedResult<VisitorLogItem>
k.analytics.visitor.summary(filter?)Aggregated page views, unique visitors, daily trends, and breakdownsVisitorSummary
k.analytics.resource.list(filter?)Recent static resource requests from bounded ring bufferPagedResult<ResourceLogItem>
k.analytics.resource.summary(filter?)Complete resource requests, bandwidth by type, and hotlink reportsResourceSummary
k.analytics.error.list(filter?)Paginated page, API, and custom runtime error logsPagedResult<ErrorLogItem>
k.analytics.error.summary(filter?)Total errors, affected users, error types, and top pathsErrorSummary
k.analytics.track(customName, parameter?)Record a custom goal or A/B test conversion event for the requestvoid

Overview ​

k.analytics provides server-side access to Kooboo site analytics and custom goal event tracking. Use it in APIs or page scripts to query traffic metrics, recent static resource requests, and error reports, or to record custom conversion events.

Corresponding Admin Features

Analytics collection switches, visual dashboards, and goal definitions are configured in Kooboo Admin under Visitor Logs, Resource Guardian, and A/B Testing.

Runtime Return Shape of list()

In editor TypeScript IntelliSense, the three list(filter?) methods are typed as returning any. At runtime, every list() call returns a PagedResult<T> object containing items, totalCount, pageIndex, pageSize, totalPages, hasPreviousPage, hasNextPage, isPartial, and notice.

Date Range and Common Parameter Rules ​

All list() and summary() methods share these date-window and validation rules:

  • Date format: startDate and endDate are inclusive and must use yyyy-MM-dd format; an analytics day begins at 04:00 local server time. Invalid formats or startDate > endDate throw an exception.
  • Default range: When omitted, the window spans from Monday of the current analytics week through the current analytics day (for example, Saturday covers the 6 days from Monday through Saturday).
  • Maximum range: A single query cannot exceed 366 days.
  • Pagination and top clamping: pageIndex clamps to at least 1; pageSize and top default to 20 (values <= 0 fall back to 20) and clamp to a maximum of 200.

visitor ​

visitor.list() ​

Queries paginated visitor log entries within the selected date range.

Privacy Protection

The ip field always contains the anonymized IP address only; the unmasked client IP is never exposed to scripts.

Parameters:

ParameterTypeRequiredDefaultDescription
filterVisitorLogFilterno{}Filter options object
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.typestringno"all"Traffic type: "all", "human", "bot", or "error" (invalid values throw)
filter.isMobilebooleanno-Filter by mobile devices
filter.statusCodenumberno-Exact HTTP status code
filter.keywordstringno-Search across URL, page name, referrer, country/city, user-agent, UTM, or anonymized IP
filter.pageIndexnumberno11-based page number
filter.pageSizenumberno20Items per page (1–200)

Returns: PagedResult<VisitorLogItem>.

js
k.api.get("visitor-logs", () => {
    const page = k.analytics.visitor.list({
        type: "human",
        isMobile: false,
        statusCode: 200,
        pageIndex: 1,
        pageSize: 20
    })

    return {
        totalCount: page.totalCount,
        pageIndex: page.pageIndex,
        pageSize: page.pageSize,
        totalPages: page.totalPages,
        items: page.items
    }
})

visitor.summary() ​

Aggregates page views, unique visitors, bot share, daily trends, and breakdown rankings for the selected date range.

Parameters:

ParameterTypeRequiredDefaultDescription
filterAnalyticsSummaryFilterno{}Summary filter options
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.topnumberno20Maximum items returned per ranking/distribution (1–200)
filter.includeDimensionsbooleannotrueInclude native aggregated dimensions array

Returns: VisitorSummary.

js
k.api.get("visitor-summary", () => {
    const currentWeek = k.analytics.visitor.summary()
    const customReport = k.analytics.visitor.summary({
        startDate: currentWeek.startDate,
        endDate: currentWeek.endDate,
        top: 10,
        includeDimensions: true
    })

    return {
        range: customReport.startDate + " ~ " + customReport.endDate,
        pageViews: customReport.pageViews,
        uniqueVisitors: customReport.uniqueVisitors,
        botVisits: customReport.botVisits,
        daysCount: customReport.days.length,
        topPages: customReport.topPages
    }
})

resource ​

resource.list() ​

Queries recent static resource request logs.

Bounded Recent Resource Ring

k.analytics.resource.list() reads from a fixed-capacity per-site ring buffer (up to roughly 102,400 recent requests). The returned object always has isPartial: true and notice: "Resource detail is read from the bounded recent resource ring. Use summary() for complete date-range totals.". Use k.analytics.resource.summary() whenever you need complete totals across a date range.

Parameters:

ParameterTypeRequiredDefaultDescription
filterResourceLogFilterno{}Resource filter options
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.typestringno"all"Resource type: "all", "image", "css", "javascript" (alias "js" also accepted), "file", "system", or "unknown"
filter.isBotbooleanno-Filter by bot requests
filter.isProtectedbooleanno-Filter by Resource Guardian protected hits
filter.statusCodenumberno-Exact HTTP status code
filter.keywordstringno-Search across URL, referrer, country code, user-agent, or anonymized IP
filter.pageIndexnumberno11-based page number
filter.pageSizenumberno20Items per page (1–200)

Returns: PagedResult<ResourceLogItem> (isPartial is true).

js
k.api.get("resource-logs", () => {
    const page = k.analytics.resource.list({
        type: "js",
        isBot: false,
        isProtected: false,
        pageIndex: 1,
        pageSize: 10
    })

    return {
        isPartial: page.isPartial,
        notice: page.notice,
        totalCount: page.totalCount,
        items: page.items
    }
})

resource.summary() ​

Returns complete resource request counts, bandwidth breakdown by file type, external referring domains, 404 resources, and source-to-resource relations across the selected date range.

Parameters:

ParameterTypeRequiredDefaultDescription
filterResourceSummaryFilterno{}Resource summary options
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.topnumberno20Maximum items returned per ranking/distribution (1–200)
filter.includeDimensionsbooleannotrueInclude dimensions array
filter.includeRelationsbooleannotrueInclude foundRelations, notFoundRelations, and protectedRelations

Returns: ResourceSummary.

js
k.api.get("resource-summary", () => {
    const report = k.analytics.resource.summary({
        top: 10,
        includeDimensions: true,
        includeRelations: true
    })

    return {
        startDate: report.startDate,
        endDate: report.endDate,
        totalRequests: report.totalRequests,
        totalBytes: report.totalBytes,
        protectedCount: report.protectedCount,
        bandwidthByFileType: report.bandwidthByFileType
    }
})

error ​

error.list() ​

Queries paginated page, API, and custom runtime error logs recorded for the site.

Parameters:

ParameterTypeRequiredDefaultDescription
filterErrorLogFilterno{}Error filter options
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.typestringno"all"Error type: "all", "page", "api", or "custom"
filter.isBotbooleanno-Filter by bot requests
filter.statusCodenumberno-Exact HTTP status code
filter.keywordstringno-Search across URL, message, level, referrer, IP, or user-agent
filter.pageIndexnumberno11-based page number
filter.pageSizenumberno20Items per page (1–200)

Returns: PagedResult<ErrorLogItem>.

js
k.api.get("error-logs", () => {
    const page = k.analytics.error.list({
        type: "all",
        pageIndex: 1,
        pageSize: 10
    })

    return {
        totalCount: page.totalCount,
        items: page.items.map((item) => ({
            id: item.id,
            time: item.time,
            errorType: item.errorType,
            statusCode: item.statusCode,
            url: item.url,
            message: item.message
        }))
    }
})

error.summary() ​

Aggregates total errors, error rate, affected users, daily breakdown, error type shares, and high-frequency errors.

Parameters:

ParameterTypeRequiredDefaultDescription
filterAnalyticsSummaryFilterno{}Summary filter options
filter.startDatestringnoMonday of current weekInclusive start date (yyyy-MM-dd)
filter.endDatestringnoCurrent analytics dayInclusive end date (yyyy-MM-dd)
filter.topnumberno20Maximum items returned per ranking/distribution (1–200)
filter.includeDimensionsbooleannotrueInclude dimensions array

Returns: ErrorSummary.

js
k.api.get("error-summary", () => {
    const report = k.analytics.error.summary({
        top: 10,
        includeDimensions: true
    })

    return {
        startDate: report.startDate,
        endDate: report.endDate,
        totalErrors: report.totalErrors,
        affectedUsers: report.affectedUsers,
        types: report.types,
        highFrequencyErrors: report.highFrequencyErrors
    }
})

track() ​

Records a custom goal event for the current HTTP request.

Prerequisites

k.analytics.track() writes conversion data when Navigation Flow or A/B Testing is enabled on the site and a Custom Goal matching customName is configured. Otherwise, the call completes synchronously with no error and records nothing.

Parameters:

ParameterTypeRequiredDescription
customNamestringyesCustom goal name matching the site's goal configuration
parameteranynoOptional payload. Passing a positive number, numeric string, or object containing revenue, amount, value, total, or price records that positive value as conversion revenue

Returns: void (the call expression evaluates to undefined at runtime).

js
// Track a custom event without revenue
k.analytics.track("newsletter_subscribe")

// Track a custom event with conversion revenue
k.analytics.track("checkout_complete", {
    revenue: 199.5,
    plan: "pro"
})

TypeScript Definitions ​

Show full TypeScript definitions
ts
interface kAnalytics {
  visitor: VisitorAnalyticsModule;
  resource: ResourceAnalyticsModule;
  error: ErrorAnalyticsModule;
  track(customName: string, parameter?: any): void;
}

interface VisitorAnalyticsModule {
  list(filter?: VisitorLogFilter): any;
  summary(filter?: AnalyticsSummaryFilter): VisitorSummary;
}

interface ResourceAnalyticsModule {
  list(filter?: ResourceLogFilter): any;
  summary(filter?: ResourceSummaryFilter): ResourceSummary;
}

interface ErrorAnalyticsModule {
  list(filter?: ErrorLogFilter): any;
  summary(filter?: AnalyticsSummaryFilter): ErrorSummary;
}

interface AnalyticsDateFilter {
  startDate?: string; // yyyy-MM-dd, defaults to Monday of current analytics week
  endDate?: string;   // yyyy-MM-dd, defaults to current analytics day
}

interface AnalyticsSummaryFilter extends AnalyticsDateFilter {
  top?: number;               // Maximum ranking/distribution entries, default 20, max 200
  includeDimensions?: boolean; // Include native aggregated dimensions, default true
}

interface ResourceSummaryFilter extends AnalyticsSummaryFilter {
  includeRelations?: boolean;  // Include resource/source relation arrays, default true
}

interface PagedAnalyticsFilter extends AnalyticsDateFilter {
  pageIndex?: number; // Page index starting at 1 (values < 1 clamp to 1)
  pageSize?: number;  // Page size, default 20, max 200
  keyword?: string;   // Case-insensitive search keyword, max 256 characters
  statusCode?: number; // Exact HTTP status code filter
}

interface VisitorLogFilter extends PagedAnalyticsFilter {
  type?: string;     // "all" | "human" | "bot" | "error"
  isMobile?: boolean;
}

interface ResourceLogFilter extends PagedAnalyticsFilter {
  type?: string;       // "all" | "image" | "css" | "javascript" | "js" | "file" | "system" | "unknown"
  isBot?: boolean;
  isProtected?: boolean;
}

interface ErrorLogFilter extends PagedAnalyticsFilter {
  type?: string; // "all" | "page" | "api" | "custom"
  isBot?: boolean;
}

interface PagedResult<T> {
  items: T[];
  totalCount: number;
  pageIndex: number;
  pageSize: number;
  totalPages: number;
  hasPreviousPage: boolean;
  hasNextPage: boolean;
  isPartial: boolean;  // Always true for resource.list()
  notice?: string;     // Ring-buffer notice for resource.list(), otherwise null
}

interface VisitorLogItem {
  id: number;
  time: Date;
  url: string;
  pageName: string;
  objectId: string;
  referrer: string;
  ip: string;
  city: string;
  countryCode: string;
  continent: string;
  userAgent: string;
  application: string;
  browser: string;
  device: string;
  isMobile: boolean;
  isBot: boolean;
  botName: string;
  statusCode: number;
  size: number;
  durationMs: number;
  utm: string;
}

interface VisitorSummary {
  startDate: string;
  endDate: string;
  pageViews: number;
  uniqueVisitors: number;
  botVisits: number;
  totalVisits: number;
  humanBytes: number;
  botBytes: number;
  totalBytes: number;
  errorCount: number;
  errorRate: number;
  humanRate: number;
  botRate: number;
  days: VisitorDailySummary[];
  topReferrers: AnalyticsValueItem[];
  topReferrerUrls: AnalyticsValueItem[];
  topApplications: AnalyticsValueItem[];
  topPages: AnalyticsValueItem[];
  topPageIds: AnalyticsValueItem[];
  topBrowsers: AnalyticsValueItem[];
  topDevices: AnalyticsValueItem[];
  topCountries: AnalyticsValueItem[];
  statusCodes: AnalyticsValueItem[];
  ipUserTypes: AnalyticsValueItem[];
  utm: AnalyticsValueItem[];
  dpr: AnalyticsValueItem[];
  colorSchemes: AnalyticsValueItem[];
  viewportWidths: AnalyticsValueItem[];
  topErrors: VisitorErrorSummaryItem[];
  bots: BotSummaryReport;
  countryNetwork: NetworkCountrySummary[];
  connectionTypes: ConnectionTypeSummary[];
  dimensions: AnalyticsDimension[];
}

interface ResourceLogItem {
  id: number;
  time: Date;
  url: string;
  resourceType: string;
  referrer: string;
  ip: string;
  countryCode: string;
  userAgent: string;
  application: string;
  browser: string;
  device: string;
  isMobile: boolean;
  isBot: boolean;
  botName: string;
  isProtected: boolean;
  statusCode: number;
  size: number;
}

interface ResourceSummary {
  startDate: string;
  endDate: string;
  humanRequests: number;
  botRequests: number;
  totalRequests: number;
  humanBytes: number;
  botBytes: number;
  totalBytes: number;
  errorCount: number;
  errorRate: number;
  protectedCount: number;
  humanRate: number;
  botRate: number;
  days: ResourceDailySummary[];
  requestsByFileType: AnalyticsValueItem[];
  bandwidthByFileType: AnalyticsValueItem[];
  statusCodes: AnalyticsValueItem[];
  externalDomains: ResourceExternalDomainItem[];
  topResources: ResourceRankItem[];
  topSources: ResourceRankItem[];
  topSystemRoutes: ResourceRankItem[];
  notFound: ResourceNotFoundSummary;
  protectedResources: ResourceUsageItem[];
  foundRelations: ResourceRelationItem[];
  notFoundRelations: ResourceRelationItem[];
  protectedRelations: ResourceRelationItem[];
  bots: BotSummaryReport;
  countryNetwork: NetworkCountrySummary[];
  connectionTypes: ConnectionTypeSummary[];
  dimensions: AnalyticsDimension[];
}

interface ErrorLogItem {
  id: number;
  time: Date;
  errorType: string;
  level: string;
  url: string;
  message: string;
  referrer: string;
  ip: string;
  userAgent: string;
  application: string;
  browser: string;
  device: string;
  isMobile: boolean;
  isBot: boolean;
  botName: string;
  statusCode: number;
  objectId: string;
}

interface ErrorSummary {
  startDate: string;
  endDate: string;
  totalErrors: number;
  errorRate: number;
  affectedUsers: number;
  affectedUserRate: number;
  humanErrors: number;
  botErrors: number;
  humanRate: number;
  botRate: number;
  days: ErrorDailySummary[];
  types: AnalyticsValueItem[];
  highFrequencyErrors: ErrorFrequencyItem[];
  dimensions: AnalyticsDimension[];
}

interface VisitorDailySummary {
  date: string;
  pageViews: number;
  uniqueVisitors: number;
  botVisits: number;
  totalVisits: number;
  humanBytes: number;
  botBytes: number;
  totalBytes: number;
}

interface ResourceDailySummary {
  date: string;
  humanRequests: number;
  botRequests: number;
  totalRequests: number;
  humanBytes: number;
  botBytes: number;
  totalBytes: number;
}

interface ErrorDailySummary {
  date: string;
  totalErrors: number;
  affectedUsers: number;
  humanErrors: number;
  botErrors: number;
  pageErrors: number;
  apiErrors: number;
  customErrors: number;
}

interface AnalyticsValueItem {
  name: string;
  value: number;
  share: number;
}

interface AnalyticsDimension {
  name: string;
  total: number;
  items: AnalyticsValueItem[];
}

interface VisitorErrorSummaryItem {
  url: string;
  statusCode: number;
  count: number;
}

interface BotSummaryReport {
  visits: number;
  trafficShare: number;
  goodBotRate: number;
  badBotRate: number;
  items: BotSummaryItem[];
}

interface BotSummaryItem {
  name: string;
  status: string;
  visits: number;
  blockedRequests: number;
  blocked: boolean;
  trafficShare: number;
}

interface NetworkCountrySummary {
  countryCode: string;
  userCount: number;
  userShare: number;
  averageRtt: number;
  downloadSpeedMbps: number;
}

interface ConnectionTypeSummary {
  name: string;
  userCount: number;
  userShare: number;
}

interface ResourceRankItem {
  url: string;
  requests: number;
  bytes: number;
}

interface ResourceExternalDomainItem {
  domain: string;
  requests: number;
  bytes: number;
  blockedRequests: number;
  blockedShare: number;
  isBlocked: boolean;
}

interface ResourceRelationItem {
  resourceUrl: string;
  sourceUrl: string;
  requests: number;
}

interface ResourceReferrerItem {
  sourceUrl: string;
  requests: number;
}

interface ResourceUsageItem {
  resourceUrl: string;
  requests: number;
  topReferrers: ResourceReferrerItem[];
}

interface ResourceNotFoundSummary {
  resourceCount: number;
  sourceCount: number;
  topResources: ResourceUsageItem[];
  topSources: ResourceReferrerItem[];
}

interface ErrorFrequencyItem {
  rank: number;
  type: string;
  statusCode: number;
  path: string;
  count: number;
}