Traffic
AI crawler requests to the brand’s site and AI-referred visits from it, from the connected Cloudflare and GA4 accounts. Beta: these shapes may change; see the changelog.
Read AI-referred visits
Section titled “Read AI-referred visits”GET /audits/{auditId}/ai-referral-traffic
Sessions that arrived from an AI surface (ChatGPT, Perplexity, Gemini…), by day and source over the last 90 days, plus the 50 landing pages they reached most. Empty until a GA4 property is connected and pulled.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/ai-referral-traffic" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.points | object[] | yes | |
data.points[].source | string | yes | |
data.points[].sessions | integer | yes | |
data.points[].reportDate | string | yes | |
data.pages | object[] | yes | At most 50, most sessions first. |
data.pages[].landingPage | string | yes | |
data.pages[].sessions | integer | yes | |
data.pages[].keyEvents | integer | null | yes | |
data.connectionStatus | string | null | yes | The analytics connection’s state; null when none is connected. |
data.connectionUpdatedAt | string | null | yes | |
data.lastPull | ReferralPull | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "points": [], "pages": [], "connectionStatus": null, "connectionUpdatedAt": null, "lastPull": null }}Re-crawl the brand’s site
Section titled “Re-crawl the brand’s site”POST /audits/{auditId}/crawl
Queues a crawl of the audit’s site. mode defaults to force_fresh, which always crawls; reuse_if_fresh keeps a completed crawl under 7 days old; skip keeps whatever crawl exists. This starts paid work.
curl -X POST "https://api.beket.ai/api/v1/audits/AUDIT_ID/crawl" \ -H "Authorization: Bearer $BEKET_API_KEY" \ -H "Content-Type: application/json" \ -d '{"mode":"<mode>"}'Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
mode | “skip” | “reuse_if_fresh” | “force_fresh” |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.message | string | yes |
Read AI crawler activity
Section titled “Read AI crawler activity”GET /audits/{auditId}/crawl-diagnostics
The last 30 days of AI crawler requests from the connected Cloudflare zone: one row per day, the 50 busiest bots, the 25 most-crawled pages broken down by the 6 busiest crawlers, and the 10 largest referral sources. A day with crawlPulled: false was not measured — its null counts are unknown, not zero.
curl "https://api.beket.ai/api/v1/audits/AUDIT_ID/crawl-diagnostics" \ -H "Authorization: Bearer $BEKET_API_KEY"Parameters
Section titled “Parameters”| Name | In | Required | Type | Description |
|---|---|---|---|---|
auditId | path | yes | string | The audit’s id. |
Response
Section titled “Response”| Field | Type | Required | Description |
|---|---|---|---|
success | boolean | yes | |
data | object | yes | |
data.connectionStatus | string | null | The analytics connection’s state; null when none is connected. | |
data.connectionUpdatedAt | string | null | ||
data.zoneTag | string | null | ||
data.referralUnit | string | null | ||
data.lastCrawlPullAt | string | null | ||
data.daysCovered | integer | yes | |
data.lastReferralPull | ReferralPull | ||
data.days | object[] | yes | Exactly 30, oldest first. |
data.days[].day | string | yes | |
data.days[].crawlPulled | boolean | yes | |
data.days[].crawlRows | integer | yes | |
data.days[].requests | integer | null | yes | |
data.days[].byPurpose | object | null | yes | |
data.days[].byPurpose.training | integer | yes | |
data.days[].byPurpose.search | integer | yes | |
data.days[].byPurpose.browsing | integer | yes | |
data.days[].referrals | integer | null | yes | |
data.days[].ga4Referrals | integer | null | ||
data.bots | object[] | yes | At most 50. |
data.bots[].botName | string | yes | |
data.bots[].detector | string | yes | |
data.bots[].requests | integer | yes | |
data.bots[].blockedRequests | integer | null | ||
data.bots[].daysSeen | integer | yes | |
data.bots[].sampleRate | number | null | ||
data.bots[].purpose | “training” | “search” | “browsing” | null | ||
data.pages | object[] | yes | At most 25. |
data.pages[].path | string | yes | |
data.pages[].requests | integer | yes | |
data.pages[].byCrawler | integer[] | yes | Requests per crawler, in pageColumns order. |
data.pages[].other | integer | yes | Requests from crawlers outside pageColumns. |
data.pages[].daysSeen | integer | yes | |
data.pageColumns | object[] | yes | At most 6. |
data.pageColumns[].botName | string | yes | |
data.pageColumns[].live | boolean | yes | A user-triggered fetch rather than a crawl. |
data.referralSources | object[] | yes | At most 10. |
data.referralSources[].provider | string | yes | |
data.referralSources[].source | string | yes | |
data.referralSources[].units | integer | yes | |
data.referralSources[].unit | string | yes | |
data.referralSources[].daysSeen | integer | yes | |
data.liveDemand | object | null | User-triggered fetches — an AI surface reading a page to answer someone now. | |
data.liveDemand.liveRequests | integer | yes | |
data.liveDemand.requests | integer | yes | |
data.liveDemand.daysMeasured | integer | yes | |
data.liveDemand.pages | object[] | yes | At most 5. |
data.liveDemand.pages[].path | string | yes | |
data.liveDemand.pages[].requests | integer | yes | |
data.liveDemand.pages[].liveRequests | integer | yes |
Example response (200)
Section titled “Example response (200)”{ "success": true, "data": { "connectionStatus": null, "connectionUpdatedAt": null, "zoneTag": null, "referralUnit": null, "lastCrawlPullAt": null, "daysCovered": 0, "lastReferralPull": null, "days": [], "bots": [], "pages": [], "pageColumns": [], "referralSources": [], "liveDemand": null }}Schemas
Section titled “Schemas”ReferralPull
Section titled “ReferralPull”The last referral pull; null before the first.
| Field | Type | Required | Description |
|---|---|---|---|
pulledAt | string | yes | |
windowDays | integer | yes | |
rawRows | integer | null | yes | |
sampleInterval | number | null | yes | GA4’s sampling interval; null when the pull was unsampled. |