Running pipelines: manage_meters_run
Use manage_meters_run operations to start, monitor, stop, and analyze meter runs, manage prefetch jobs, and ingest usage events.
| Operation | Access | What it does |
|---|---|---|
| run_guidance | Read | Describes the workflow. Start here. |
| run_meter | Write | Starts a run. Accepts a mode (normal or debug) and optional run parameters. |
| stop_meter_run | Write | Stops a run. Using the run ID is preferred. |
| get_run_status | Read | Returns the current status of a meter version |
| list_run_history | Read | Lists past runs, with filters and cursor pagination |
| get_run_summary | Read | Returns operator-level statistics for a run |
| get_run_records | Read | Returns paged output records from a SINK step |
| query_event_store | Read | Runs an asynchronous SQL SELECT against an event store and returns a query ID |
| get_operator_summary | Read | Returns aggregated operator statistics over a time window |
| list_prefetch_definitions | Read | Lists live prefetch definitions for a meter version |
| get_prefetch_status | Read | Returns the status of a prefetch job |
| start_prefetch | Write | Starts a prefetch job, optionally for a single processor |
| cancel_prefetch | Write | Cancels a prefetch job |
| ingest_usage_events | Write | Returns the REST endpoint and instructions for sending usage events. Your system makes the POST request with its own OAuth credentials. |
Run status values
| Status | Meaning |
|---|---|
| INITIALIZING | The run is starting up |
| JOB_SUBMISSION_IN_PROGRESS | The run job is being submitted |
| RUNNING | The run is active |
| PAUSED | The run is paused |
| STOPPING | A graceful stop is in progress |
| COMPLETED | The run finished. Confirm billing completeness through the error audit. |
| FAILED | The run failed |
| CANCELED | The run was canceled |
| FORCE_STOPPED | The run was force stopped |
| NEVER_RUN | The meter version has never been run |
Stopping a run
| Method | Behavior | When to use it |
|---|---|---|
| Graceful stop (default) | Shuts down streaming pipelines cleanly by saving a checkpoint | Normal stops |
| Force stop | Stops the run immediately through the REST API (forceStop=true) | Only when a run is stuck in STOPPING or RUNNING after a graceful attempt |
You cannot force a stop while its status is STOPPING. A force stop on a streaming pipeline results in FORCE_STOPPED, and in-flight data may be lost. Confirm with your team before using force stop.
Prefetch
Prefetch loads reference data, such as lookup tables, before a run needs it. The typical sequence is:
- Check existing definitions or the current prefetch status for a meter version.
- Start prefetch for a specific processor. The response returns a job ID.
- Poll the job status until it reaches FETCHED.
- Cancel the job if you no longer need it.
If you start prefetch without specifying a processor, it runs for all live definitions. In that case no job ID is returned, so you track progress through the prefetch status instead.
Direct ingestion
ingest_usage_events does not send events for you. It returns the REST endpoint along with instructions. Your system then sends the events using its own OAuth credentials. Each event must include CustomerId, UsageIdentifier, UsageDate, and Quantity.