GET /v1/session/{session_id}

Reconstruct a complete conversation for a session_id straight from Floopy’s stored request/response logs. Because the gateway already persists every turn, you can restore a chat for an end user without keeping any message history in your own database — point your client at this endpoint, get back an OpenAI-style messages array, and continue the conversation.

The session_id is whatever value your client sent on the floopy-session-id header at request time. This endpoint is read-only and never produces a log row of its own.

Endpoint

GET https://api.floopy.ai/v1/session/{session_id}

Authentication

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

Permission: read_permission on the API key.
Available on all plans. Subject to your plan’s rate limit (enforced by the gateway).
The conversation is org-scoped: the lookup is pinned to the organization that owns the API key, so a session_id from another organization is indistinguishable from one that does not exist (both return 404).

Path parameters

Field	Type	Required	Constraints
`session_id`	string	Yes	Trimmed before use. Empty/whitespace-only returns `400`. Bound as a ClickHouse query parameter — never interpolated into SQL — so arbitrary values are safe.

Response (200)

{
  "session_id": "sess_demo_1",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "What's the capital of France?" },
    { "role": "assistant", "content": "The capital of France is Paris." },
    { "role": "user", "content": "And its population?" },
    { "role": "assistant", "content": "About 2.1 million in the city proper." }
  ],
  "turn_count": 2,
  "turns": [
    {
      "request_id": "0c4a1d3f-7bea-4a1f-8b6e-2c0a8e4d3f10",
      "created_at": "2026-05-17T10:00:00Z",
      "model": "gpt-4o",
      "provider": "openai"
    },
    {
      "request_id": "1d5b2e4f-8cfb-4b2f-9c7f-3d1b9f5e4a21",
      "created_at": "2026-05-17T10:01:12Z",
      "model": "gpt-4o",
      "provider": "openai"
    }
  ]
}

Field reference

Field	Type	Description
`session_id`	string	Echo of the requested session id.
`messages`	array	Stitched conversation, oldest → newest. Each element is a raw OpenAI-style message object (role, content, `tool_calls`, etc. preserved verbatim). Drop-in for the `messages` field of a follow-up `chat/completions` call.
`turn_count`	integer	Number of stored turns that contributed to `messages`.
`turns`	array	Per-turn provenance, in the same order as the contributing turns.
`turns[].request_id`	string	The originating request’s id.
`turns[].created_at`	ISO8601	Server-side request timestamp (UTC).
`turns[].model`	string	Model that served that turn.
`turns[].provider`	string	Provider that served that turn.

How reconstruction works

Floopy walks the session’s turns in chronological order and stitches them into a single message array:

The first turn seeds messages with its full request history (so a system prompt and any prior context the client sent are preserved).
Each subsequent turn contributes the assistant reply plus any new trailing messages in that turn’s request. This works whether your client replays the full history on every call (stateful) or sends only the new message (stateless).

Limitations:

A session is capped at its most recent 500 turns, returned oldest → newest.
Turns that are not successful chat completions are skipped and do not count toward turn_count: non-2xx responses, streaming responses (SSE bodies), and non-chat endpoints such as embeddings.

Errors

Status	`error` code	When
`400`	`invalid_request`	`session_id` is empty or whitespace-only after trimming.
`401`	`unauthorized`	Missing or invalid API key.
`403`	`read_permission`	Key lacks `read_permission`.
`404`	`not_found`	No turns exist for that `session_id` in the caller’s organization. Identical bytes for cross-tenant lookups so existence is not leaked.
`429`	`rate_limited`	Plan rate limit exceeded. Carries `Retry-After`.
`502`	`bad_gateway`	Upstream analytics store unavailable.

Curl example

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/session/sess_demo_1"