Sign in
CustomerMetrics

Query a metric time series

Returns a time series of aggregated metric values for the named metric within the requested time range, together with the metric's descriptor.

get/v2/metrics/{metric_name}

Path parameters

metric_namestring required

The name of the metric to query (see /v2/metrics for the catalog).

Query parameters

dimensionsobject

Dimension filters keyed by dimension name, for example dimensions[agent_keys]=support-bot. Each metric's descriptor at /v2/metrics lists its dimension names. A dimension with several values matches any of them, and the series merges the matched values.

labelsobject

Deprecated alias for dimensions; identical semantics. Use dimensions. Ignored when dimensions is supplied.

startstring date-time required

The inclusive start of the query window (ISO 8601). For a system metric, no more than 30 days before now. A window is at most 30 days long. Points older than the metric's retention window are omitted; the first point keeps its bin_start, so when start is older than the retained data that point covers only the retained portion of its bin.

endstring date-time required

The exclusive end of the query window (ISO 8601). Must be after start and no more than 30 days after it.

max_binsinteger

The upper bound on the number of points in the response. The response may contain fewer points than requested but never more. The response reports the actual time-bin size as bin_size_seconds. When max_bins is 1, the response has one point covering the requested window, with start rounded down and end rounded up to the nearest five-minute boundary; bin_size_seconds is the width of that rounded window. Defaults to 60.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Response

The requested metric series.

OR
OR
OR

Example response

{
  "metric": {
    "name": "agent.trace.duration_ms",
    "category": "agent",
    "unit": "ms",
    "display_name": "Agent turn duration percentiles",
    "dimensions": [
      "agent_keys"
    ],
    "origin": "system",
    "type": "counter"
  },
  "type": "counter"
}

Changes

Changed in 2 of the 13 revisions of this API.16

  • 3f4075adad3d2See the full diff
    • ○

      added the media type application/json for the response with the status

      response-media-type-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

  • de6b34bc4a4f14See the full diff
    • ○

      added the new optional query request parameter dimensions

      new-optional-request-parameter

    • ○

      query request parameter labels was deprecated

      request-parameter-deprecated

    • ○

      response property oneOf[CounterMetricSeries]/allOf[MetricSeriesBase]/labels deprecated

      response-property-deprecated

    • ○

      response property oneOf[DistributionMetricSeries]/allOf[MetricSeriesBase]/labels deprecated

      response-property-deprecated

    • ○

      response property oneOf[GaugeMetricSeries]/allOf[MetricSeriesBase]/labels deprecated

      response-property-deprecated

    • ○

      response property oneOf[PercentilesMetricSeries]/allOf[MetricSeriesBase]/labels deprecated

      response-property-deprecated

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    • ○

      added the required property //////// to the response with the status

      response-required-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog