> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Coortes de retenção

> Coortes semanais e a fração de cada uma que voltou — com as definições que decidem o que é uma coorte, o que significa retido, e o que uma matriz vazia está dizendo.

Retenção é uma razão entre duas definições. Agrupe as pessoas por *quando* e
conte quantas voltaram *em qual outro quando* — mude qualquer uma das metades e
o mesmo produto retém 40% ou 80%. Esta página são as metades.

O painel desenha isso em **Analytics → Retenção**, atrás de `analytics:read`.

## O que é uma coorte

**Uma semana UTC, começando na segunda-feira.** Um contato pertence à semana do
seu primeiro evento `$auth.identified` — o fato que o UserKit publica no momento
em que alguém deixa de ser anônimo. Quando não existe esse evento, vale a semana
em que o contato foi criado: um contato nascido por `POST /v1/contacts` ou por
[importação de CSV](/pt-br/guides/import-contacts) não dispara fato de auth
nenhum, e descartá-los excluiria silenciosamente todo tenant que migrou a base
de usuários para cá.

**Visitantes anônimos não têm coorte alguma.** Um visitante ganha uma linha de
contato e uma sessão, então os eventos dele carregam um `contact_id` — que é
exatamente por que "tem contato" não pode ser o que uma coorte conta. Só
identificados, a mesma exclusão que mantém visitantes fora do
[medidor de contatos ativos](/pt-br/concepts/contacts).

## O que significa retido

O contato produziu **pelo menos um evento autenticado** naquela semana: um
sign-in, ou qualquer coisa que ele tenha feito logado. Não um page view de um
navegador deslogado, e não a abertura de um e-mail.

A semana 0 é a própria semana da coorte, então a retenção dela é 1 por
construção — uma coorte é 100% dela mesma. Os offsets vão densos até a semana
atual, então uma semana em que ninguém voltou é um zero no gráfico e não um
buraco nele.

## Como ler

```bash theme={null}
curl "https://api.userkit.dev/v1/organization/analytics/retention?environment=live" \
  -H "Authorization: Bearer uk_st_…" \
  -H "X-Organization-Id: …"
```

```json theme={null}
{
  "cohorts": [
    {
      "cohort_week": "2026-07-20",
      "contacts": 2,
      "weeks": [
        { "week_offset": 0, "retained": 2, "retention": 1 },
        { "week_offset": 1, "retained": 1, "retention": 0.5 },
        { "week_offset": 2, "retained": 0, "retention": 0 }
      ]
    }
  ],
  "status": "ready",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-08-03T00:00:00Z"
}
```

`contacts` é o tamanho da coorte e o denominador de toda `retention` abaixo
dela. `retention` é uma fração entre 0 e 1, não uma porcentagem — a porcentagem
está a uma multiplicação de distância e uma razão não perde precisão no caminho
até o gráfico.

Uma coorte de três semanas tem três entradas em `weeks`. A quarta não é um
zero; ela ainda não aconteceu, e desenhá-la seria reportar um churn que nenhuma
semana teve a chance de contradizer.

## Oito semanas, recalculadas

Um job noturno recalcula **as últimas oito semanas de coorte** inteiras, a
partir dos seus eventos crus, e faz upsert do resultado. Rodar duas vezes
produz os mesmos números.

Linhas mais antigas que essa janela **congelam** onde a última execução as
deixou. O congelamento é o objetivo: seu histórico de eventos crus pode
envelhecer e sumir sem que o gráfico se mova por baixo. Isso também significa
que uma correção só alcança uma coorte enquanto ela ainda está dentro da janela.

O período padrão cobre essas oito semanas. `from` e `to` estreitam o recorte, e
são comparados contra a **segunda-feira** da coorte — uma coorte é desenhada
inteira ou não é desenhada, porque meia curva lida como se fosse a curva toda
não é uma retenção mais grosseira, é uma retenção errada. A janela de retenção
de analytics do seu plano vale aqui do mesmo jeito que vale para a
[contagem de eventos](/pt-br/guides/analytics#o-explorer).

## O que uma resposta vazia significa

`status` é o campo que impede um `cohorts` vazio de mentir, e ele existe porque
os dois jeitos de chegar num vazio pedem ações opostas:

| `status`  | O que significa                                                                  | O que fazer                                            |
| --------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `ready`   | A matriz é o que a última execução escreveu                                      | Ler                                                    |
| `pending` | Este ambiente tem contatos que poderiam ser agrupados, e nenhuma linha para eles | Esperar o job noturno, ou conferir se ele está rodando |
| `empty`   | Nenhuma coorte que a janela contém tem gente                                     | Nada está quebrado. Ainda não há o que desenhar        |

É `ready` sempre que `cohorts` não está vazio. A distinção entre os outros dois
é perguntada aos seus contatos em vez de adivinhada a partir do vazio: reportar
"sem dados" para quem está com o job parado é exatamente a tranquilização que
faz a pessoa parar de procurar.

## De quem é a meia-noite

As semanas são UTC no armazenamento e no fuso da sua organização na exibição, a
mesma regra que a [contagem de eventos](/pt-br/guides/analytics#de-quem-e-a-meia-noite)
e as [métricas de receita](/pt-br/guides/revenue-metrics#de-quem-e-a-meia-noite)
seguem. Decidir isso uma vez é o que permite sobrepor uma curva de retenção e um
gráfico de eventos.