CrUX History API: como medir o antes e depois de uma campanha sem esperar 28 dias

Todo time de growth já viveu esta cena: sobe uma landing page nova para a campanha, otimiza imagem, corta script de terceiro, e o pessoal de SEO técnico pergunta "melhorou o Core Web Vitals?". A resposta padrão é frustrante: "espera 28 dias". Isso acontece porque os dados de campo do Chrome (CrUX) são uma média móvel de 28 dias. Mas existe um caminho para reduzir a espera e, principalmente, para provar a tendência com número: a CrUX History API, documentada no Chrome for Developers.

O que a History API entrega que a API diária não entrega

A API diária da CrUX devolve um retrato único: o p75 atual, o histograma atual. A History API devolve a série temporal. Segundo a documentação, ela dá acesso de baixa latência a dados históricos de experiência de usuários reais, na granularidade da página e da origem, tanto no nível de origem (o site inteiro) quanto no nível de URL (uma página específica). Na prática, o teto é ainda maior: a API guarda as 40 semanas anteriores (cerca de 10 meses), uma coleta por semana, e por padrão retorna 25 períodos. Dá para pedir de 1 a 40 com o campo collectionPeriodCount.

A diferença de estrutura em relação à API diária é direta: os valores viram arrays e as chaves ganham nome no plural. Onde a diária tem histogram, a histórica tem histogramTimeseries; onde tem p75, tem p75s. Cada posição do array corresponde a um período de coleta, do mais antigo para o mais recente.

Por que ainda existe atraso (e como conviver com ele)

Aqui está a parte que separa quem usa a ferramenta com honestidade de quem promete milagre. A History API não elimina a janela de 28 dias, ela a torna visível ao longo do tempo. Cada ponto da série continua sendo uma média móvel de 28 dias, e os períodos são semanais, então eles se sobrepõem: entre um ponto e o seguinte, três semanas de dados são as mesmas e só uma semana é nova.

O que isso significa para uma campanha? Se a landing subiu numa segunda-feira, a melhoria de LCP não aparece inteira no ponto seguinte. Ela entra diluída, ganhando peso a cada semana conforme os 28 dias vão sendo tomados pelo período pós-otimização. Por isso a leitura certa não é "o número mudou de X para Y", e sim "a curva começou a descer nesta semana e estabilizou num patamar melhor quatro semanas depois". A tendência é o argumento, não o ponto isolado.

Dois detalhes operacionais reforçam isso: a base é atualizada toda segunda-feira por volta das 04:00 UTC, com dados até o sábado anterior (o lag padrão de 2 dias), e não há SLA de horário. E repetir a chamada dentro da mesma semana devolve exatamente o mesmo resultado, então não adianta ficar fazendo poll diário esperando o número mexer.

A consulta na prática

Nota da redação: o código desta seção não foi executado em ambiente real. Valide antes de usar em produção.

A chamada é um POST para o endpoint queryHistoryRecord (note o History no nome, que substitui o queryRecord da API diária). Precisa de uma chave do Google Cloud↳Google Cloud13 conteúdosPrograma da Google Cloud no Brasil projeta formar de forma gratuita 30 mil universitáriosDev (Back & Front) · mar 2026Google Cloud OnBoard capacita estudantes e desenvolvedores de TIGestão Dev & TI · mai 2019Desenvolvedores poderão participar de treinamento gratuito do Google CloudGestão Dev & TI · mai 2019Ver tudo em DevSecOps → provisionada para o Chrome UX↳UX33 conteúdosUX e IA: Transformando Experiências Digitais com Inteligência ArtificialProduto & UX · jan 2025UX, IA e Front-End: quando experiência, inteligência e código se encontram para criar o futuro digitalProduto & UX · jul 2025Novidades em UX/UI para 2025: O futuro do design de experiências digitaisProduto & UX · abr 2025Ver tudo em Produto & UX → Report, a mesma que serve para a API diária. Para medir uma página específica de campanha, o segredo é passar url em vez de origin, o que restringe os dados àquela URL exata:

curl -s --request POST \
  'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://loja.exemplo.com.br/promo-black-friday",
    "formFactor": "PHONE",
    "metrics": ["largest_contentful_paint", "cumulative_layout_shift", "interaction_to_next_paint"],
    "collectionPeriodCount": 40
  }'

O formFactor aceita PHONE, TABLET ou DESKTOP, e a History API só agrega por essa dimensão. Para campanha mobile-first, PHONE é o recorte que importa. Se você omitir a lista de metrics, a API devolve tudo o que houver, incluindo métricas úteis para diagnóstico de LCP como largest_contentful_paint_image_time_to_first_byte e largest_contentful_paint_image_element_render_delay, além de round_trip_time e navigation_types.

A resposta traz, para cada métrica, o histogramTimeseries (percentual de carregamentos em cada faixa: bom, precisa melhorar, ruim) e o percentilesTimeseries com os p75s. Um trecho de p75 de LCP se parece com isto, do período mais antigo ao mais recente:

"percentilesTimeseries": {
  "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
}

Para alinhar cada número a uma data, use o array collectionPeriods, que vem em ordem ascendente com firstDate e lastDate de cada janela de 28 dias. É esse casamento entre p75s[i] e collectionPeriods[i] que permite marcar no gráfico a semana em que a landing entrou no ar.

O buraco na série: dados faltantes

Um ponto que costuma pegar quem monta o dashboard: nem todo período tem dado elegível. URLs de campanha, por natureza, têm tráfego que sobe e desce. Quando uma janela não bate o mínimo de amostras, a API devolve "NaN" nas densidades do histograma e null nos percentis para aquele período. A documentação explica a diferença: densidade é sempre número, mas percentil pode ser número ou string (o CLS vem como string, mesmo parecendo número).

"p75s": [1362, null, 1344, 1356, 1366, 1377]

Para URLs ou origens que se tornam e deixam de ser qualificadas ao longo do tempo, como diz a fonte, dá para ver muitos buracos. Isso tem uma consequência tática: página de campanha com pouco tráfego pode simplesmente não aparecer no nível de URL. Nesse caso, a saída é medir no nível de origin (o site todo) ou aceitar que a prova de campo não virá dessa fonte.

Onde isso brilha e onde não vale a pena

O caso de uso mais forte é justamente o do editor desta pauta: um time de growth no Brasil que subiu uma landing de campanha, otimizou LCP e INP, e quer provar o impacto sem contratar uma ferramenta de RUM paga. A History API cobre isso de graça, com dados de usuários reais do Chrome, e a série de 40 semanas dá o antes e o depois num só request.

Como eu montaria: puxar a série no nível de URL para PHONE, cruzar p75s com collectionPeriods, marcar a semana do deploy e observar quatro a seis pontos depois. A leitura da subida gradual da faixa "boa" no histogramTimeseries costuma ser mais convincente para stakeholder do que o p75 sozinho, porque mostra a proporção de usuários beneficiados.

Onde não vale: nada de landing de campanha-relâmpago que fica no ar dez dias. Com a média móvel de 28 dias e a granularidade semanal, esse tempo não constrói uma série legível, e você vai colher NaN. Também não sirva a History API como monitoramento em tempo real, para isso o caminho é RUM próprio (por exemplo, coletar Web Vitals no cliente e enviar para o seu backend↳Back-end49 conteúdosIntegração front-end com backend: 7 decisões que evitam caos entre APIs, BFF e GraphQLDev (Back & Front) · abr 2026Como criar uma FAKE API REST para testes — JSONPlaceholderDev (Back & Front) · set 2025Construindo um aplicativo de bate-papo de IA simples com Spring AI e AngularDev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) →), que enxerga o efeito no mesmo dia. A CrUX é auditoria e prova de tendência, não alerta de incidente. Os dois se complementam: RUM para reagir rápido, History API para provar o resultado com a mesma base que o Google usa para ranqueamento.

Fonte: Documentação do Chrome UX Report History API (Google for Developers)