PostHog

Métricas diárias de Web Analytics e entidades de produto de todos os projetos de uma organização PostHog, com o acesso de cada projeto.

O conector PostHog lê as métricas diárias do Web Analytics e as entidades de produto (pessoas, grupos, coortes, feature flags, pesquisas e anotações) de todos os projetos que a chave enxerga na organização, e leva ao Data Catalog o acesso que cada projeto define.

Status	Disponível
Conteúdo	Registros
Autenticação	Personal API key
Permissões	Por item
Sincronização	Incremental e full refresh, por recurso
Última revisão	06/10/2026

Capacidades

• Traz ao Data Catalog as consultas do próprio dashboard de Web Analytics do PostHog, dia a dia, com o filtro de contas de teste ligado: visitantes, visualizações, sessões, duração e taxa de rejeição, e oito cortes (canal, UTM, domínio de origem e páginas).
• Traz pessoas, grupos, coortes, feature flags, pesquisas, respostas de pesquisa e anotações.
• Lê todos os projetos da organização da chave em uma única conexão. O projeto é a coluna project_id de cada tabela, não um recurso.
• Aplica o acesso do PostHog por projeto e por tipo de recurso (ver Permissões).
• Alimenta o Memory pelo recurso persons: o fragmento de ontologia do conector declara persons como nó Customer, que se funde com o contato do CRM pelo mesmo e-mail ou telefone. O nó só entra no grafo depois que a ontologia unificada é aplicada. Os demais recursos ficam no Data Catalog e não viram nós.

Recursos disponíveis

Todo recurso nasce desligado no Data Catalog. Você escolhe quais carregar depois de conectar.

Recurso	O que contém	Carga	Cursor	Destino	Permissão por item
web_overview_daily	Uma linha por projeto e dia: visitors, views, sessions, session_duration_s e bounce_rate_pct	Full refresh, incremental opcional	day	Catálogo	Sim
web_stats_daily	Uma linha por projeto, dia, corte e valor do corte, com visitors, views e bounce_rate_pct	Full refresh, incremental opcional	day	Catálogo	Sim
persons	Pessoas identificadas, com email, phone, distinct_ids, properties e last_seen_at	Full refresh	—	Catálogo e Memory	Sim
groups	Grupos de todos os tipos de grupo do projeto	Full refresh	—	Catálogo	Sim
cohorts	Coortes, com is_static e count	Full refresh	—	Catálogo	Sim
feature_flags	Feature flags, com key, active, rollout_percentage e filters	Full refresh	—	Catálogo	Sim
surveys	Pesquisas, com tipo, perguntas e datas	Full refresh	—	Catálogo	Sim
survey_responses	Respostas das pesquisas, com o texto das respostas concatenado em answers_text	Full refresh	—	Catálogo	Sim
annotations	Anotações do projeto	Full refresh	—	Catálogo	Sim

Os oito cortes de web_stats_daily, na coluna breakdown_by: InitialChannelType, InitialUTMSource, InitialUTMMedium, InitialUTMCampaign, InitialReferringDomain, Page, InitialPage e ExitPage. Os oito são ligados e desligados juntos.

Cada linha de web_overview_daily e web_stats_daily também traz o fuso do projeto (project_timezone), se o PostHog serviu um resultado em cache (is_cached) e o instante da leitura (fetched_at).

Como ler as métricas

• visitors é uma contagem de pessoas distintas. Não some visitors entre dias nem entre valores de um corte: a mesma pessoa que volta em três dias seria contada três vezes. Some só views e sessions.
• bounce_rate_pct vai de 0 a 100, a mesma escala que o dashboard mostra, nas duas tabelas. Não tire a média simples da taxa entre dias, porque ela ignora o peso das sessões de cada dia.
• day é o dia do calendário no fuso do projeto.
• Os valores são os do dashboard de Web Analytics com filter test accounts ligado, não os de um insight qualquer.

Permissões (ACL)

O conector lê a permissão de cada item na fonte e a guarda junto com o dado. Em Comportamento dos dados, você escolhe entre dois modos:

Modo	Quem vê
Aberto	Quem puder usar este conector vê todos os registros. As permissões da fonte são ignoradas.
Espelhar a fonte	Cada pessoa vê apenas os registros que a própria fonte libera para ela.

No passo de acesso do assistente de criação, o Comportamento dos dados começa em “Aberto”. Mude para “Espelhar a fonte” se quiser que as restrições do PostHog valham na Strattum.

No modo “Espelhar a fonte”, a Strattum reconhece cada pessoa pelo e-mail que ela tem no PostHog e presume que é o mesmo da Strattum. A presunção só vale quando a equipe da Strattum a habilita para a instância e para o domínio de e-mail da sua empresa. Sem essa habilitação, ninguém é reconhecido pelo e-mail do PostHog, os registros de um projeto restrito não aparecem para ninguém e nenhum erro é exibido. O PostHog não tem a opção Exigir login na fonte como prova de identidade.

Como a fonte define acesso

O PostHog concede acesso por projeto e, dentro dele, por tipo de recurso. Nenhuma linha tem permissão própria: o acesso vale para o projeto inteiro ou para o tipo de recurso inteiro.

Como a Strattum traduz o acesso

A Strattum lê, uma vez por projeto a cada sincronização, se o projeto está aberto à organização e quem tem acesso a ele. O resultado vale para todas as linhas do projeto e do tipo de recurso.

Situação do projeto	Quem recebe acesso à linha
Aberto à organização	Todos os usuários da Strattum que podem usar o conector, sem depender de estarem no PostHog.
Restrito	Só os membros da organização que o PostHog libera para aquele projeto e tipo de recurso, identificados pelo e-mail.

Um projeto está aberto quando o acesso padrão do projeto é member ou admin e, nos recursos que têm tipo próprio, o acesso padrão do tipo herda o do projeto ou é viewer, editor ou manager. Qualquer outro valor, resposta ausente ou resposta ilegível conta como restrito.

Em um projeto restrito, o membro entra quando o acesso efetivo dele ao projeto é member ou admin e, nos recursos com tipo próprio, o acesso efetivo ao tipo é viewer, editor ou manager.

Recurso	O que decide o acesso
web_overview_daily, web_stats_daily	Tipo web_analytics
feature_flags	Tipo feature_flag
surveys, survey_responses	Tipo survey
persons, groups, cohorts, annotations	Só o acesso ao projeto

Se o PostHog não informar um tipo de recurso, ninguém recebe acesso aos recursos que dependem dele. Todo erro de leitura reduz o acesso, nunca o amplia.

Quando a identidade não é encontrada

• Membro do PostHog sem e-mail cadastrado não recebe acesso, e a execução registra quantos foram ignorados.
• Membro cujo e-mail no PostHog é diferente do e-mail na Strattum, ou de um domínio que a instância não aceita, não vê os registros de projetos restritos.
• Linha sem nenhum usuário com acesso fica invisível no modo “Espelhar a fonte”.

Quando a permissão é atualizada

A permissão é recalculada em todo sync. As entidades são reescritas por inteiro a cada execução, então o acesso delas sai sempre atual. Nas tabelas de Web Analytics, que podem ser incrementais, a Strattum compara o acesso de cada projeto com o da execução anterior e reaplica o novo acesso às linhas antigas quando ele muda, inclusive na troca entre projeto aberto e restrito. Um projeto que a chave deixa de alcançar, ou que sai da organização, perde o acesso de suas linhas de Web Analytics na execução seguinte.

Pré-requisitos

• Uma organização PostHog Cloud (US ou UE) ou uma instalação self-hosted acessível por https://.
• Um usuário PostHog estável, de preferência um administrador ou um usuário de serviço. A chave pertence a quem a criou: se essa pessoa sair da organização, o conector para.
• Uma Personal API key criada com acesso a todos os projetos da organização e com os escopos da tabela abaixo.
• Uma só conexão PostHog por instalação da Strattum, que cobre uma organização.

Autenticação e escopos

A autenticação usa uma Personal API key (phx_...) enviada no cabeçalho Authorization. Para limitar os projetos lidos, restrinja a chave aos projetos desejados no PostHog. O conector não tem seletor de projetos.

Escopo	Para quê
project:read	Listar os projetos da organização.
organization_member:read	Ler os membros da organização, para o acesso.
access_control:read	Ler o acesso de cada membro e o acesso padrão de cada projeto.
query:read	Rodar as consultas de Web Analytics.
person:read	Ler persons.
group:read	Ler groups.
cohort:read	Ler cohorts.
feature_flag:read	Ler feature_flags.
survey:read	Ler surveys e survey_responses.
annotation:read	Ler annotations.

Os três primeiros escopos são de organização. Uma chave criada para um projeto específico autentica, mas o PostHog nega o acesso às permissões, e o teste de conexão falha. Sem access_control:read ninguém enxerga os dados.

1. Abra as chaves pessoais

   No PostHog, abra as configurações da sua conta, na seção Personal API keys.

2. Crie a chave

   Crie uma chave com acesso a todos os projetos da organização e marque os dez escopos da tabela.

3. Copie a chave

   Copie o valor phx_... e guarde. Você o informa no Console.

Configuração no Console

1. Abra o assistente

   Em Conectores, clique em + Nova Conexão e selecione PostHog.

2. Preencha a conexão

   Nome do Conector (Opcional): como a conexão aparece na lista. O padrão é PostHog.

   Região (Obrigatório): Cloud EUA (us.posthog.com), Cloud UE (eu.posthog.com) ou Self-hosted.

   URL do PostHog (Quando selecionado): só para Self-hosted. Precisa começar com https://, e a barra final é removida.

   Personal API key (Obrigatório): a chave phx_....

3. Teste a conexão

   Clique em Testar Conexão. Você só avança depois de um teste com sucesso ou com ressalvas. Com ressalvas, o aviso nomeia o escopo que falta em cada recurso, e você pode seguir sem esses recursos.

4. Escolha a frequência

   Em Sincronização, escolha a frequência. Uma vez por dia basta: o dia de Web Analytics só se estabiliza depois que termina.

5. Defina o acesso

   Em Permissionamento, defina Quem pode usar este conector e o Comportamento dos dados. O padrão é “Aberto”.

6. Revise e salve

   Em Revisão, confira os dados e salve. Depois, no Data Catalog, ligue os recursos que você quer carregar e marque os dados pessoais, se houver. Ver Dados pessoais (PII).

Depois da primeira carga, passe web_overview_daily e web_stats_daily para o modo incremental no Data Catalog. O padrão é full refresh, que relê todo o histórico a cada execução.

Como a sincronização funciona

A frequência vem do passo Sincronização. A referência do conector é uma execução por dia, às 06:00 UTC.

Ordem. Em cada execução, o conector lê os projetos e o acesso, depois os recursos de Web Analytics selecionados, depois as entidades selecionadas. Recurso desligado no Data Catalog não é lido. Todas as chamadas saem uma por vez.

Entidades. persons, groups, cohorts, feature_flags, surveys, survey_responses e annotations são sempre full refresh: a tabela é reescrita a cada execução, e um item apagado no PostHog some dela.

Web Analytics em full refresh (padrão). A tabela é reescrita com os dias de cada projeto, do primeiro evento do projeto até hoje, no máximo 365 dias. Um projeto sem eventos não gera consulta. Se o PostHog não responder qual foi o primeiro evento, o conector lê os 365 dias.

Web Analytics em incremental. Cada projeto retoma do último dia que o conector leu para ele e relê os 3 últimos dias, porque os números de um dia continuam mudando depois que ele passa. Cada dia relido substitui por inteiro o que a tabela tinha para aquele dia. Um projeto novo na organização recebe a janela completa de até 365 dias na mesma execução.

Primeira carga. Cada dia custa uma consulta para web_overview_daily e uma ou mais para cada um dos oito cortes de web_stats_daily. Um projeto com um ano de histórico pode levar mais de uma hora, e o limite de consultas do PostHog é o que define esse tempo.

Falhas. O conector nunca escreve uma leitura incompleta. Se uma página ou um dia falha, o recurso inteiro falha e a tabela anterior é mantida. Uma consulta que o PostHog responde com erro ou sem concluir também falha o dia. Se nenhum projeto for alcançável, a execução para antes de escrever qualquer coisa. Um projeto que nega o acesso às permissões é pulado na execução, e os demais seguem.

Remoção. Nas entidades, o full refresh reflete a remoção. Nas tabelas de Web Analytics, o incremental só substitui os dias lidos: um dia que perde todas as linhas no PostHog só desaparece com um full refresh.

API da fonte

Método e caminho	Usado para	Recurso
GET /api/users/@me/	Descobrir a organização da chave	Todos
GET /api/organizations/{org}/projects/	Listar os projetos	Todos
GET /api/organizations/{org}/projects/{project}/access_control_members/	Acesso efetivo de cada membro	Todos
GET /api/organizations/{org}/projects/{project}/access_control_defaults/	Saber se o projeto está aberto	Todos
POST /api/projects/{project}/query/	Consultas WebOverviewQuery, WebStatsTableQuery e o primeiro evento do projeto	web_overview_daily, web_stats_daily
GET /api/projects/{project}/persons/	Listar pessoas	persons
GET /api/projects/{project}/groups_types/	Listar os tipos de grupo	groups
GET /api/projects/{project}/groups/	Listar grupos de cada tipo	groups
GET /api/projects/{project}/cohorts/	Listar coortes	cohorts
GET /api/projects/{project}/feature_flags/	Listar feature flags	feature_flags
GET /api/projects/{project}/surveys/	Listar pesquisas	surveys, survey_responses
GET /api/projects/{project}/surveys/{survey}/responses/	Listar respostas de cada pesquisa	survey_responses
GET /api/projects/{project}/annotations/	Listar anotações	annotations

A consulta POST /query/ só lê dados.

Rate limits. O PostHog limita as consultas de /query/ por projeto a 2.400 por hora, 240 por minuto e 3 em execução simultânea, com 10 segundos de execução por consulta. Uma Personal API key também consome um orçamento de leitura por hora, por projeto, medido em bytes lidos. Quando ele acaba, o PostHog responde 429 com o código api_queries_budget_exceeded. O conector envia uma consulta por vez, com tempo limite de 10 segundos para conectar e 90 para ler. Diante de um 429, espera o Retry-After quando ele vem, ou um tempo de recuo, soma no máximo 900 segundos de espera por requisição e tenta de novo. Erros 5xx e conexões interrompidas têm até 5 tentativas com recuo crescente.

Referência oficial: PostHog, API de consultas

Limitações conhecidas

• Em um projeto aberto, todo usuário que pode usar o conector vê os dados, mesmo um membro que o PostHog tenha deixado sem acesso. Para restringir, use um projeto restrito no PostHog ou limite Quem pode usar este conector.
• No modo “Espelhar a fonte”, projetos restritos só aparecem para quem a equipe da Strattum habilitou por e-mail e domínio. Sem a habilitação, esses registros não aparecem para ninguém. Para liberar o conteúdo agora, use “Aberto” e limite o acesso em Quem pode usar este conector.
• O PostHog não permite vincular a conta de cada usuário: a identidade é presumida pelo e-mail.
• A chave pertence a uma pessoa do PostHog. Se ela sair da organização, o conector para até a chave ser trocada.
• A Web Analytics traz só as consultas do dashboard e os oito cortes listados. Países, dispositivos e eventos brutos ficam de fora, assim como notebooks, insights, dashboards e gravações de sessão.
• A primeira carga de Web Analytics é lenta em projetos com muito histórico, por causa do limite de consultas do PostHog.
• Em incremental, um dia só é corrigido enquanto estiver na janela de 3 dias. Alterações mais antigas pedem um full refresh.
• Uma conexão PostHog por instalação.
• O texto das respostas de survey_responses vem de campos que a documentação do PostHog não descreve em detalhe, e o recurso não foi exercitado com dados reais. Confira as respostas na primeira carga.
• Não há seletor de projetos: o universo é o que a chave alcança.

Troubleshooting

Mensagem ou sintoma	Causa	O que fazer
Chave de API do PostHog inválida.	A chave está errada ou é de outra região.	Crie uma nova chave em Personal API keys e confira se a região escolhida é a da sua conta.
Não foi possível contatar a API do PostHog.	Região, endereço ou rede incorretos.	Confira a região (ou o endereço, no self-hosted) e a conectividade de rede.
O endereço do PostHog self-hosted é inválido.	A URL não começa com https://.	Informe uma URL https:// completa, sem barra final.
Nenhum projeto encontrado para esta chave.	A chave foi criada para um projeto específico.	Crie a chave com acesso à organização inteira, com os escopos organization_member:read e project:read.
A chave não pode listar os projetos da organização.	Falta o escopo project:read.	Crie uma nova chave com acesso a todos os projetos da organização.
Sem acesso às permissões da organização.	Faltam organization_member:read ou access_control:read.	Crie uma nova chave com os dois escopos de organização.
Conectado ao PostHog, mas alguns recursos não estão acessíveis.	Falta o escopo de um ou mais recursos.	Leia os avisos, que nomeiam o escopo de cada recurso, e crie uma chave com esses escopos ou siga sem eles.
A execução falha porque nenhum projeto é legível com a chave.	A chave não tem access_control:read, ou o usuário dela não alcança os projetos.	Troque a chave por uma com os escopos de organização e com acesso aos projetos.
Um recurso falha e os outros carregam.	Falta o escopo daquele recurso em algum projeto.	Adicione o escopo da tabela de escopos. A tabela anterior do recurso é mantida enquanto isso.
Os registros de um projeto restrito não aparecem no modo “Espelhar a fonte”.	O projeto é restrito e a presunção de identidade por e-mail não está habilitada.	Peça à equipe da Strattum para habilitar a instância e o domínio, ou use “Aberto”.

Próximos passos

Data Catalog

Ligue os recursos do PostHog, ajuste o modo de carga e marque dados pessoais.

Memory

Veja como as pessoas do PostHog se ligam aos contatos do CRM no grafo.