Tráfego de IA e de agentes

O que a IA envia realmente para o seu site: o tráfego de referência abrange as pessoas que chegam a partir de assistentes de IA e o tráfego de agentes abrange os rastreadores de IA que acedem ao seu servidor de origem.

GET`/metrics/ai_traffic`

Devolve o tráfego com origem em IA medido a partir do fornecedor de análise web ligado a um projeto (Google Analytics 4, Adobe Analytics, PostHog, Plausible ou Piano): utilizadores, sessões e conversões por dia, agrupados por origem de IA (ChatGPT, Perplexity, Gemini, Claude e outros), com totais e uma taxa de conversão. Requer o plano Scale ou superior e um fornecedor ligado; os projetos sem um devolvem ERR_AI_TRAFFIC_NOT_CONNECTED (404).

Parâmetros:

project_idobrigatório
range
from
to
granularityday|week|month
sourcerestringir a uma origem de IA

GET`/web_analytics/schema`

Descreve como consultar em tempo real o fornecedor de análise web ligado ao projeto: o fornecedor e a propriedade, o formato de consulta nativo que aceita, os campos de nível superior permitidos, as regras que este endpoint aplica, um exemplo prático e, quando o fornecedor o disponibiliza, a respetiva lista de campos obtida em tempo real (todas as dimensões e métricas do GA4, incluindo as definições personalizadas, os IDs de dimensões e métricas da Adobe, os métodos de relatório do Matomo, os eventos recentes do PostHog e o catálogo do Plausible). Fica em cache durante uma hora. Ao contrário de /metrics/ai_traffic, que devolve os números de tráfego de referência de IA já guardados pela sincronização do Tráfego de IA, estes endpoints leem diretamente o fornecedor. Os projetos sem um fornecedor ligado devolvem ERR_WEB_ANALYTICS_NOT_CONNECTED (404). Requer o plano Growth ou superior. MCP: get_web_analytics_schema.

Parâmetros:

project_idobrigatório

POST`/web_analytics/query`

Executa uma consulta em tempo real, só de leitura, no fornecedor de análise web ligado ao projeto e devolve colunas e linhas. Escreva a consulta no formato próprio do fornecedor: um corpo GA4 Data API runReport, um pedido de relatório do Adobe Analytics ou do Customer Journey Analytics, parâmetros da Matomo Reporting API (apenas métodos get), PostHog HogQL, uma consulta Plausible Stats API v2 ou um corpo Piano getData. A consulta usa sempre a propriedade, o site, o conjunto de relatórios ou o projeto ligado, e qualquer campo de propriedade incluído na consulta é ignorado. Por predefinição, são devolvidas 100 linhas, com um máximo de 5 000; as consultas idênticas são respondidas a partir de uma cache de 10 minutos (cached: true). Uma consulta rejeitada pelo fornecedor devolve ERR_WEB_ANALYTICS_INVALID_QUERY (422) com a mensagem de validação do próprio fornecedor. Cada consulta não servida pela cache consome a quota da API do fornecedor, que é partilhada com a sincronização do Tráfego de IA, e cada projeto permite 20 consultas não servidas pela cache por minuto (ERR_WEB_ANALYTICS_UPSTREAM, 503, com Retry-After). Requer o plano Growth ou superior; não é necessária uma chave com âmbito de escrita. MCP: query_web_analytics.

Corpo (JSON): project_id (obrigatório), query (obrigatório): o objeto de consulta nativo ou, no caso do PostHog, a string HogQL ou {"query": "SELECT ..."}.

GET`/metrics/agent_traffic`

Tráfego agregado de bots de IA de um projeto, agrupado por bot ou por empresa, com granularidade diária, semanal ou mensal.

Parâmetros:

project_idobrigatório
range
from
to
bot
company
group_bybot|company
granularityday|week|month

GET`/dimensions/agent_bots`

Catálogo estático dos bots de IA que o Agent Analytics consegue identificar. Utilize-o para criar interfaces de filtragem que espelhem a nossa classificação interna (slug, nome apresentado, empresa, categoria, mapeamento de bots verificados da Cloudflare). Requer o plano Scale ou superior; a ferramenta MCP list_agent_bots está disponível no plano Scale ou superior.

Parâmetros:

project_idobrigatório, mas ignorado: o catálogo é o mesmo em todos os projetos

Exemplos de código

Download: OpenAPI Swagger Postman

Perguntar à IA: Abrir no ChatGPT Abrir no Claude Ver como Markdown

Linguagem

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());

Tráfego de IA e de agentes

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`