Add Helicone custom properties, user IDs, sessions, caching, and rate limits via headers, then query the logged data back through the API or HQL

Documented steps

1. Confirm requests are already flowing through a Helicone base URL. These headers only take effect on proxied gateway requests, not on async-logged direct calls.
2. Attach Helicone-User-Id to every request with the identifying string, email, or UUID so per-user cost and usage roll up correctly in the dashboard.
3. Add one or more Helicone-Property-<Name> headers for business dimensions you will want to slice by later, for example Helicone-Property-Environment: prod or Helicone-Property-App: mobile. These also become valid segments for rate-limit policies.
4. For multi-step or agentic workflows, generate one UUID per logical session and send it as Helicone-Session-Id on every request in that workflow.
5. Set Helicone-Session-Path to a slash-delimited conceptual hierarchy such as /abstract/outline/lesson-1. This represents grouping, not chronological order; keep identical paths for repeated work of the same type so dashboard timing comparisons are meaningful.
6. Set Helicone-Session-Name to a human-readable workflow label so sessions are filterable in the dashboard.
7. Enable caching with Helicone-Cache-Enabled: true. Control TTL with Cache-Control: max-age=<seconds>; the default is 604800 (7 days) and the maximum is 31536000 (365 days).
8. Verify caching is working by reading the Helicone-Cache response header, which returns HIT or MISS, and Helicone-Cache-Bucket-Idx for the bucket slot that served the response.
9. If cached responses must not be shared across tenants or users, set Helicone-Cache-Seed to a per-user or per-tenant namespace string. Use Helicone-Cache-Ignore-Keys (comma-separated) to exclude volatile fields from the cache key.
10. If you want several distinct cached variants for the same prompt rather than one frozen answer, raise Helicone-Cache-Bucket-Max-Size (default 1, cap 20, higher on enterprise).
11. Enable rate limiting with Helicone-RateLimit-Policy formatted as "<quota>;w=<window_seconds>;u=<unit>;s=<segment>". Examples: "1000;w=3600" for 1000 requests per hour globally, "1000;w=86400;s=user" for 1000 per day per user, "500;w=3600;u=cents;s=user" for a $5 per hour per user cost cap, "5000;w=3600;s=organization" to segment on a custom property.
12. Read Helicone-RateLimit-Limit and Helicone-RateLimit-Remaining from responses to back off before you start receiving HTTP 429s.
13. Pull data back programmatically with POST https://api.helicone.ai/v1/request/query (EU tenants use eu.api.helicone.ai), sending Authorization: Bearer <HELICONE_API_KEY> and a body of { filter, offset, limit, sort, isCached, includeInputs, isScored, isPartOfExperiment }. The filter is an AND/OR FilterNode tree over fields such as request.user_id and request.model. Paginate with offset and limit.
14. For aggregation beyond simple filters, use HQL: POST https://api.helicone.ai/v1/helicone-sql/execute with Authorization: Bearer <API_KEY>, plus GET /schema, POST /download, and saved-query CRUD on the same base.
15. Build dashboards and alerts on top of the queried data (cost per user, cache hit rate, rate-limit rejections) rather than polling ad hoc.