---
editLink: false
lastUpdated: false
outline: [2, 3]
---

<!-- Generated by python/b2c-tooling-sdk/scripts/generate_api_docs.py. Do not edit. -->

# b2c_tooling_sdk.operations.metrics

Metrics operations for B2C Commerce (Observability).

Mirrors `src/operations/metrics/index.ts`. Provides typed, high-level
functions for retrieving operational time-series metrics from the SCAPI
Observability Metrics API (`observability/metrics/v1`). Each metric *category*
has its own function; all return the same metrics-data-response envelope (as raw
JSON `dict`).

Categories:

- [`get_overall_metrics`](/python/api/operations/metrics#get-overall-metrics) — overall application metrics
- [`get_sales_metrics`](/python/api/operations/metrics#get-sales-metrics) — sales metrics
- [`get_ecdn_metrics`](/python/api/operations/metrics#get-ecdn-metrics) — embedded CDN metrics
- [`get_third_party_metrics`](/python/api/operations/metrics#get-third-party-metrics) — third-party service call metrics
- [`get_scapi_metrics`](/python/api/operations/metrics#get-scapi-metrics) — SCAPI request metrics
- [`get_scapi_hooks_metrics`](/python/api/operations/metrics#get-scapi-hooks-metrics) — SCAPI hook execution metrics
- [`get_mrt_metrics`](/python/api/operations/metrics#get-mrt-metrics) — Managed Runtime metrics
- [`get_controller_metrics`](/python/api/operations/metrics#get-controller-metrics) — controller/pipeline metrics
- [`get_ocapi_metrics`](/python/api/operations/metrics#get-ocapi-metrics) — OCAPI request metrics

[`get_metrics_by_category`](/python/api/operations/metrics#get-metrics-by-category) dispatches to the correct function by category
name.

The Metrics API wire format is epoch **seconds**; these operations convert
millisecond inputs to seconds on the way out and normalize response timestamps
back to **milliseconds** on the way in.

Authentication requires OAuth client-credentials with the `sfcc.metrics` admin
scope, attached automatically by [`create_metrics_client`](/python/api/clients#create-metrics-client).

## Classes

### MetricsQueryOptions {#metricsqueryoptions}

```python
class MetricsQueryOptions(MetricsTimeWindow)
```

Union of every option shape accepted by [`get_metrics_by_category`](/python/api/operations/metrics#get-metrics-by-category).

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `third_party_service_id` | `str \| None` | `None` |
| `api_family` | `str \| None` | `None` |
| `api_name` | `str \| None` | `None` |
| `ocapi_category` | `str \| None` | `None` |
| `ocapi_api` | `str \| None` | `None` |

### MetricsTagContext {#metricstagcontext}

```python
class MetricsTagContext
```

The request identity and applied filters used to derive authoritative tags.

`realm`/`environment` are parsed from `tenant_id`. The optional filter
fields mirror the Metrics API's category filters; when a filter was sent, that
dimension is *known from the request* and is stamped onto every series as an
authoritative tag — rather than being (mis)parsed from a drilled-down series
id.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `tenant_id` | `str` |  |
| `api_family` | `str \| None` | `None` |
| `api_name` | `str \| None` | `None` |
| `ocapi_category` | `str \| None` | `None` |
| `ocapi_api` | `str \| None` | `None` |
| `third_party_service_id` | `str \| None` | `None` |

### MetricsTimeWindow {#metricstimewindow}

```python
class MetricsTimeWindow
```

Time-window options common to every metrics operation.

Accepts either a `datetime` or a number of **epoch milliseconds** (the
same unit as `Date.now()`) for both `from_` and `to`. Both optional;
when omitted the API applies its default window.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `from_` | `datetime \| int \| float \| None` | `None` |
| `to` | `datetime \| int \| float \| None` | `None` |

### MetricsWindowInput {#metricswindowinput}

```python
class MetricsWindowInput
```

Raw `from`/`to`/`window` inputs before resolution. Any subset may be provided.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `from_` | `MetricsBoundInput \| None` | `None` |
| `to` | `MetricsBoundInput \| None` | `None` |
| `window` | `int \| str \| None` | `None` |

### OcapiMetricsOptions {#ocapimetricsoptions}

```python
class OcapiMetricsOptions(MetricsTimeWindow)
```

Options for [`get_ocapi_metrics`](/python/api/operations/metrics#get-ocapi-metrics): time window plus optional OCAPI filters.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `ocapi_category` | `str \| None` | `None` |
| `ocapi_api` | `str \| None` | `None` |

### ResolvedMetricsWindow {#resolvedmetricswindow}

```python
class ResolvedMetricsWindow
```

A resolved metrics window. Both `from_` and `to` are always present.

**Fields**

| Name | Type |
| --- | --- |
| `from_` | `datetime` |
| `to` | `datetime` |
| `from_iso` | `str` |
| `to_iso` | `str` |
| `from_epoch_seconds` | `int` |
| `to_epoch_seconds` | `int` |
| `clamped_from` | `bool` |
| `defaulted_window` | `bool` |

### ScapiMetricsOptions {#scapimetricsoptions}

```python
class ScapiMetricsOptions(MetricsTimeWindow)
```

Options for [`get_scapi_metrics`](/python/api/operations/metrics#get-scapi-metrics): time window plus optional SCAPI filters.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `api_family` | `str \| None` | `None` |
| `api_name` | `str \| None` | `None` |

### ThirdPartyMetricsOptions {#thirdpartymetricsoptions}

```python
class ThirdPartyMetricsOptions(MetricsTimeWindow)
```

Options for [`get_third_party_metrics`](/python/api/operations/metrics#get-third-party-metrics): time window plus a service filter.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `third_party_service_id` | `str \| None` | `None` |

## Functions

### enrich_metrics_tags {#enrich-metrics-tags}

```python
def enrich_metrics_tags(response: dict[str, Any], category: MetricCategory, context: MetricsTagContext) -> MetricsTaggedResponse
```

Enrich a metrics response by adding a structured `tags` map to every series.

Returns a new response (the input is not mutated). Walks every metric and
series and attaches `series["tags"]` derived from the series id, the metric
id, the category, and the request context. Existing fields (`id`, `name`,
`data`) are preserved exactly, so the enriched response is a structural
superset. The category must be supplied because a metrics response does not
carry it (it is implied by the endpoint that produced the response).

### get_controller_metrics {#get-controller-metrics}

```python
async def get_controller_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve controller/pipeline metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_ecdn_metrics {#get-ecdn-metrics}

```python
async def get_ecdn_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve embedded CDN (eCDN) metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_metrics_by_category {#get-metrics-by-category}

```python
async def get_metrics_by_category(client: MetricsClient, tenant_id: str, category: MetricCategory, options: MetricsQueryOptions | None = None) -> dict[str, Any]
```

Retrieve metrics for a category by name, dispatching to the category-specific function.

Category-specific filters are applied only for the categories that support
them and ignored otherwise.

**Raises**

- `RuntimeError` — if the request fails.
- `ValueError` — if the category is unknown.

### get_mrt_metrics {#get-mrt-metrics}

```python
async def get_mrt_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve Managed Runtime (MRT) metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_ocapi_metrics {#get-ocapi-metrics}

```python
async def get_ocapi_metrics(client: MetricsClient, tenant_id: str, options: OcapiMetricsOptions | None = None) -> dict[str, Any]
```

Retrieve OCAPI request metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_overall_metrics {#get-overall-metrics}

```python
async def get_overall_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve overall application metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_sales_metrics {#get-sales-metrics}

```python
async def get_sales_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve sales metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_scapi_hooks_metrics {#get-scapi-hooks-metrics}

```python
async def get_scapi_hooks_metrics(client: MetricsClient, tenant_id: str, options: MetricsTimeWindow | None = None) -> dict[str, Any]
```

Retrieve SCAPI hook execution metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_scapi_metrics {#get-scapi-metrics}

```python
async def get_scapi_metrics(client: MetricsClient, tenant_id: str, options: ScapiMetricsOptions | None = None) -> dict[str, Any]
```

Retrieve SCAPI request metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### get_third_party_metrics {#get-third-party-metrics}

```python
async def get_third_party_metrics(client: MetricsClient, tenant_id: str, options: ThirdPartyMetricsOptions | None = None) -> dict[str, Any]
```

Retrieve third-party service call metrics for an organization.

**Raises**

- `RuntimeError` — if the request fails.

### parse_metrics_bound {#parse-metrics-bound}

```python
def parse_metrics_bound(value: MetricsBoundInput, now: datetime | None = None) -> datetime
```

Parse a single metrics time bound (`from` or `to`) into a `datetime`.

Resolves a single bound in isolation; deriving the companion bound and
applying the 24-hour default window is the job of [`resolve_metrics_window`](/python/api/operations/metrics#resolve-metrics-window).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `value` | `MetricsBoundInput` | The bound: a `datetime`, epoch milliseconds, a relative duration (`5m`/`1h`/`2d`, relative to `now`), or an ISO 8601 timestamp. |
| `now` | `datetime \| None` | Reference time for relative durations (defaults to the current time; injectable for deterministic tests). |

**Raises**

- `ValueError` — if a string value is neither a valid relative duration nor a parseable ISO 8601 timestamp.

### parse_series_tags {#parse-series-tags}

```python
def parse_series_tags(*, category: MetricCategory, metric_id: str, series_id: str, context: MetricsTagContext) -> MetricSeriesTags
```

Extract the dimension tags for a single series id.

Combines three tiers, most-authoritative last:

1. **Request identity** — `realm`/`environment` from the tenant id.
2. **String heuristics** — category/metric-specific dimensions parsed from the
   packed id, or the raw remainder under `series` when no rule matches.
3. **Applied filters** — any filter that was sent with the request
   ([`MetricsTagContext`](/python/api/operations/metrics#metricstagcontext)) is stamped last, overriding a heuristic guess.

The result is always a superset of the request context and never throws.

### resolve_metrics_window {#resolve-metrics-window}

```python
def resolve_metrics_window(input: MetricsWindowInput | None = None, now: datetime | None = None) -> ResolvedMetricsWindow
```

Resolve `from`/`to`/`window` inputs into concrete bounds for the Metrics API.

Always produces an explicit `from_`+`to` pair. Resolution rules:

- `from` + `to` — used as given; `window` must NOT also be set.
- `from` + `window` — `to = from + window`.
- `to` + `window` — `from = to - window`.
- `window` only — the last `window`: `to = now`, `from = now - window`.
- `from` only — a 24-hour window forward: `to = min(from + 24h, now)`.
- `to` only — a 24-hour window back: `from = to - 24h`.
- nothing — the last 24 hours.

A `from` at or beyond the 30-day retention floor is clamped *forward* to
`now - 30 days + margin` so requests like `--from 30d` are not rejected by
the server's slightly-later clock.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `input` | `MetricsWindowInput \| None` | The raw `from`/`to`/`window` inputs. |
| `now` | `datetime \| None` | Reference time for relative bounds, default/window modes, and the retention clamp (defaults to the current time; injectable for tests). |

**Raises**

- `ValueError` — if a bound or the window string is unparseable, if all three are supplied, or if the resolved `from` is after `to`.

## Attributes

### METRICS_DEFAULT_WINDOW_MS {#metrics-default-window-ms}

```python
METRICS_DEFAULT_WINDOW_MS = 24 * 60 * 60 * 1000
```

### METRICS_RETENTION_MS {#metrics-retention-ms}

```python
METRICS_RETENTION_MS = 30 * 24 * 60 * 60 * 1000
```

### METRICS_RETENTION_SAFETY_MARGIN_MS {#metrics-retention-safety-margin-ms}

```python
METRICS_RETENTION_SAFETY_MARGIN_MS = 5 * 60 * 1000
```

### METRIC_CATEGORIES {#metric-categories}

```python
METRIC_CATEGORIES: tuple[str, ...] = ('overall', 'sales', 'ecdn', 'third-party', 'scapi', 'scapi-hooks', 'mrt', 'controller', 'ocapi')
```

### MetricCategory {#metriccategory}

```python
MetricCategory = Literal['overall', 'sales', 'ecdn', 'third-party', 'scapi', 'scapi-hooks', 'mrt', 'controller', 'ocapi']
```

### MetricSeriesTags {#metricseriestags}

```python
MetricSeriesTags = dict[str, str]
```

### MetricsBoundInput {#metricsboundinput}

```python
MetricsBoundInput = datetime | int | float | str
```

### MetricsTaggedResponse {#metricstaggedresponse}

```python
MetricsTaggedResponse = dict[str, Any]
```