Documentation

Customer data & cache fields

Attach business context to every AI request. Surface user IDs, experiment buckets, and metadata without storing full payloads.

What are cache fields?

Cache fields let you tag AI requests with business identifiers that echo back in every response and in the events ModelRiver sends for that request. 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 synchronous /v1/ai response under customer_data
  • WebSocket messages for async requests (including the final result)
  • Webhook payloads for downstream processing
  • Every step of a backend pipeline, through to the final result

Each key in customer_data is the field path you configured (for example metadata.user_id), not just the last segment.

Request Logs don't store customer_data as a separate column, and you can't filter or search logs by it. The original values are visible in the logged request body when the project saves full request and response text.

Configuring cache fields

Add cache fields when creating or editing a workflow:

  1. Navigate to Workflows in your project
  2. Open an existing workflow or create a new one
  3. In the Custom fields setting (under advanced settings), enter field paths separated by commas or newlines

Field path syntax

Use dot notation for nested data and indexes for arrays:

PathExtracts from
user_idTop-level user_id field
metadata.segmentNested metadata.segment value
messages.0.contentFirst message's content field
metadata.experiment.bucketDeeply nested experiment bucket

Example request and response

Request:

JSON
1{
2 "model": "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 the customer_data keys your code reads stay the same.
  • 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: Log customer_data in your own application or webhook handler so you can trace specific users or experiments alongside ModelRiver's channel_id.

Next steps