---
title: Get AI crawler analytics
description: "Call getAiCrawlerAnalytics from the Clics TypeScript SDK: date ranges, crawler filters, status filters, and dashboard-shaped results."
sidebar:
  label: Get AI crawler analytics
seo:
  title: Get AI crawler analytics with the Clics TypeScript SDK
---

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

```typescript
clics.aiCrawlers.getAiCrawlerAnalytics(request, options?)
```

## Examples

### Last 30 days

```typescript
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

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

### Exclude a provider

```typescript
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.

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

## What it returns

```typescript
{
  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](/reference/ai-crawlers/getaicrawleranalytics) for the full request and response schemas.