AI & Agent Traffic

What AI actually sends to your site: referral traffic covers humans arriving from AI assistants, agent traffic covers the AI crawlers hitting your origin server.

GET`/metrics/ai_traffic`

Returns the AI-referred traffic measured from a project's connected web analytics provider (Google Analytics 4, Adobe Analytics, PostHog, Plausible or Piano): per-day users, sessions and conversions grouped by AI source (ChatGPT, Perplexity, Gemini, Claude and others), with totals and a conversion rate. Requires the Scale plan or above and a connected provider; projects without one return ERR_AI_TRAFFIC_NOT_CONNECTED (404).

Params:

project_idrequired
range
from
to
granularityday|week|month
sourcerestrict to one AI source

GET`/web_analytics/schema`

Describes how to query the project's connected web analytics provider live: which provider and property, the native query format it accepts, the allowed top-level fields, the rules this endpoint enforces, a worked example and, where the provider offers it, its live field list (every GA4 dimension and metric including custom definitions, Adobe dimension and metric ids, Matomo report methods, recent PostHog events, the Plausible catalog). Cached for an hour. Unlike /metrics/ai_traffic, which returns the AI referral numbers already stored by the AI Traffic sync, these endpoints read the provider directly. Projects without a connected provider return ERR_WEB_ANALYTICS_NOT_CONNECTED (404). Requires the Growth plan or above. MCP: get_web_analytics_schema.

Params:

project_idrequired

POST`/web_analytics/query`

Runs a live, read-only query against the web analytics provider connected to the project and returns columns and rows. Write the query in the provider's own format: a GA4 Data API runReport body, an Adobe Analytics or Customer Journey Analytics report request, Matomo Reporting API parameters (get methods only), PostHog HogQL, a Plausible Stats API v2 query or a Piano getData body. The connected property, site, report suite or project is always used and any property field in the query is ignored. Rows default to 100 and are capped at 5,000; identical queries are answered from a 10-minute cache (cached: true). A query the provider rejects returns ERR_WEB_ANALYTICS_INVALID_QUERY (422) with the provider's own validation message. Each uncached query spends the provider API quota the AI Traffic sync shares, and a project allows 20 uncached queries a minute (ERR_WEB_ANALYTICS_UPSTREAM, 503, with Retry-After). Requires the Growth plan or above; no writable key is needed. MCP: query_web_analytics.

JSON body: project_id (required), query (required): the native query object, or for PostHog the HogQL string or {"query": "SELECT ..."}.

GET`/metrics/agent_traffic`

Aggregated AI bot traffic for a project, grouped by bot or by company, with daily/weekly/monthly granularity.

Params:

project_idrequired
range
from
to
bot
company
group_bybot|company
granularityday|week|month

GET`/dimensions/agent_bots`

Static catalog of AI bots that Agent Analytics can identify. Use it to render filter UIs that mirror our internal classification (slug, display name, company, category, Cloudflare verified-bot mapping). Requires Scale or above; the MCP tool list_agent_bots is available on the Scale plan or above.

Params:

project_idrequired

Code Examples

Download: OpenAPI Swagger Postman

Ask AI: Open in ChatGPT Open in Claude View as Markdown

Language

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/ai_traffic?project_id=PROJECT_ID&range=30&granularity=day"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID"

const response = await fetch("https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/web_analytics/schema?project_id=PROJECT_ID"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}}' \
  "https://api.llmpulse.ai/api/v1/web_analytics/query"

const response = await fetch("https://api.llmpulse.ai/api/v1/web_analytics/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}})
});
const data = await response.json();

import requests

response = requests.post(
    "https://api.llmpulse.ai/api/v1/web_analytics/query",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}}
)
data = response.json()

require 'httparty'

response = HTTParty.post(
  "https://api.llmpulse.ai/api/v1/web_analytics/query",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" },
  body: {"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}}
)
data = response.parsed_response

req, _ := http.NewRequest("POST", "https://api.llmpulse.ai/api/v1/web_analytics/query", strings.NewReader(`{"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}}`))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.llmpulse.ai/api/v1/web_analytics/query', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'json' => {"project_id":"PROJECT_ID","query":{"dateRanges":[{"startDate":"28daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"sessionDefaultChannelGroup"}],"metrics":[{"name":"sessions"},{"name":"keyEvents"}],"limit":20}}
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/web_analytics/query"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("{\"project_id\":\"PROJECT_ID\",\"query\":{\"dateRanges\":[{\"startDate\":\"28daysAgo\",\"endDate\":\"yesterday\"}],\"dimensions\":[{\"name\":\"sessionDefaultChannelGroup\"}],\"metrics\":[{\"name\":\"sessions\"},{\"name\":\"keyEvents\"}],\"limit\":20}}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/agent_traffic?project_id=PROJECT_ID&range=30&group_by=bot&granularity=day"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Request

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID"

const response = await fetch("https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/dimensions/agent_bots?project_id=PROJECT_ID"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

AI & Agent Traffic

GET/metrics/ai_traffic

GET/web_analytics/schema

POST/web_analytics/query

GET/metrics/agent_traffic

GET/dimensions/agent_bots

GET`/metrics/ai_traffic`

GET`/web_analytics/schema`

POST`/web_analytics/query`

GET`/metrics/agent_traffic`

GET`/dimensions/agent_bots`