Relatórios

O motor de relatórios expõe um conjunto de relatórios nomeados definidos no servidor. Estes dois endpoints listam os relatórios disponíveis e executam um relatório nomeado com seus parâmetros. Para autenticação, veja Autenticação; para o formato geral de erros e status, veja Convenções e erros.

Endpoints

Listar relatórios

GET /reports

Retorna todos os relatórios definidos, ordenados por nome; cada relatório aparece uma vez, com o nome e os metadados semânticos (meta): os parâmetros que exige e a forma da saída. Descobrir os parâmetros e a forma da saída aqui evita uma cadeia de erros 400 de parâmetro faltando ao executar o relatório.

A lista não é filtrada pela conta do token: duas contas veem a mesma lista. A conta só autoriza o chamador.

Escopo de auth: exige acesso de leitura escopado à conta, apenas pelo cabeçalho Authorization: Bearer. O ?token= na URL não vale para este endpoint (só para executar um relatório); chamar GET /reports?token=... responde 401.

Resposta: uma lista de objetos. Cada objeto tem:

Metadados semânticos (meta)

O meta de cada relatório é a camada semântica: permite descobrir a forma da saída sem adivinhar colunas. Tem os campos:

Cada entrada de columns descreve uma coluna de saída:

• description: frase do que a coluna representa.
• type: um escalar (DATE, VARCHAR, INTEGER, BIGINT, DOUBLE, BOOLEAN) o paramétrico JSON[T], um mapa JSON cujos valores são todos do escalar T, endereçado por chave com coluna[chave], que extrai um T; ou BIGINT[], uma lista exata de ids, válida só com agg count_distinct (por exemplo a coluna users de dash.tgsr.distinct-users).
• semantics: o papel da coluna, um objeto plano cuja chave discriminadora é role, em minúsculas:

sum, min e max reduzem os valores das linhas. count_distinct conta os ids distintos da união das listas BIGINT[] das linhas cobertas (nunca a soma de contagens parciais) e só vale com type BIGINT[].

derived_metrics são razões calculadas após a agregação (por exemplo cpc para cost / clicks), nunca colunas armazenadas nem colunas do CSV.

Executar um relatório

GET /reports/{report_name}

Executa o relatório nomeado com os parâmetros fornecidos e devolve o resultado. {report_name} é o nome do relatório, por exemplo dash.ga4.performance.

Parâmetros: passados na query string, um por nome de parâmetro que o relatório exige. Os nomes vêm de GET /reports e são declarados por relatório. O parâmetro de entidade muda por plataforma: property_id no GA4, customer_id no Google Ads, meta_id na Meta, server_name na família dash.tgsr.*. Quando o relatório aceita uma janela de datas, ela é sempre start_date / end_date (YYYY-MM-DD, inclusivas).

Como o token é enviado: no cabeçalho Authorization: Bearer ou no parâmetro de query ?token=<token> na URL. O ?token= serve para ferramentas que leem um CSV por URL e não conseguem mandar cabeçalho (por exemplo o IMPORTDATA do Google Sheets, que só faz GET sem cabeçalho): com ele a própria URL autentica. O token da query é removido do mapa de parâmetros antes das checagens, então nunca conta como parâmetro do relatório nem dispara 400 unexpected parameters.

Escopo de auth: todo relatório exige autenticação. O servidor injeta o id da conta autenticada (você não passa account_id na query), e cada relatório só lê as linhas dessa conta. Sem auth, a resposta é Error 401: unauthorized.

Resposta: CSV (Content-Type: text/csv), transmitido em fluxo. Sempre traz uma linha de cabeçalho; numa resposta de 0 linhas o cabeçalho vem dos nomes de coluna declarados em meta (mesma ordem), em vez de corpo vazio.

Erros

Os erros gerais de status e formato ficam em Convenções e erros. Específicos deste endpoint:

Esquema de nomes

Cada nome de relatório segue dash.{plataforma}.{nome}: plataforma identifica a origem (por exemplo facebook, googleads, ga4, rdstation e tgsr, o rastreamento do próprio TagServer) e nome identifica o relatório dentro dela (por exemplo ad-performance, campaign-performance, performance). É o mesmo conjunto a que os tiles de dashboard se vinculam.

A família dash.tgsr.* traz dados do site sem conta de anúncios conectada (por exemplo dash.tgsr.performance, dash.tgsr.traffic, dash.tgsr.pages), com o parâmetro de entidade server_name: o hostname do servidor, que precisa pertencer à conta.

A lista completa e autoritativa é o próprio GET /reports; Relatórios e métricas cataloga os relatórios por plataforma.

Veja também

• Métricas de eventos para o endpoint de saúde de entrega de eventos.
• Relatórios e métricas para o catálogo de relatórios e métricas por plataforma, que usa estes nomes dash.*.