>_ DOCS / HOW-TO GUIDES
MANAGE
SESSIONS.
Sessions are budget-capped containers for LLM spend. Every request made with a session ID is tracked against its budget. No overruns. No surprises.
What is a session?
- →A UUID-identified spending container with a hard USD budget cap.
- →All LLM requests tagged with a session_id draw from its budget.
- →When the budget is exhausted, further requests return 402 SESSION_BUDGET_EXCEEDED.
- →Sessions can be funded incrementally — top up without creating a new one.
- →Session stats (spend, cache hits, request count) are available in real time.
Create a Session
bash
curl -s -X POST https://p402.io/api/v2/sessions \
-H "Authorization: Bearer $P402_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"budget_usd": 10,
"expires_in_hours": 24
}' | jq .Response
{
"id": "sess_01jx...",
"budget_usd": 10.00,
"budget_spent_usd": 0.00,
"budget_remaining_usd": 10.00,
"status": "active",
"expires_at": "2026-04-16T12:00:00.000Z",
"created_at": "2026-04-15T12:00:00.000Z"
}budget_usd
Required
Hard cap in USD (minimum $0.10).
expires_in_hours
Optional
TTL in hours. Default: 168 (7 days).
agent_id
Optional
Bind session to a registered agent DID.
metadata
Optional
Arbitrary key-value pairs, returned in stats.
Use a Session
Pass session_id in the p402 extension block of any chat completion. Budget is debited atomically before the LLM call — you never overspend.
bash
curl -s -X POST https://p402.io/api/v2/chat/completions \
-H "Authorization: Bearer $P402_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"messages": [{"role": "user", "content": "Summarise EIP-3009."}],
"p402": {
"session_id": "sess_01jx...",
"mode": "cost",
"cache": true
}
}' | jq .p402_metadata{
"provider": "deepseek",
"model": "deepseek-v3",
"cost_usd": 0.0003,
"cached": false,
"session_remaining_usd": 9.9997 // ← remaining budget after this request
}Inspect a Session
bash
# Get session details
curl -s https://p402.io/api/v2/sessions/sess_01jx... \
-H "Authorization: Bearer $P402_API_KEY" | jq .
# Get real-time stats
curl -s https://p402.io/api/v2/sessions/sess_01jx.../stats \
-H "Authorization: Bearer $P402_API_KEY" | jq .Stats response
{
"id": "sess_01jx...",
"budget_usd": 10.00,
"budget_spent_usd": 0.0012,
"budget_remaining_usd": 9.9988,
"request_count": 5,
"cache_hits": 1,
"cache_savings_usd": 0.0003,
"status": "active",
"expires_at": "2026-04-16T12:00:00.000Z"
}List Sessions
bash
# Active sessions
curl -s "https://p402.io/api/v2/sessions?status=active&limit=20" \
-H "Authorization: Bearer $P402_API_KEY" | jq .
# All sessions (paginated)
curl -s "https://p402.io/api/v2/sessions?limit=50&offset=0" \
-H "Authorization: Bearer $P402_API_KEY" | jq '.sessions[] | {id, budget_usd, budget_spent_usd, status}'Top Up a Session
Add budget to an existing active session without interrupting in-flight requests.
bash
curl -s -X POST https://p402.io/api/v2/sessions/sess_01jx.../fund \
-H "Authorization: Bearer $P402_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_usd": 5}' | jq .Response
{
"id": "sess_01jx...",
"budget_usd": 15.00, // was 10.00, now 15.00
"budget_remaining_usd": 14.9988,
"status": "active"
}Close a Session
Closing a session immediately rejects all new requests. In-flight requests are allowed to complete. Unspent budget is released.
bash
curl -s -X DELETE https://p402.io/api/v2/sessions/sess_01jx... \
-H "Authorization: Bearer $P402_API_KEY" | jq .{ "status": "closed", "budget_spent_usd": 0.0012 }Error Handling
Error Code
Meaning
SESSION_NOT_FOUND
The session ID does not exist or belongs to another tenant.
SESSION_BUDGET_EXCEEDED
The session has no remaining budget. Top up or create a new session.
SESSION_EXPIRED
The session TTL has elapsed. Expired sessions cannot be reactivated.
SESSION_CLOSED
Session was explicitly closed via DELETE. Create a new one.
BUDGET_RESERVATION_FAILED
Concurrent request exceeded budget atomically. Retry immediately.