Use runtime configuration when you need to:

• Reprocess a specific Amazon S3 folder or file.

• Read a specific date range from an Event Store.

• Run a Snowflake query against a different table or dataset.

• Test a meter with a specific uploaded file.

• Start a Streaming API source from a specific position.

Run meter request

POST /meters/run/{meterId}/{version}

Runtime configuration is supplied through the request body:

For new integrations, use runtimeSourceConfigs.

Supported runtime sources

How runtime configuration works

When you submit a meter run, Zuora Mediation processes the runtime configuration in the following order:

1. Validate the runtime configuration.

2. Resolve the target source.

3. Merge the runtime overrides with the meter defaults.

4. Build the run job.

5. Submit the run.

6. Persist the runtime configuration in run history.

Configuration precedence

Zuora Mediation resolves source settings in the following order:

1. runtimeSourceConfigs

2. Existing source-option fields in the request

3. Stored meter definition

A field supplied in the runtime configuration replaces the stored value. If you do not supply a field, the run inherits its value from the meter definition.

Some source settings are mutually exclusive. For example, a Snowflake runtime configuration can specify a table or a query. An Event Store runtime configuration can specify a date range or a query. When you provide a Snowflake query, the query replaces the stored table for that run.

Target a source

Use processorId to identify the source to which a runtime configuration applies.

{
  "processorId": "s3_source_1",
  "sourceType": "S3"
}

You can omit processorId when the meter contains exactly one source of the specified type. The request is rejected in the following cases:

• The meter contains multiple sources of the specified type and processorId is omitted.

• The specified processorId does not exist.

• Two overrides target the same source.

• The meter does not contain the specified source type.

Always provide processorId when you build integrations programmatically.

Amazon S3 runtime configuration

Use an S3 runtime configuration to run an existing meter against a specific S3 location.

{
  "processorId": "s3_source_1",
  "sourceType": "S3",
  "s3": {
    "connectionName": "customer-landing",
    "paths": ["usage/2026/03/31/"],
    "fileFormat": "CSV"
  }
}

connectionName, paths, and fileFormat are required in the S3 runtime configuration. Other settings, such as incremental, batchSize, and retentionTime, can be inherited or overridden. Zuora Mediation validates S3 paths before submitting the job.

Snowflake runtime configuration

Use a Snowflake runtime configuration to point the source to a different table:

{
  "sourceType": "SNOWFLAKE",
  "snowflake": {
    "database": "ANALYTICS",
    "schema": "USAGE",
    "table": "usage_events"
  }
}

You can also execute a different read query:

{
  "sourceType": "SNOWFLAKE",
  "snowflake": {
    "database": "ANALYTICS",
    "schema": "USAGE",
    "query": "SELECT * FROM usage_events WHERE account_id = :accountId",
    "queryParameters": {
      "accountId": "A-00042"
    }
  }
}

The connection remains the one configured on the meter.

Event Store runtime configuration

Use an Event Store runtime configuration to run a meter against a specific date range or an ad hoc read query.

{
  "sourceType": "EVENT_STORE",
  "eventStore": {
    "storeId": "7781",
    "startDate": "2026-01-01",
    "endDate": "2026-01-31"
  }
}

Uploaded file runtime configuration

Specify the uploaded file by using its file ID.

{
  "sourceType": "LOCAL_FS",
  "localFs": {
    "fileId": 123
  }
}

fileId must refer to a valid uploaded file.

Retry a run safely

Use uniqueKey to make a normal run safe to retry.

"uniqueKey": "lms_meter2_2026-03-31T22:00:00Z"

If you run the same meter again with the same uniqueKey, the API returns the existing run instead of creating another one. This behavior is useful for schedulers and orchestration systems.

Without a uniqueKey, each request can create a new run.

Understand validation and errors

Zuora Mediation validates runtime configuration before submitting the job. Common validation failures include:

• Invalid or missing source type.

• Unknown processorId.

• Ambiguous source targeting.

• Duplicate source overrides.

• Missing required source parameters.

• Invalid S3 paths.

• Non-read-only Snowflake or Event Store queries.

• Invalid Event Store date ranges.

• Invalid Streaming API start position.

• Invalid uniqueKey.

A failed validation does not modify the meter definition.

Review runtime configuration in run history

Zuora Mediation persists the runtime configuration used for a run with the run history. You can use the run history to determine:

• Which runtime overrides were supplied.

• Which meter and version were executed.

• Which configuration was used.

• Which uniqueKey produced the run.

This information supports reprocessing and troubleshooting.

Example: Run a meter with an S3 override

{
  "runtimeSourceConfigs": [
    {
      "processorId": "s3_source_1",
      "sourceType": "S3",
      "s3": {
        "connectionName": "customer-landing",
        "paths": ["usage/2026/03/31/"],
        "fileFormat": "CSV"
      }
    }
  ],
  "uniqueKey": "lms_meter2_2026-03-31T22:00:00Z"
}

The existing meter version runs against the specified S3 input for this execution only. The stored meter definition remains unchanged, and the uniqueKey makes the request safe to retry.