Janelas de data e paginação

O recorte de uma consulta é a janela de datas. A maior parte das rotas devolve a resposta inteira da janela, sem páginas.

Parâmetros de janela

Quase toda rota de totais aceita:

Parâmetro	Formato	Significado
`since`	`AAAA-MM-DD`	Primeiro dia.
`until`	`AAAA-MM-DD`	Último dia, inclusivo.

Algumas rotas usam outros nomes para o mesmo conceito: de e ate (busca-organica, google-analytics, sugestoes-de-desempenho) e inicio e fim (google-business, merchant-center). A Referência lista o nome certo de cada rota.

Regras

Omitir tem efeito. Sem until, vale o dia de hoje em UTC. Sem since, vale 30 dias antes de until. Não presuma: peça a janela explicitamente sempre que o número for comparado com outro.
Formato exato. AAAA-MM-DD. Datas inexistentes (2026-02-31) são recusadas.
Faixa aceita. De 2000-01-01 até um ano à frente de hoje.
Janela invertida (since depois de until) é recusada.
Máximo de 400 dias por consulta. Para períodos maiores, consulte em partes. A rota sugestoes-de-desempenho aceita no máximo 180 dias.
Quando a janela é inválida, a resposta é 400 com error.code igual a INVALID_WINDOW e uma mensagem com o motivo.

Cada resposta de totais devolve since e until como o servidor os interpretou. Leia esses campos, principalmente quando você omitiu algum parâmetro.

Consultar um mês

Para setembro de 2026:

?since=2026-09-01&until=2026-09-30

Para o mês corrente, use o primeiro dia do mês e o dia de hoje. O dia corrente é parcial e pode mudar nas coletas seguintes.

Consultar mais de 400 dias

Divida em janelas que não se sobreponham e some os totais aditivos (spend_micros, impressions, clicks, conversions_micros, conversion_value_micros) depois. Recalcule as métricas derivadas a partir da soma. Veja Unidades e tipos.

Para fechar um período já revisado, evite consultar só os dias mais recentes. Eles são os que mais mudam.

Paginação

Não há paginação por cursor nem por página nas rotas de leitura publicadas. Cada resposta traz o recorte completo da janela. Para controlar o tamanho de uma resposta, reduza a janela.

Exceção: audit/revisions aceita limit, um inteiro de 1 a 1000 (padrão 100), que devolve as alterações mais recentes. Valor fora da faixa responde 400 com INVALID_LIMIT. Não há como pedir além das 1000 mais recentes; a rota não filtra por data. Guarde o que já leu e releia periodicamente.

Ordem

Não presuma a ordem dos elementos de um array, a menos que a documentação da rota diga. Onde há ordem, há um campo que a define (por exemplo, ordem e posicao em plano/acoes). Ordene do seu lado pelo campo que importa.