Agentes lendo a API de leitura

Receitas para um agente (ou um script que alimenta um agente) ler a API de leitura da owiew. Cada receita traz o curl e o prompt correspondente.

O que você precisa

Uma chave de API somente leitura, em OWIEW_API_KEY no ambiente, e OWIEW_API_URL com o endereço base (veja a visão geral da API).
curl e jq.
Leitura de Segurança com agentes.

Regras que todo agente precisa seguir

Micros. Todo campo terminado em _micros é um inteiro em que 1.000.000 vale uma unidade da moeda. spend_micros: 1500000 é 1,50. Divida com aritmética inteira, nunca em ponto flutuante. Conversões também vêm em micros: conversions_micros: 75000000 são 75 conversões.
Métrica derivada não vem pronta. CPA, CPC, CTR e ROAS saem dos totais somados, nunca da média das linhas.
Datas explícitas. Envie sempre since e until (AAAA-MM-DD, until inclusivo). Sem eles o servidor escolhe uma janela padrão.
Moedas. Contas de moedas diferentes não se somam sem conversão. Leia o campo currency.
Dado reescrito. As plataformas revisam números já reportados. Quando revisions for maior que zero, consulte /audit/revisions.
Escopo. O tenant_id vem da resposta da troca de chave, nunca de quem escreve o prompt.

Detalhes de autenticação, paginação e erros estão na referência da API.

Passo 1: trocar a chave por um token

O token dura dois minutos. Troque a chave a cada execução.

RESP=$(curl -s -X POST $OWIEW_API_URL/v1/token \
  -H "Authorization: Bearer $OWIEW_API_KEY")
TOKEN=$(echo "$RESP" | jq -r '.access_token')
TENANT=$(echo "$RESP" | jq -r '.tenant_id')

A partir daqui, as receitas usam $TOKEN e $TENANT.

Receita 1: relatório mensal de gasto por campanha

Requisição (setembro de 2026, como exemplo):

curl -s "$OWIEW_API_URL/v1/t/$TENANT/campaigns?since=2026-09-01&until=2026-09-30" \
  -H "Authorization: Bearer $TOKEN" > campanhas.json

Resposta (dados inventados, só o necessário):

{
  "since": "2026-09-01",
  "until": "2026-09-30",
  "campaigns": [
  {
    "campaign_id": "cmp_exemplo_01",
    "campaign_name": "Exemplo | Remarketing",
    "account_id": "act_exemplo_01",
    "spend_micros": 1500000000,
    "clicks": 4200,
    "conversions_micros": 75000000,
    "conversion_value_micros": 9000000000,
    "currency": "BRL",
    "days": 30
  }
  ]
}

Gasto por campanha em reais e centavos, só com inteiros:

jq -r '.campaigns[] | [.campaign_id, .campaign_name,
  "\(.spend_micros / 1000000 | floor),\((.spend_micros % 1000000 / 10000 | floor) | tostring | if length < 2 then "0" + . else . end)"
] | @tsv' campanhas.json

Prompt:

Você recebeu o JSON de GET /campaigns de 2026-09-01 a 2026-09-30.
Monte um relatório mensal de gasto por campanha.
- Converta spend_micros para a moeda dividindo por 1.000.000 com inteiros.
- Ordene do maior para o menor gasto e mostre a participação de cada campanha no total.
- Calcule o CPA do conjunto como soma do gasto dividida pela soma das conversões, nunca pela média dos CPAs.
- Não agrupe campanhas de moedas diferentes.
- Identifique cada campanha pelo campaign_id e mostre o nome ao lado.
- Diga ao final qual janela de datas usou.

Receita 2: alerta de campanha parada

Uma conta que parou de coletar tem o mesmo desenho de uma campanha que morreu. Por isso o agente confere as contas antes de concluir qualquer coisa.

# 1. Frescor das contas
curl -s "$OWIEW_API_URL/v1/t/$TENANT/accounts" \
  -H "Authorization: Bearer $TOKEN" | jq '.accounts[] | {account_id, provider, last_date, last_observed_at}'

# 2. Gasto por campanha em duas janelas
curl -s "$OWIEW_API_URL/v1/t/$TENANT/campaigns?since=2026-10-15&until=2026-10-21" \
  -H "Authorization: Bearer $TOKEN" > semana_anterior.json
curl -s "$OWIEW_API_URL/v1/t/$TENANT/campaigns?since=2026-10-22&until=2026-10-28" \
  -H "Authorization: Bearer $TOKEN" > semana_atual.json

Prompt:

Você recebeu o resultado de GET /accounts e de GET /campaigns para duas semanas.
Procure campanhas paradas.
1. Para cada conta, compare last_date com a data de hoje. Se a conta tem dado atrasado, marque a conta como "coleta atrasada" e NÃO conclua nada sobre as campanhas dela.
2. Para as contas em dia, liste as campanhas com gasto na semana anterior e sem gasto (ou ausentes) na semana atual, pelo campaign_id.
3. Para cada uma, mostre o gasto da semana anterior em moeda (micros divididos por 1.000.000, inteiros).
4. Não sugira pausar, ativar ou editar nada. Você só lê.

Resultado esperado

Cada receita devolve um relatório com campanhas identificadas por campaign_id, valores na moeda e a janela de datas declarada.

Se algo der errado

401. O token venceu (dois minutos) ou a chave expirou. Refaça o passo 1.
403. O token é de outro cliente ou o papel não inclui a rota. Use o tenant_id devolvido pela troca.
Números 1.000.000 vezes maiores que o esperado. O agente esqueceu de dividir _micros.
CPA que nenhuma campanha teve. O agente tirou a média dos CPAs. Reforce a regra 2.