> This page is for Docs. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://zuora.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server. # Runtime configuration for meter runs > Runtime configuration lets you change the input source for a single meter run without modifying the stored meter definition or creating a new version. Runtime overrides apply only to the current run. The stored meter definition remains unchanged. Runtime configuration lets you change the input source for a single meter run without modifying the stored meter definition or creating a new version. Runtime overrides apply only to the current run. The stored meter definition remains unchanged. 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: | Field | Purpose | | ------------------------- | ------------------------------------------------------------------------ | | `runtimeSourceConfigs` | Preferred mechanism for overriding source configuration for a single run | | `sourceOptions` | Legacy mechanism for selecting uploaded/test files | | `eventStoreSourceOptions` | Legacy mechanism for specifying Event Store date ranges | | `uniqueKey` | Optional idempotency key for safely retrying a run | For new integrations, use `runtimeSourceConfigs`. ## Supported runtime sources | Source type | Settings that you can override | | --------------- | ------------------------------------------------------------------------ | | `LOCAL_FS` | Uploaded file by using `fileId`. | | `S3` | Connection, paths, file format, and read behavior. | | `SNOWFLAKE` | Database, schema, table or query, query parameters, warehouse, and role. | | `EVENT_STORE` | Event Store, date range, or query. | | `STREAMING_API` | Initial stream position: `EARLIEST` or `LATEST`. | ## 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. ```json { "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. ```json { "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: ```json { "sourceType": "SNOWFLAKE", "snowflake": { "database": "ANALYTICS", "schema": "USAGE", "table": "usage_events" } } ``` You can also execute a different read query: ```json { "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. ```json { "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. ```json { "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 ```json { "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.