Parâmetros de filtro dos relatórios

Os relatórios da API aceitam filtros por ambiente, trilha, usuário, período e outros recortes. Este artigo é o catálogo: o nome de cada parâmetro, o formato do valor e os nomes antigos que não funcionam mais.

Antes de começar

• As credenciais da sua instância, reunidas em Comece por aqui: credenciais para integrar com a API da Engage, e um token gerado em Passo 2 — Obtendo o access_token (POST /auth).
• Saiba quais filtros o seu relatório aceita: é o objeto filters da listagem de relatórios, descrito em Relatórios disponíveis e seus filtros. Só valem as opções marcadas como true.
• Teste em homologação: https://sandbox.engage.bz/api/v1.

Como enviar os filtros

Os filtros vão na query string da chamada de consumo:

GET https://sandbox.engage.bz/api/v1/{customer_id}/reports/legacy/{guid_report}/{admin_id}/json
    ?competitionId=1001,1002
    &roundCompletionDateStartDate=2026-08-01
    &roundCompletionDateEndDate=2026-08-31
Authorization: Bearer {access_token}

No Postman: pasta 05 - Relatórios, request Consumir relatório (JSON) - com filtros. Os filtros já estão na aba Params, desmarcados — marque só os que você vai usar.

Aba Params do request Consumir relatório (JSON) - com filtros no Postman, com os parâmetros desmarcados

Três regras valem para todos os parâmetros:

• Lista de valores é uma string com vírgulas. Escreva competitionId=1001,1002. Repetir o parâmetro (competitionId=1001&competitionId=1002) não dá o resultado esperado.
• Datas no formato AAAA-MM-DD. A hora é descartada: toda data inicial vira 00:00:00 e toda data final vira 23:59:59 do dia informado.
• Marcadores aceitam 0 ou 1.

Seleção

Datas

O par genérico é startDate e endDate. Além dele, cada relatório tem o par da data que faz sentido para ele, sempre no formato <prefixo>StartDate e <prefixo>EndDate:

Exemplo: roundCompletionDateStartDate=2026-08-01&roundCompletionDateEndDate=2026-08-31.

Marcadores

Nomes que não existem

Estes nomes aparecem em material antigo e são descartados sem aviso:

Cuidados

• Lista muito longa de IDs estoura o tamanho da URL. Em produção, o limite fica perto de 8 KB, cerca de mil IDs; em homologação pode ser menor. Para muitos usuários, filtre por group ou competitionId, ou divida a extração em lotes.
• Nada vai no corpo da requisição. A chamada é GET. O bloco { "params": { ... } }, citado em material antigo, é formato interno da plataforma, não da API.
• Não envie environmentId. Ele não filtra nada: só marca a origem da chamada no log de auditoria.

Problemas comuns