PageLens Analytics

npx add-mcp 'https://app.pagelens.io/mcp'

Tudo o que você vê no dashboard do PageLens está disponível como JSON. Use a API REST a partir de scripts e backends, ou conecte o servidor MCP para que Claude, Cursor e outros assistentes de IA possam responder perguntas sobre o seu tráfego.

Chaves de API

Crie chaves no dashboard em API & MCP. Uma chave age como você, com o mesmo acesso que você tem a cada site. Ao criar uma, você escolhe:

• Somente leitura ou Leitura e escrita. Chaves de escrita também podem criar metas, funis e anotações, atualizar configurações do site, adicionar sites e enviar eventos do lado do servidor.
• Todos os sites ou um site.

As chaves começam com pl_ e são exibidas apenas uma vez. Armazenamos apenas um hash. Envie-as no cabeçalho Authorization:

Authorization: Bearer pl_your_key

As chaves não podem gerenciar outras chaves, cobrança ou membros, e não podem excluir sites. Essas ações exigem uma sessão de navegador com login.

Servidor MCP

Endpoint: https://app.pagelens.io/mcp (HTTP transmissível). Autentique com uma chave de API.

Claude Code

claude mcp add --transport http pagelens https://app.pagelens.io/mcp \
  --header "Authorization: Bearer pl_your_key"

Cursor, Windsurf e outros clientes com suporte a servidor remoto

{
  "mcpServers": {
    "pagelens": {
      "url": "https://app.pagelens.io/mcp",
      "headers": { "Authorization": "Bearer pl_your_key" }
    }
  }
}

Claude Desktop

Adicione isso a claude_desktop_config.json (Configurações → Desenvolvedor → Editar configuração) e reinicie. Requer Node.js.

{
  "mcpServers": {
    "pagelens": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.pagelens.io/mcp",
               "--header", "Authorization: Bearer pl_your_key"]
    }
  }
}

Ferramentas

Ferramenta	O que faz
list_sites	Sites que a chave pode acessar, com visitantes nas últimas 24 horas
get_overview	Visitantes, sessões, visualizações de página, taxa de rejeição e duração, comparados com o período anterior, além de uma série temporal
get_breakdown	Principais páginas, páginas de entrada/saída, referenciadores, canais, tags UTM, países, cidades, navegadores, SO, dispositivos, idiomas, eventos
get_pages	Visitantes por página, entradas, taxa de rejeição e tempo na página
get_realtime	Visitantes online agora e o que estão visualizando
list_sessions, get_session	Sessões e a linha do tempo completa de uma sessão
get_events	Eventos personalizados e cliques externos com propriedades
get_errors, get_web_vitals	Erros de JavaScript; percentis de LCP, INP, CLS, FCP e TTFB
get_journeys, run_funnel	Caminhos comuns; conversão passo a passo
list_goals, list_segments	Metas com taxas de conversão; segmentos salvos (qualquer ferramenta aceita segment_id)
list_users, get_user, get_retention	Usuários identificados, perfis e retenção de coorte
get_bots_and_ai	Crawlers de IA, assistentes de IA, bots de busca e visitas referidas por ChatGPT, Perplexity, Claude e outros
create_goal, add_annotation	Somente chaves de escrita: criar uma meta, marcar uma data nos gráficos

API REST

URL base: https://app.pagelens.io. As respostas são JSON. Os timestamps estão em ISO 8601 no UTC.

curl "https://app.pagelens.io/api/sites/SITE_ID/overview?from=2026-09-01T00:00:00Z&to=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer pl_your_key"

Parâmetros de consulta comuns

Parâmetro	Descrição
from, to	Datas ISO ou timestamps. to é exclusivo. Padrão: os últimos 7 dias.
tz	Fuso horário IANA usado para agrupar dias e horas, ex.: Europe/Berlin. Padrão: UTC.
bucket	hour, day, week ou month para séries temporais. Escolhido automaticamente se omitido.
filter	dimension:value repetível, ex.: filter=country:DE&filter=channel:Organic%20Search. Mantém sessões inteiras que correspondem. Operadores vão após a dimensão: page!:/x é não, page~:blog contém, page!~:blog não contém, page^:/docs começa com (codifique na URL ^ e ~).
segment	ID de um segmento salvo (GET /api/sites/:id/segments). Seus filtros são combinados com qualquer filter.
limit	Linhas para listas (padrão 10, máximo 500).

Dimensões de filtro e detalhamento: page, title, hostname, referrer, channel, utm_source, utm_medium, utm_campaign, browser, os, device, screen, country, city, language, event. Detalhamentos também aceitam entry, exit e outbound.

Endpoints

Método e caminho	Retorna
GET /api/sites	Seus sites
GET /api/sites/:id	Um site com suas configurações
GET /api/sites/:id/overview	Totais de current e previous, series, previousSeries
GET /api/sites/:id/breakdown/:dimension	rows de valor, visitantes, sessões, contagem. Suporta search.
GET /api/sites/:id/pages	Métricas por página
GET /api/sites/:id/realtime	Visitantes nos últimos 5 minutos
GET /api/sites/:id/sessions	Sessões. tab = engajadas, rejeitadas, erros ou replay. user = um ID de usuário identificado.
GET /api/sites/:id/sessions/:sid	Eventos de uma sessão
GET /api/sites/:id/events	Eventos personalizados e propriedades
GET /api/sites/:id/errors	Erros de JavaScript
GET /api/sites/:id/performance	Web Vitals
GET /api/sites/:id/journeys	Caminhos comuns
GET /api/sites/:id/goals	Metas com conversões
POST /api/sites/:id/funnel	Corpo {"steps":[{"type":"page","value":"/"},{"type":"event","value":"signup"}]}
GET /api/sites/:id/users	Usuários. tab = identificado ou anônimo. Suporta search.
GET /api/sites/:id/users/:uid	Perfil e sessões de um usuário
GET /api/sites/:id/retention	Coortes; unit = dia ou semana
GET /api/sites/:id/bots	Tráfego de bots e IA
GET /api/sites/:id/export/:type	Download em CSV
GET /api/sites/:id/segments	Segmentos salvos
POST /api/sites/:id/goals, /funnels, /annotations, /segments	Chaves de escrita: criar. DELETE …/:itemId remove.

Eventos do lado do servidor

Rastreie eventos do seu backend (pagamentos, inscrições, webhooks) com uma chave de escrita. Envie o IP e o user agent do visitante se você os tiver; eles são usados para localização e dispositivo e não são armazenados.

curl https://app.pagelens.io/api/track \
  -H "Authorization: Bearer pl_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "SITE_ID",
    "type": "custom_event",
    "name": "purchase",
    "url": "https://example.com/checkout",
    "props": { "plan": "pro", "amount": 49 },
    "ip": "203.0.113.7",
    "user_agent": "Mozilla/5.0 ..."
  }'

Limites e erros

Plano	Requisições por dia
Teste gratuito	5.000
Starter	2.000
Pro	10.000
Business	50.000

Cada chave também está limitada a 120 requisições por minuto. As respostas incluem X-RateLimit-Limit e X-RateLimit-Remaining. Quando você atinge um limite, recebe 429 com Retry-After.

Os erros têm a aparência de {"error": "message"}:

• 401: chave ausente, inválida ou revogada.
• 402: o teste terminou.
• 403: a chave não pode chamar esta rota.
• 404: o site não está acessível com esta chave.

Perguntas ou endpoints ausentes: hello@pagelens.io