GET /v1/optimization/verification

Este endpoint responde uma unica pergunta sobre o trafego do proprio cliente, com os numeros do proprio cliente: a Floopy esta mesmo verificando a historia de economia para esta rota, nos ultimos 7 dias? E a API por tras do card “Verification Status” da pagina Baseline-vs-Floopy no dashboard.

A resposta e um de quatro estados — verified, not_verified, insufficient_data, regression_detected — derivado de uma agregacao por tenant sobre o log de requisicoes, com os numeros subjacentes de baseline e floopy retornados ao lado para que voce possa auditar o veredito.

Endpoint

GET https://api.floopy.ai/v1/optimization/verification?route_id=<uuid>&window=7d

Autenticacao

Authorization: Bearer <sua-chave-floopy>

Permissao: read_permission.
Disponivel em todos os planos.
Nosso time esta liberando esse endpoint gradualmente e validando a qualidade dos dados antes da disponibilidade ampla — fale com o suporte para acesso antecipado.

Parametros de query

Campo	Tipo	Obrigatorio	Restricoes
`route_id`	string (UUID v4)	Sim	O id da rota cuja performance voce quer verificar. Validado como UUID v4 no deserializador; entrada invalida retorna `400 invalid_route_id`.
`window`	string	Sim	Enum fechado: `7d`. v2 lanca com uma unica janela fixa; outras janelas estao explicitamente fora de escopo.

Uma chamada bem-sucedida primeiro busca a configuracao da rota com escopo na organizacao do chamador. Se a rota nao pertence a org do chamador, a resposta e 404 com bytes identicos a uma rota inexistente; a camada de analytics nao e consultada.

Resposta (200)

{
  "route_id": "5b3f9c1e-7a2b-4c3d-9e1f-0a1b2c3d4e5f",
  "window": "7d",
  "status": "verified",
  "baseline": {
    "samples": 4218,
    "avg_cost_micro_usd": 412,
    "composite_quality": 0.812,
    "p50_latency_ms": 612
  },
  "floopy": {
    "samples": 17392,
    "avg_cost_micro_usd": 226,
    "composite_quality": 0.804,
    "p50_latency_ms": 588
  },
  "delta": {
    "cost_pct": -45.1,
    "quality_abs": -0.008,
    "p50_latency_ms": -24
  }
}

Referencia de campos

Campo	Tipo	Descricao
`route_id`	UUID	Ecoa o parametro `route_id`.
`window`	string	Ecoa o parametro `window` (sempre `7d` no v2).
`status`	string	Enum fechado: `verified`, `not_verified`, `insufficient_data`, `regression_detected`. Veja Metodologia de status de verificacao.
`baseline.samples`	integer	Numero de requisicoes em fallback (nao roteadas pela Floopy) na rota dentro da janela. Contado em linhas do log de requisicoes onde `fallback_used = 1` e `routing_rule_id = route_id`.
`baseline.avg_cost_micro_usd`	number	Media de `cost_micro_usd` sobre `baseline.samples`.
`baseline.composite_quality`	number	Media do score composto de qualidade em `[0.0, 1.0]` sobre as mesmas linhas.
`baseline.p50_latency_ms`	number	Mediana de latencia ponta-a-ponta em milissegundos.
`floopy.samples`	integer	Numero de requisicoes roteadas pela Floopy na rota dentro da janela. Contado onde `fallback_used = 0` e a estrategia de roteamento esta entre as estrategias da Floopy (allowlist fechada: `feedback_driven`, `smart_cost`, `weighted`, `round_robin`, `latency_based`).
`floopy.avg_cost_micro_usd`	number	Media de custo sobre `floopy.samples`.
`floopy.composite_quality`	number	Media de qualidade composta em `[0.0, 1.0]`.
`floopy.p50_latency_ms`	number	Mediana de latencia.
`delta.cost_pct`	number	Variacao percentual de custo: `(floopy − baseline) / baseline * 100`. Negativo significa que a Floopy esta mais barata.
`delta.quality_abs`	number	Variacao absoluta de qualidade composta: `floopy − baseline`. Negativo significa que a Floopy esta abaixo da baseline.
`delta.p50_latency_ms`	number	Variacao absoluta de latencia p50 em milissegundos.

Quando status == "insufficient_data", os blocos baseline e floopy continuam populados com o que foi observado, mas delta e omitido porque a comparacao nao e significativa abaixo do piso de amostras.

Quando status == "regression_detected", a resposta e populada normalmente; o veredito e definido pelo sinal de regressao bucketizado vindo de /v1/decisions na mesma janela, nao pelos numeros de custo/qualidade.

Semantica de status

Status	Quando
`verified`	Ambos os paineis atendem `samples >= SAMPLE_FLOOR` (`100`), nao ha regressoes recentes na rota e `(baseline.composite_quality − floopy.composite_quality) <= QUALITY_TOLERANCE` (`0.03`).
`not_verified`	Ambos os paineis atendem o piso, nao ha regressoes, mas a qualidade da Floopy esta abaixo da baseline em mais que `QUALITY_TOLERANCE`.
`insufficient_data`	Algum painel tem menos que `SAMPLE_FLOOR = 100` linhas na janela. A resposta honesta quando nao ha trafego suficiente para emitir um veredito.
`regression_detected`	O sinal bucketizado `recent_regressions` sobre a rota nao e zero na janela de 7 dias. O endpoint se recusa a chamar a rota de “verified” enquanto uma regressao esta em curso, independentemente dos numeros de custo/qualidade.

As constantes estao fixadas no codigo (SAMPLE_FLOOR = 100, QUALITY_TOLERANCE = 0.03) e documentadas em Metodologia Baseline-vs-Floopy.

Cabecalho de aviso de agregacao

Se alguma decisao na janela de 7 dias tem used_shared_pool_prior == true, a resposta inclui o cabecalho:

Floopy-Aggregation-Notice: shared-pool-influenced

Isso indica que priors entre tenants influenciaram pelo menos uma decisao que alimenta o veredito de verificacao. Os numeros sao mantidos; a procedencia fica visivel. Veja Metodologia de Confianca para o mecanismo subjacente.

Cache de resposta e `Cache-Control`

O endpoint armazena a resposta em Redis por (organization_id, route_id, window) durante 60 segundos. O cabecalho Cache-Control: max-age=60 e ecoado para que intermediarios HTTP respeitem o mesmo TTL. Numeros de verificacao mudam devagar; o cache foi dimensionado para essa cadencia.

Um cache hit retorna o mesmo payload byte a byte, incluindo o cabecalho Floopy-Aggregation-Notice quando aplicavel.

Erros

Status	Codigo `error`	Quando
`400`	`invalid_route_id`	`route_id` ausente ou nao e UUID v4 valido.
`400`	`invalid_window`	`window` ausente ou fora de `{7d}`.
`403`	`read_permission`	A chave nao tem `read_permission`.
`403`	`plan_required`	O endpoint nao esta incluido no plano do chamador.
`404`	`not_found`	Nao existe rota na org do chamador para esse `route_id`. Os bytes sao identicos a um lookup cross-tenant para nao vazar existencia.
`429`	`rate_limited`	Excedeu `60 req/min/org` ou `20 req/min/chave`. Carrega `Retry-After`.
`503`	`upstream_timeout`	A agregacao de analytics excedeu o timeout de 5 s. Carrega `Retry-After: 60`.
`5xx`	`internal`	Falha upstream.

Exemplo curl

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/optimization/verification?route_id=5b3f9c1e-7a2b-4c3d-9e1f-0a1b2c3d4e5f&window=7d" \
  -i

A flag -i imprime os cabecalhos da resposta para voce ver Cache-Control: max-age=60 e qualquer Floopy-Aggregation-Notice.

Rate limits

60 requisicoes / minuto / organizacao.
20 requisicoes / minuto / chave de API.

Ambas as janelas sao avaliadas atomicamente. O cap por chave e mais baixo porque numeros de verificacao mudam devagar — nao ha sinal a ser obtido com polling em alta cadencia.

Trilha de auditoria

Toda resposta bem-sucedida grava um evento optimization.verification_read no log de auditoria com:

actor_api_key_id — id da chave de API que chamou o endpoint.
resource_id — o route_id.
status — o status de verificacao (enum fechado: verified, not_verified, insufficient_data, regression_detected).

O evento e throttled por (organization_id, key_id, route_id) durante 60 segundos para que um cliente em polling nao inunde o log de auditoria.

Veja tambem

Metodologia Baseline-vs-Floopy — como a comparacao e construida, incluindo a semantica de status de verificacao.
Metodologia de Confianca — sinal bucketizado de regressao que aciona regression_detected.
GET /v1/decisions/{request_id} — auditoria de uma unica decisao, incluindo evidence.