---
title: "AI-crawler activity"
method: GET
path: "/brands/{brandId}/crawlers"
tags: ["measurement"]
---

# AI-crawler activity

`GET /brands/{brandId}/crawlers`

## Request

- Base URL: `https://shruwd.io/api/v1`
- URL: `https://shruwd.io/api/v1/brands/{brandId}/crawlers`
- Auth: HTTP bearer

Per-bot hits from the brand's server logs over the window, plus how
continuous the log ingest has been. `verifiedHits` are hits whose source
IP was confirmed against the vendor's published ranges; `unverifiedHits`
merely claimed the user-agent. **Only verified hits are a signal.** They
are never summed, here or anywhere.

## Query parameters

- `from` string, date
- `to` string, date

## Response `200`

Crawler activity.

- Crawlers
  - `brand` object, required
    - `brandId` string, required
    - `name` string, required
  - `range` object, required
    - `from` string, date, required
    - `to` string, date, required
  - `historyFrom` string, date, nullable, required
  - `coverage` IngestCoverage, required
    - `daysWithIngest` integer, required
    - `windowDays` integer, required
    - `continuous` boolean, required: Unbroken daily ingest across the window.
    - `lastSeen` string, date, nullable, required
    - `gaps` string[], required: Days in the window with no log lines received.
  - `bots` BotActivity[], required
    - `botId` string, required
    - `purpose` 'training' | 'live_retrieval', required: `live_retrieval` fetches pages to answer a question now, so a page it cannot fetch cannot be cited in those answers; `training` collects pages for model training.
    - `vendor` string, required
    - `verifiedHits` integer, required: Hits whose IP was confirmed against the vendor's published ranges. The only number that is a signal.
    - `unverifiedHits` integer, required: Hits that merely claimed the user-agent. Anyone can send one. Never add to verifiedHits.
    - `distinctPaths` integer, required
    - `status4xx` integer, required
    - `status5xx` integer, required
    - `verifiable` boolean, required: False for bots whose vendor publishes no ranges; their hits can never be verified.
  - `daily` object, required: Hits per day for the timeline. A day with no log ingest is null in every series — a gap, not a zero. Verified and unverified stay apart here too.
    - `days` string[], required: Every day in the range, ascending. The per-bot series are index-aligned with it.
    - `ingested` boolean[], required
    - `bots` object[], required: Most verified hits first.
      - `botId` string, required
      - `purpose` 'training' | 'live_retrieval', required
      - `vendor` string, required
      - `verified` integer[], required
      - `unverified` integer[], required
  - `totals` object, required
    - `verified` integer, required
    - `unverified` integer, required
    - `liveRetrieval` integer, required: Verified hits by live-retrieval bots.
    - `training` integer, required: Verified hits by training crawlers.

## Other responses

- `404`: `not_found`: no such resource in this workspace.
- `default`: Every failure has this body.

---

[API](https://skmtc.dev/shruwd/apis/shruwd-api.md) · [All operations](https://skmtc.dev/shruwd/apis/shruwd-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shruwd/apis/shruwd-api/revisions/64a5da079928?raw)