GET /v1/decisions/{request_id}

Recupere a auditoria completa de roteamento para uma única requisição de chat-completion, indexada pelo header x-request-id que o gateway ecoa em toda resposta. Útil para correlacionar uma entrada nos logs da sua aplicação com o provider, modelo, candidatos e confiança exatos que a Floopy escolheu para ela.

Este endpoint nunca produz uma linha decision_trace própria — ele apenas lê.

Endpoint

GET https://api.floopy.ai/v1/decisions/{request_id}

Autenticação

Authorization: Bearer <your-floopy-api-key>

Permissão: read_permission na API key (o método HTTP mapeia para GET → read_permission).
Disponível em todos os planos.
Estamos liberando esse endpoint gradualmente; uma organização que ainda não foi habilitada recebe 404 not_found, com bytes idênticos aos de uma requisição inexistente. Fale com o suporte para acesso antecipado.

Path parameters

Field	Type	Required	Constraints
`request_id`	string (UUID v4)	Yes	Validado com parse estrito de UUID. Entrada malformada retorna `400 invalid_request_id`.

Resposta (200)

{
  "request_id": "0c4a1d3f-7bea-4a1f-8b6e-2c0a8e4d3f10",
  "request_created_at": "2026-05-05T17:42:11Z",
  "session_id": "sess_demo_1",
  "routing_strategy": "feedback_driven",
  "phase": "auto",
  "weights": { "session": 0.5, "auto": 0.3, "manual": 0.1, "benchmark": 0.1 },
  "candidates": [
    { "provider": "openai",    "model": "gpt-5.4-mini",    "score": 0.81 },
    { "provider": "anthropic", "model": "claude-sonnet-4", "score": 0.78 }
  ],
  "filtered": [
    { "provider": "openai", "model": "gpt-5.4", "reason": "constraint_max_cost_increase", "score": 0.86 }
  ],
  "winner": { "provider": "openai", "model": "gpt-5.4-mini" },
  "reason": "dispatched",
  "confidence": 0.78,
  "confidence_reason": "ok",
  "exploration_rate_effective": 0.05,
  "used_shared_pool_prior": false,
  "outcome": {
    "status": 200,
    "latency_ms": 412,
    "cost_micro_usd": 230,
    "cache_hit": false,
    "threat_blocked": false,
    "fallback_used": false
  },
  "evidence": {
    "samples": 412,
    "top2_score_gap": 0.07,
    "outcome_variance": 0.04,
    "recent_regressions": { "kind": "exact", "exact": 1 },
    "last_regression_at": "2026-05-04T18:25:00Z"
  },
  "explanation": {
    "text": "A Floopy roteou esta requisicao para openai/gpt-5.4-mini com base em 412 amostras historicas e uma confianca moderada de 0,78. O proximo candidato pontuou dentro de 0,07 pontos e a variancia dos resultados tem se mantido estavel. Uma regressao foi registrada nos ultimos 7 dias.",
    "template_id": "feedback_driven_moderate_confidence"
  }
}

A resposta tambem carrega um cabecalho Content-Language ecoando a locale usada para renderizar explanation.text — veja a feature de Explicacao de Decisao.

Referência de campos

Field	Type	Description
`request_id`	UUID	O id do header de resposta `x-request-id`.
`request_created_at`	ISO8601	Timestamp da requisição no servidor (UTC).
`session_id`	string \| null	Valor do header `floopy-session-id`, se presente.
`routing_strategy`	string	Nome da estratégia executada (`feedback_driven`, `smart_cost`, `fallback`, `round_robin`, `weighted`, `latency_based`, `legacy_model`).
`phase`	string \| null	Fase do Feedback-Driven (`day0`, `auto`, `nps`); `null` para execuções que não são Feedback-Driven.
`weights`	object \| null	Pesos dos sinais no momento da decisão (apenas Feedback-Driven).
`candidates`	array	Modelos considerados, com o score de roteamento atribuído pela estratégia a cada um.
`filtered`	array	Candidatos removidos durante a filtragem. `reason` é um enum fechado (veja abaixo).
`winner`	object \| null	O par `(provider, model)` despachado. `null` quando nenhum candidato pôde ser selecionado.
`reason`	string	`dispatched`, `exhausted`, ou `no_enabled_targets`.
`confidence`	number \| null	Confiança auto-reportada do roteador no vencedor, em `[0.0, 1.0]`. `null` significa que nenhum roteador foi invocado (ex.: cache hit). Veja a metodologia de Confidence.
`confidence_reason`	string \| null	Por que esse valor de confiança — `ok`, `cap_day0`, `cap_shared`, `no_router_invoked`, `insufficient_samples`, `single_candidate`.
`exploration_rate_effective`	number	Taxa efetiva de exploração para esta requisição.
`used_shared_pool_prior`	boolean	Se a decisão de roteamento utilizou priors cross-tenant.
`outcome.status`	integer	Status HTTP da chat completion subjacente.
`outcome.latency_ms`	integer \| null	Latência ponta a ponta em milissegundos.
`outcome.cost_micro_usd`	integer	Custo do provider para a requisição em micro-USD.
`outcome.cache_hit`	boolean	Se a resposta foi servida a partir do cache.
`outcome.threat_blocked`	boolean \| null	Se o LLM firewall bloqueou a requisição.
`outcome.fallback_used`	boolean	Se um target de fallback foi utilizado.
`evidence`	object \| null	Entradas que produziram o numero de confianca, expostas para auditoria (apenas Feedback-Driven e Smart-Cost). `null` quando nenhum router foi invocado. Veja Metodologia de Confianca.
`evidence.samples`	integer	Contagem rolante de amostras `n_samples` sobre o vencedor.
`evidence.top2_score_gap`	number	Gap de score entre o vencedor e o segundo colocado.
`evidence.outcome_variance`	number	Variancia rolante de resultados sobre o vencedor.
`evidence.recent_regressions`	tagged union	Contagem bucketizada de regressoes sobre o `(provider, model)` do vencedor nos ultimos 7 dias. Tagged union com `kind: "exact"` e campo `exact` para `n < 10`, ou `kind: "at_least"` e campo `at_least` para os limiares `10` e `50`.
`evidence.last_regression_at`	ISO8601 \| null	Timestamp da regressao mais recente na janela de 7 dias, arredondado para o multiplo de 5 minutos mais proximo. `null` quando nao ha regressao.
`explanation`	object \| null	Explicacao legivel da decisao de roteamento, renderizada em tempo de leitura segundo o `Accept-Language` da requisicao (caindo para `en`). `null` quando nenhum router foi invocado. Veja Explicacao de Decisao.
`explanation.text`	string	Paragrafo em prosa simples (≤ 600 caracteres) descrevendo a decisao. Nunca referencia o conteudo do prompt.
`explanation.template_id`	string	Id de template (enum fechado) que foi renderizado. Veja a taxonomia de template-id.

Valores de filtered[].reason: circuit_breaker_open, rate_limited, constraint_max_cost_increase, constraint_max_regression, constraint_confidence_below_threshold, constraint_min_samples, constraint_high_variance, constraint_cost_drop_requires_validation, constraint_shadow_required, no_enabled_targets, firewall_blocked, other.

Cabecalhos de resposta

Alem dos cabecalhos padrao, a resposta carrega:

Content-Language: en ou Content-Language: pt — a locale usada para renderizar explanation.text. Resolvida do cabecalho Accept-Language da requisicao, caindo para en em entrada ausente, malformada ou nao suportada. Veja Explicacao de Decisao.

Erros

Status	`error` code	Quando
`400`	`invalid_request_id`	`request_id` não é um UUID v4 válido.
`403`	`read_permission`	A key não possui `read_permission`.
`403`	`plan_required`	O endpoint não está incluído no plano do chamador.
`404`	`not_found`	Não existe linha na organização do chamador para esse `request_id`. Retornado com bytes idênticos para consultas cross-tenant para que a existência não seja revelada.
`410`	`retention_expired`	A linha existe mas é mais antiga que o `log_retention_days` do plano. O body carrega `retention_window_days`.
`429`	`rate_limited`	Excedeu `600 req/min/org` ou `200 req/min/key`. Carrega `Retry-After`.
`5xx`	`internal`	Falha upstream da camada de analytics.

Exemplo curl

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/decisions/0c4a1d3f-7bea-4a1f-8b6e-2c0a8e4d3f10"

Rate limits

600 requests / minuto / organização.
200 requests / minuto / API key.

Ambas as janelas são avaliadas atomicamente; se qualquer uma negar, a requisição é rejeitada com 429.

Veja também

GET /v1/decisions — listagem paginada com cursors HMAC.
GET /v1/export/decisions — export em massa em JSONL.
Metodologia de Confidence.