GET /v1/decisions

List routing audits across a session, time window, strategy, model, or a specific batch of request ids. Designed for pulling every decision in a conversation into a notebook, or for ad-hoc auditability queries from a SIEM.

The list endpoint never produces a decision_trace row of its own.

Endpoint

GET https://api.floopy.ai/v1/decisions

Authentication

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

Permission: read_permission.
Plan flag: has_audit_api. Available on Free and Pro plans.
Behind the per-org canary kill switch.

Query parameters

At least one of session_id, (from, to), or request_ids is required.

Field	Type	Required	Constraints	Default
`session_id`	string	Conditional	The session id sent in the `floopy-session-id` header.	—
`from`	ISO8601	Conditional	Inclusive start of the time range.	—
`to`	ISO8601	Conditional	Inclusive end of the time range. `to - from` ≤ 31 days.	—
`request_ids`	array of UUID	Conditional	Up to 50 ids. Always evaluated alongside the caller’s organisation predicate.	—
`routing_strategy`	string	No	One of `feedback_driven`, `smart_cost`, `fallback`, `round_robin`, `weighted`, `latency_based`, `legacy_model`.	—
`model`	string	No	Filter to a specific model id (e.g. `gpt-4o`).	—
`min_confidence`	number	No	Lower bound, `[0.0, 1.0]`. Filters in `confidence >= min_confidence`.	—
`max_confidence`	number	No	Upper bound, `[0.0, 1.0]`.	—
`limit`	integer	No	`1..=200`.	`50`
`cursor`	string	No	Opaque, HMAC-signed continuation token returned by a previous response.	—

The response body has deny_unknown_fields semantics — unknown query keys return 400 invalid_request.

Response (200)

{
  "items": [
    {
      "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 }],
      "filtered": [],
      "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
      }
    }
  ],
  "next_cursor": "eyJ0cyI6IjIwMjYtMDUtMDVUMTc6NDI6MTFaIiwiaWQiOiIwYzRhMWQzZi03YmVhLTRhMWYtOGI2ZS0yYzBhOGU0ZDNmMTAifQ.RUVhSV9..."
}

Fields

Field	Type	Description
`items`	array	Page of decisions, same shape as `GET /v1/decisions/{request_id}`.
`next_cursor`	string \| null	Opaque token to pass back as `cursor` for the next page. `null` when there are no further results.

The cursor is HMAC-signed using the gateway’s secret pepper. Tampered cursors are rejected with 400 invalid_cursor. Pepper rotation invalidates all outstanding cursors — clients should restart pagination with no cursor on a 400 invalid_cursor.

Errors

Status	`error` code	When
`400`	`missing_filter`	None of `session_id`, `(from, to)`, or `request_ids` provided.
`400`	`range_too_wide`	`to - from > 31 days`.
`400`	`request_ids_too_many`	`request_ids` has more than 50 entries.
`400`	`invalid_cursor`	Cursor failed HMAC verification, or pepper rotated.
`400`	`invalid_request`	Unknown query key, malformed UUID in `request_ids`, or invalid type.
`403`	`read_permission` / `plan_required`	Permission or plan flag missing.
`429`	`rate_limited`	Over per-org or per-key budget.
`5xx`	`internal`	Upstream failure.

Curl example

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/decisions?session_id=sess_demo_1&limit=100"

Paginating through a time window:

CURSOR=""
while :; do
  RESP=$(curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
    "https://api.floopy.ai/v1/decisions?from=2026-05-01T00:00:00Z&to=2026-05-05T00:00:00Z&limit=200${CURSOR:+&cursor=$CURSOR}")
  echo "$RESP" | jq -c '.items[]'
  CURSOR=$(echo "$RESP" | jq -r '.next_cursor // empty')
  [ -z "$CURSOR" ] && break
done

Rate limits

60 requests / minute / organization.
30 requests / minute / API key.

Lower than the single-decision endpoint because each call is heavier.