k.analytics
Query site visitor, resource, and error analytics, and track custom goal events
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
Api, CodeBlock, <script env="server"> | Site analytics enabled; track() requires matching goal names in Admin | Query visitor, resource, and error metrics, or record conversion events |
Quick Start
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 / Property | Description | Returns |
|---|---|---|
k.analytics.visitor.list(filter?) | Paginated visitor logs with anonymized IP addresses | PagedResult<VisitorLogItem> |
k.analytics.visitor.summary(filter?) | Aggregated page views, unique visitors, daily trends, and breakdowns | VisitorSummary |
k.analytics.resource.list(filter?) | Recent static resource requests from bounded ring buffer | PagedResult<ResourceLogItem> |
k.analytics.resource.summary(filter?) | Complete resource requests, bandwidth by type, and hotlink reports | ResourceSummary |
k.analytics.error.list(filter?) | Paginated page, API, and custom runtime error logs | PagedResult<ErrorLogItem> |
k.analytics.error.summary(filter?) | Total errors, affected users, error types, and top paths | ErrorSummary |
k.analytics.track(customName, parameter?) | Record a custom goal or A/B test conversion event for the request | void |
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:
startDateandendDateare inclusive and must useyyyy-MM-ddformat; an analytics day begins at04:00local server time. Invalid formats orstartDate > endDatethrow 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
366days. - Pagination and top clamping:
pageIndexclamps to at least1;pageSizeandtopdefault to20(values<= 0fall back to20) and clamp to a maximum of200.
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | VisitorLogFilter | no | {} | Filter options object |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.type | string | no | "all" | Traffic type: "all", "human", "bot", or "error" (invalid values throw) |
filter.isMobile | boolean | no | - | Filter by mobile devices |
filter.statusCode | number | no | - | Exact HTTP status code |
filter.keyword | string | no | - | Search across URL, page name, referrer, country/city, user-agent, UTM, or anonymized IP |
filter.pageIndex | number | no | 1 | 1-based page number |
filter.pageSize | number | no | 20 | Items per page (1–200) |
Returns: PagedResult<VisitorLogItem>.
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | AnalyticsSummaryFilter | no | {} | Summary filter options |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.top | number | no | 20 | Maximum items returned per ranking/distribution (1–200) |
filter.includeDimensions | boolean | no | true | Include native aggregated dimensions array |
Returns: VisitorSummary.
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | ResourceLogFilter | no | {} | Resource filter options |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.type | string | no | "all" | Resource type: "all", "image", "css", "javascript" (alias "js" also accepted), "file", "system", or "unknown" |
filter.isBot | boolean | no | - | Filter by bot requests |
filter.isProtected | boolean | no | - | Filter by Resource Guardian protected hits |
filter.statusCode | number | no | - | Exact HTTP status code |
filter.keyword | string | no | - | Search across URL, referrer, country code, user-agent, or anonymized IP |
filter.pageIndex | number | no | 1 | 1-based page number |
filter.pageSize | number | no | 20 | Items per page (1–200) |
Returns: PagedResult<ResourceLogItem> (isPartial is true).
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | ResourceSummaryFilter | no | {} | Resource summary options |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.top | number | no | 20 | Maximum items returned per ranking/distribution (1–200) |
filter.includeDimensions | boolean | no | true | Include dimensions array |
filter.includeRelations | boolean | no | true | Include foundRelations, notFoundRelations, and protectedRelations |
Returns: ResourceSummary.
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | ErrorLogFilter | no | {} | Error filter options |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.type | string | no | "all" | Error type: "all", "page", "api", or "custom" |
filter.isBot | boolean | no | - | Filter by bot requests |
filter.statusCode | number | no | - | Exact HTTP status code |
filter.keyword | string | no | - | Search across URL, message, level, referrer, IP, or user-agent |
filter.pageIndex | number | no | 1 | 1-based page number |
filter.pageSize | number | no | 20 | Items per page (1–200) |
Returns: PagedResult<ErrorLogItem>.
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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
filter | AnalyticsSummaryFilter | no | {} | Summary filter options |
filter.startDate | string | no | Monday of current week | Inclusive start date (yyyy-MM-dd) |
filter.endDate | string | no | Current analytics day | Inclusive end date (yyyy-MM-dd) |
filter.top | number | no | 20 | Maximum items returned per ranking/distribution (1–200) |
filter.includeDimensions | boolean | no | true | Include dimensions array |
Returns: ErrorSummary.
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:
| Parameter | Type | Required | Description |
|---|---|---|---|
customName | string | yes | Custom goal name matching the site's goal configuration |
parameter | any | no | Optional 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).
// 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
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;
}Related Docs
- k.logger — Write and query application code logs
- Visitor Logs (Admin) — Built-in traffic analytics dashboard
- Resource Guardian (Admin) — Static resource bandwidth and hotlink protection
- A/B Testing (Admin) — Conversion goals and experiment management