GET AI Crawl Analytics

These endpoints return AI crawler analytics for the site attached to your API key. Both require Bearer Token authentication.

When no dates are provided, both endpoints return the most recent 24 hours. Custom dates must be valid ISO 8601 values, the start date must not be later than the end date, and the requested range cannot exceed 366 days.

AI crawl overview

GET https://api.faurya.com/api/v1/analytics/ai-crawls

Returns overall AI crawler activity, including provider totals, categories, top pages, provider time series, and recent crawl events.

Query parameters

• startDate (string, optional): Inclusive range start in ISO 8601 format. Defaults to 24 hours before endDate.
• endDate (string, optional): Inclusive range end in ISO 8601 format. Defaults to the current time.
• granularity (string, optional): Time-series grouping. Use hourly, daily, weekly, or monthly. Defaults to hourly.

Example request

The default request needs no query parameters and returns the latest 24 hours grouped hourly.

const response = await fetch(
  "https://api.faurya.com/api/v1/analytics/ai-crawls",
  {
    headers: {
      Authorization: `Bearer ${process.env.FAURYA_API_KEY}`,
    },
  },
);

const result = await response.json();

Response

{
  "success": true,
  "data": {
    "total": 148,
    "providers": [
      {
        "key": "ai_0",
        "provider": "OpenAI",
        "agent": "ChatGPT-User",
        "category": "answer_fetch",
        "label": "ChatGPT",
        "count": 82,
        "percentage": 0.5541
      }
    ],
    "categories": {
      "answer_fetch": 82,
      "ai_crawler": 66
    },
    "pages": [],
    "seriesPages": [],
    "timeseries": [],
    "rows": [],
    "interval": "hour",
    "timezone": "UTC",
    "websiteDomain": "example.com"
  }
}

Paginated AI crawl pages

GET https://api.faurya.com/api/v1/analytics/ai-crawls/pages

Returns page-level AI crawl totals, crawler and status-code breakdowns, and chart data. This endpoint is always paginated.

Query parameters

• startDate (string, optional): Inclusive range start in ISO 8601 format. Defaults to 24 hours before endDate.
• endDate (string, optional): Inclusive range end in ISO 8601 format. Defaults to the current time.
• granularity (string, optional): Chart grouping. Use hourly, daily, weekly, or monthly. Defaults to hourly.
• limit (number, optional): Number of pages to return. Defaults to 40; accepted values are 30 through 40.
• offset (number, optional): Number of page records to skip. Defaults to 0; maximum 100000.
• category (string, optional): all, answer_fetch, training, or indexing. indexing includes both search_index and ai_crawler events.
• search (string, optional): Case-insensitive search across page path, URL, and hostname.

Example request

const params = new URLSearchParams({
  granularity: "hourly",
  category: "all",
  offset: "0",
  limit: "40",
});

const response = await fetch(
  `https://api.faurya.com/api/v1/analytics/ai-crawls/pages?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.FAURYA_API_KEY}`,
    },
  },
);

const result = await response.json();

Response

The pagination object is always present, including when no pages match the query. pagination.total is the number of matching page records, while data.total is the total number of matching crawl events.

{
  "success": true,
  "data": {
    "total": 148,
    "pages": [
      {
        "id": "example.com::/pricing",
        "hostname": "example.com",
        "path": "/pricing",
        "href": "https://example.com/pricing",
        "count": 34,
        "statusCounts": {
          "200": 32,
          "404": 2
        },
        "crawlers": []
      }
    ],
    "chartPages": [],
    "chartData": [],
    "hasMore": false,
    "resultCount": 1,
    "offset": 0,
    "limit": 40,
    "interval": "hour",
    "timezone": "UTC",
    "websiteDomain": "example.com"
  },
  "pagination": {
    "limit": 40,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}

To request the next page, add the current limit to offset while pagination.hasMore is true.