Get AI crawler analytics

Call getAiCrawlerAnalytics from the Clics TypeScript SDK: date ranges, crawler filters, status filters, and dashboard-shaped results.

Returns verified AI crawler analytics for one project. The method always reads production crawler data.

Use it to build crawler reports, feed an internal dashboard, or check whether a provider has fetched a page recently.

Parameters

Field	Required	Description
`projectId`	Yes	Clics project ID
`dateRange`	No	Period preset. Ignored when both `start` and `end` are set
`start`	No	Custom range start (`yyyy-MM-dd` or ISO8601). Must be paired with `end`
`end`	No	Custom range end. Must be paired with `start`
`timezone`	No	IANA timezone for calendar boundaries. Defaults to `UTC`
`category`	No	One of `answer_fetch`, `search_index`, or `training`
`provider`	No	Comma-separated provider names
`providerOp`	No	`is` or `is_not`; defaults to `is`
`crawler`	No	Comma-separated crawler names
`crawlerOp`	No	`is` or `is_not`; defaults to `is`
`status`	No	Comma-separated HTTP status codes. Use `0` for unknown status
`statusOp`	No	`is` or `is_not`; defaults to `is`
`breakdownLimit`	No	Maximum rows per breakdown
`filterValuesLimit`	No	Maximum values returned for filter pickers

Date range presets

last24h · last7days · last30days · last3months · last12months · monthToDate · quarterToDate · yearToDate · allTime

Signature

clics.aiCrawlers.getAiCrawlerAnalytics(request, options?)

Examples

Last 30 days

import { Clics } from "@clicsdev/sdk";

const clics = new Clics({
  apiKey: process.env.CLICS_API_KEY!,
});

const result = await clics.aiCrawlers.getAiCrawlerAnalytics({
  projectId: "proj_xxx",
  dateRange: "last30days",
  timezone: "Europe/London",
});

console.log(result.categories[0]?.crawls);
console.log(result.breakdowns.providers);

Filter one provider and crawler

const result = await clics.aiCrawlers.getAiCrawlerAnalytics({
  projectId: "proj_xxx",
  dateRange: "last30days",
  provider: "OpenAI",
  crawler: "GPTBot",
  status: "200,404",
});

Exclude a provider

const result = await clics.aiCrawlers.getAiCrawlerAnalytics({
  projectId: "proj_xxx",
  dateRange: "last7days",
  provider: "Google",
  providerOp: "is_not",
});

Custom calendar range

Pass both start and end. dateRange is ignored when they are set.

const result = await clics.aiCrawlers.getAiCrawlerAnalytics({
  projectId: "proj_xxx",
  start: "2026-07-01",
  end: "2026-07-31",
  timezone: "Europe/Paris",
});

What it returns

{
  hasEvents: boolean;
  categories: Array<{
    category: string;
    crawls: number;
    previousCrawls: number;
    changePercent: number;
  }>;
  timeseries: Array<{
    date: string;
    crawls: number;
  }>;
  breakdowns: {
    providers: Array<{ value: string; label: string; crawls: number }>;
    crawlers: Array<{ value: string; label: string; crawls: number }>;
    pages: Array<{ value: string; label: string; crawls: number }>;
    urls: Array<{ value: string; label: string; crawls: number }>;
    statuses: Array<{ value: string; label: string; crawls: number }>;
  };
  filterValues: {
    providers: Array<{ value: string; label: string; crawls: number }>;
    crawlers: Array<{ value: string; label: string; crawls: number }>;
    statuses: Array<{ value: string; label: string; crawls: number }>;
  };
  meta: {
    environment: "production";
    timezone: string;
    category: "answer_fetch" | "search_index" | "training";
    dateRange: string | string[];
  };
  query: Record<string, unknown>;
}

The response is shaped for dashboards: category totals, one time series, breakdown tables, and filter values for UI controls.

Notes

Requires a paid plan: free tiers get 403
Reads production crawler data only
Passing only start or only end returns 400
Provider and crawler values are enums in the SDK, so TypeScript can guide the allowed values

API reference

See Get AI crawler analytics for the full request and response schemas.

Get AI crawler analytics with the Clics TypeScript SDK

Get AI crawler analytics