What are cache fields?
Cache fields let you tag AI requests with business identifiers that echo back in every response and appear in your observability dashboard. They bridge the gap between your application's context and ModelRiver's processing pipeline.
When you define cache fields on a workflow, ModelRiver extracts matching values from your request payload and includes them in:
- The API response under
customer_data - The Request Logs table for filtering and search
- Webhook payloads for downstream processing
- Timeline views in Observability
Configuring cache fields
Add cache fields when creating or editing a workflow:
- Navigate to Workflows in your project
- Open an existing workflow or create a new one
- In the Cache Fields section, enter field paths separated by commas or newlines
Field path syntax
Use dot notation for nested data and indexes for arrays:
| Path | Extracts from |
|---|---|
user_id | Top-level user_id field |
metadata.segment | Nested metadata.segment value |
messages.0.content | First message's content field |
metadata.experiment.bucket | Deeply nested experiment bucket |
Example request and response
Request:
JSON
1{2 "workflow": "support-summarizer",3 "messages": [{"role": "user", "content": "Summarise this ticket"}],4 "metadata": {5 "user_id": "usr_abc123",6 "segment": "enterprise",7 "experiment": {"bucket": "v2"}8 }9}Response includes:
JSON
1{2 "customer_data": {3 "metadata.user_id": "usr_abc123",4 "metadata.segment": "enterprise",5 "metadata.experiment.bucket": "v2"6 }7}Best practices
- Keep it selective: Cache only the fields you need for observability. Avoid caching sensitive or high-cardinality data.
- Use consistent naming: Standardise field paths across workflows so dashboards and filters work uniformly.
- Don't replace persistence: Customer data is for observability echo, not a substitute for your database. Treat it as a convenient annotation layer.
- Leverage in debugging: Filter Request Logs by customer data values to trace specific users or experiments.
Next steps
- Structured outputs: Enforce JSON response schemas
- Test mode: Validate workflows without provider calls
- Observability: Monitor and debug with customer data filters