---
title: "Query scalar data across multiple products"
method: POST
path: "/api/v2/query/scalar"
tags: ["Metrics"]
---

# Query scalar data across multiple products

`POST /api/v2/query/scalar`

Query scalar values (as seen on Query Value, Table, and Toplist widgets).
Multiple data sources are supported with the ability to
process the data using formulas and functions.

## Request body

- ScalarFormulaQueryRequest — A wrapper request around one scalar query to be executed.
  - `data` ScalarFormulaRequest, required — A single scalar query to be executed.
    - `attributes` ScalarFormulaRequestAttributes, required — The object describing a scalar formula request.
      - `formulas` QueryFormula[] — List of formulas to be calculated and returned as responses.
        - `formula` string, required — Formula string, referencing one or more queries with their name property.
        - `limit` FormulaLimit — Message for specifying limits to the number of values returned by a query. This limit is only for scalar queries and has no effect on timeseries queries.
          - `count` integer — The number of results to which to limit.
          - `order` 'asc' | 'desc' — Direction of sort.
      - `from` integer, required — Start date (inclusive) of the query in milliseconds since the Unix epoch.
      - `queries` ScalarQuery[], required — List of queries to be run and used as inputs to the formulas.
        - union — An individual scalar query to one of the basic Datadog data sources.
          - MetricsScalarQuery — A query against Datadog custom metrics or Cloud Cost data sources.
            - `aggregator` 'avg' | 'min' | 'max' | 'sum' | 'last' | 'percentile' | 'mean' | 'l2norm' | 'area', required — The type of aggregation that can be performed on metrics-based queries.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'metrics' | 'cloud_cost', required — A data source that is powered by the Metrics platform.
            - `name` string — The variable name for use in formulas.
            - `query` string, required — A classic metrics query string.
          - EventsScalarQuery — An individual scalar query for logs, RUM, traces, CI pipelines, security signals, and other event-based data sources. Use this query type for any data source powered by the Events Platform. See the data_source field for the full list of supported sources.
            - `compute` EventsCompute, required — The instructions for what to compute for this query.
              - …
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'logs' | 'spans' | 'network' | 'rum' | 'security_signals' | 'profiles' | 'audit' | 'events' | 'ci_tests' | 'ci_pipelines' | 'incident_analytics' | 'product_analytics' | 'on_call_events' | 'dora', required — A data source that is powered by the Events Platform.
            - `group_by` EventsGroupBy[] — The list of facets on which to split results.
              - …
            - `indexes` string[] — The indexes in which to search.
            - `name` string — The variable name for use in formulas.
            - `search` EventsSearch — Configuration of the search/filter for an events query.
              - …
          - ApmResourceStatsQuery — A query for APM resource statistics such as latency, error rate, and hit count, grouped by resource name.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'apm_resource_stats', required — A data source for APM resource statistics queries.
            - `env` string, required — The environment to query.
            - `group_by` string[] — Tag keys to group results by.
            - `name` string, required — The variable name for use in formulas.
            - `operation_name` string — The APM operation name.
            - `primary_tag_name` string — Name of the second primary tag used within APM. Required when `primary_tag_value` is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog
            - `primary_tag_value` string — Value of the second primary tag by which to filter APM data. `primary_tag_name` must also be specified.
            - `resource_name` string — The resource name to filter by.
            - `service` string, required — The service name to filter by.
            - `stat` 'error_rate' | 'errors' | 'hits' | 'latency_avg' | 'latency_max' | 'latency_p50' | 'latency_p75' | 'latency_p90' | 'latency_p95' | 'latency_p99' | 'latency_distribution' | 'total_time', required — The APM resource statistic to query.
          - ApmMetricsQuery — A query for APM trace metrics such as hits, errors, and latency percentiles, aggregated across services.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'apm_metrics', required — A data source for APM metrics queries.
            - `group_by` string[] — Optional fields to group the query results by.
            - `name` string, required — The variable name for use in formulas.
            - `operation_mode` string — Optional operation mode to aggregate across operation names.
            - `operation_name` string — Name of operation on service. If not provided, the primary operation name is used.
            - `peer_tags` string[] — Tags to query for a specific downstream entity (peer.service, peer.db_instance, peer.s3, peer.s3.bucket, etc.).
            - `query_filter` string — Additional filters for the query using metrics query syntax (for example, env, primary_tag).
            - `resource_hash` string — The resource hash for exact matching.
            - `resource_name` string — The full name of a specific resource to filter by.
            - `service` string — The service name to filter by.
            - `span_kind` 'consumer' | 'server' | 'client' | 'producer' | 'internal' — Describes the relationship between the span, its parents, and its children in a trace.
            - `stat` 'error_rate' | 'errors' | 'errors_per_second' | 'hits' | 'hits_per_second' | 'apdex' | 'latency_avg' | 'latency_max' | 'latency_p50' | 'latency_p75' | 'latency_p90' | 'latency_p95' | 'latency_p99' | 'latency_p999' | 'latency_distribution' | 'total_time', required — The APM metric statistic to query.
          - ApmDependencyStatsQuery — A query for APM dependency statistics between services, such as call latency and error rates.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'apm_dependency_stats', required — A data source for APM dependency statistics queries.
            - `env` string, required — The environment to query.
            - `is_upstream` boolean — Determines whether stats for upstream or downstream dependencies should be queried.
            - `name` string, required — The variable name for use in formulas.
            - `operation_name` string, required — The APM operation name.
            - `primary_tag_name` string — The name of the second primary tag used within APM; required when `primary_tag_value` is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog.
            - `primary_tag_value` string — Filter APM data by the second primary tag. `primary_tag_name` must also be specified.
            - `resource_name` string, required — The resource name to filter by.
            - `service` string, required — The service name to filter by.
            - `stat` 'avg_duration' | 'avg_root_duration' | 'avg_spans_per_trace' | 'error_rate' | 'pct_exec_time' | 'pct_of_traces' | 'total_traces_count', required — The APM dependency statistic to query.
          - SloQuery — A query for SLO status, error budget, and burn rate metrics.
            - `additional_query_filters` string — Additional filters applied to the SLO query.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'slo', required — A data source for SLO queries.
            - `group_mode` 'overall' | 'components' — How SLO results are grouped in the response.
            - `measure` 'good_events' | 'bad_events' | 'slo_status' | 'error_budget_remaining' | 'error_budget_remaining_history' | 'error_budget_burndown' | 'burn_rate' | 'slo_status_history' | 'good_minutes' | 'bad_minutes', required — The SLO measurement to retrieve.
            - `name` string — The variable name for use in formulas.
            - `slo_id` string, required — The unique identifier of the SLO to query.
            - `slo_query_type` 'metric' | 'time_slice' | 'monitor' — The type of SLO definition being queried.
          - ProcessScalarQuery — A query for host-level process metrics such as CPU and memory usage.
            - `aggregator` 'avg' | 'min' | 'max' | 'sum' | 'last' | 'percentile' | 'mean' | 'l2norm' | 'area' — The type of aggregation that can be performed on metrics-based queries.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'process', required — A data source for process-level infrastructure metrics.
            - `is_normalized_cpu` boolean — Whether CPU metrics should be normalized by core count.
            - `limit` integer — Maximum number of results to return.
            - `metric` string, required — The process metric to query.
            - `name` string, required — The variable name for use in formulas.
            - `sort` 'asc' | 'desc' — Direction of sort.
            - `tag_filters` string[] — Tag filters to narrow down processes.
            - `text_filter` string — A full-text search filter to match process names or commands.
          - ContainerScalarQuery — A query for container-level metrics such as CPU and memory usage.
            - `aggregator` 'avg' | 'min' | 'max' | 'sum' | 'last' | 'percentile' | 'mean' | 'l2norm' | 'area' — The type of aggregation that can be performed on metrics-based queries.
            - `cross_org_uuids` string[] — Organization UUIDs to query when using [cross-organization visibility](/account_management/org_settings/cross_org_visibility/). Limited to one organization UUID.
            - `data_source` 'container', required — A data source for container-level infrastructure metrics.
            - `is_normalized_cpu` boolean — Whether CPU metrics should be normalized by core count.
            - `limit` integer — Maximum number of results to return.
            - `metric` string, required — The container metric to query.
            - `name` string, required — The variable name for use in formulas.
            - `sort` 'asc' | 'desc' — Direction of sort.
            - `tag_filters` string[] — Tag filters to narrow down containers.
            - `text_filter` string — A full-text search filter to match container names.
      - `to` integer, required — End date (exclusive) of the query in milliseconds since the Unix epoch.
    - `type` 'scalar_request', required — The type of the resource. The value should always be scalar_request.

## Response `200`

OK

- ScalarFormulaQueryResponse — A message containing one or more responses to scalar queries.
  - `data` ScalarResponse — A message containing the response to a scalar query.
    - `attributes` ScalarFormulaResponseAtrributes — The object describing a scalar response.
      - `columns` ScalarColumn[] — List of response columns, each corresponding to an individual formula or query in the request and with values in parallel arrays matching the series list.
        - union — A single column in a scalar query response.
          - GroupScalarColumn — A column containing the tag keys and values in a group.
            - `name` string — The name of the tag key or group.
            - `type` 'group' — The type of column present for groups.
            - `values` array[] — The array of tag values for each group found for the results of the formulas or queries.
              - …
          - DataScalarColumn — A column containing the numerical results for a formula or query.
            - `meta` ScalarMeta — Metadata for the resulting numerical values.
              - …
            - `name` string — The name referencing the formula or query for this column.
            - `type` 'number' — The type of column present for numbers.
            - `values` number[] — The array of numerical values for one formula or query.
    - `type` 'scalar_response' — The type of the resource. The value should always be scalar_response.
  - `errors` string — An error generated when processing a request.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)