> ## Documentation Index > Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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)](https://strattumai.mintlify.site/data-pipelines/personal-data.md). > [!TIP] > > 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](https://posthog.com/docs/api/queries) ## 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](https://strattumai.mintlify.site/data-catalog/overview.md)** > > Ligue os recursos do PostHog, ajuste o modo de carga e marque dados pessoais. > **[Memory](https://strattumai.mintlify.site/memory/overview.md)** > > Veja como as pessoas do PostHog se ligam aos contatos do CRM no grafo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.