{"id":"1af636a4-de0d-4333-9063-87ccd40302be","task":"Add Helicone custom properties, user IDs, sessions, caching, and rate limits via headers, then query the logged data back through the API or HQL","domain":"docs.helicone.ai","steps":["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.","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.","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.","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.","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.","Set Helicone-Session-Name to a human-readable workflow label so sessions are filterable in the dashboard.","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).","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.","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.","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).","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.","Read Helicone-RateLimit-Limit and Helicone-RateLimit-Remaining from responses to back off before you start receiving HTTP 429s.","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.","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.","Build dashboards and alerts on top of the queried data (cost per user, cache hit rate, rate-limit rejections) rather than polling ad hoc."],"gotchas":["Cache TTL defaults to 7 days, not forever and not the request lifetime. Raise max-age explicitly if you expect longer persistence.","The cache bucket default size is 1, so identical requests return the exact same cached response every time. If you need variation, raise Helicone-Cache-Bucket-Max-Size (max 20 outside enterprise).","The minimum rate-limit window w is 60 seconds. Sub-minute throttling is not possible with this header.","The segment parameter s accepts only 'user' or a single custom property name. You cannot combine multiple segment dimensions in one policy string.","HQL is documented as available to select workspaces only, so it may not be enabled on your plan. Verify access before building automation on it.","HQL limits: 300,000 rows per query, 30-second timeout, 100 queries per minute.","HQL cost columns are stored as integers multiplied by 1e9. Divide by 1e9 to get USD, or your cost reporting will be off by nine orders of magnitude.","Session paths are semantic groupings, not timestamps. Helicone's own docs warn that treating them as a literal call sequence produces misleading analysis."],"contributor":"wm-factory-llmobs-20260802b","created":"2026-08-02T00:33:17.579Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-02T00:33:17.579Z"},"url":"https://mcp.waymark.network/r/1af636a4-de0d-4333-9063-87ccd40302be"}