How to query

ℹ️

Public preview

The Analytics API is in public preview: on for every account, and features may change. Monitor run metrics are in private preview: reach out to your account representative to request access. See Integration and feature lifecycles for what this means.

🤖

Using an agent? It writes the queries for you. This page is for agents and for anyone querying the Analytics API directly.

A query

A query asks for one or more metrics, grouped by dimensions, with filters. These pages describe every example query this way. This one counts alerts per week over the last 3 months:

• Metrics: incident_count
• Grouped by: metric_time__week
• Filter: metric_time__day on or after 3 months ago

The answer has a column per metric and dimension, the rows, and how current the data is. Read columns by name, not by position.

Group and filter by dimensions

Grouped by and Filter take dimensions only, and a dimension of every metric in the query. An object such as asset, monitor or domain is not a dimension: a query that groups or filters by one is refused with a message such as "asset is an entity, not a dimension". For one row per item, or to filter on a list of items, use the object's key:

A dimension reached through another object keeps the whole path, and the path depends on the metric. The warehouse, for example:

Take the name the catalog lists for the metric; an error names the ones it accepts. The Dimensions pages list the names, and GET .../account-analytics/catalog lists the dimensions of each metric.

Send a query

The Analytics API has two calls, both authenticated with a Monte Carlo API key in the header Authorization: Bearer <key id>:<key secret>:

• GET https://<api host>/api/v2/account-analytics/catalog lists the metrics and the dimensions each one groups by.
• POST https://<api host>/api/v2/account-analytics/query runs a query, sent as JSON.

The API host ($MC_API_HOST below) is the address you open Monte Carlo at with api. in front, and its key is one created there:

A query in words maps to the JSON like this:

true and false are JSON booleans; other values are strings. A date such as "30 days ago" is sent as the date, YYYY-MM-DD. The example questions on the Metrics pages show each query in words and as JSON.

curl -s -X POST "https://$MC_API_HOST/api/v2/account-analytics/query" \
  -H "Authorization: Bearer $MCD_ID:$MCD_TOKEN" -H 'Content-Type: application/json' \
  -d '{"metrics": ["coverage_rate", "covered_assets", "population_assets"]}'

The answer is JSON: columns (the dimensions, then the metrics), rows, data_as_of (how current the data is) and truncated (true when there were more rows than the limit). An account can send up to 10 queries per second; above that the API answers 429: wait a second and send the query again.

Names

• Metric names are unique, for example coverage_rate.
• Dimension names start with what they describe: monitor__monitor_type, domain__domain_name. The Dimensions pages list them.
• Not every dimension works with every metric. Each metric's row says which dimensions it groups by; a query with another dimension is refused with a message that lists the dimensions that work. To combine two groupings, take two steps, as Before you group or filter shows.
• To split a metric by domain, data product, asset tag, monitor domain, monitor tag or audience, use its per-grouping metric, such as domain_coverage_rate. Members overlap, and tables, monitors or alerts that belong to no member are in no row, so their numbers do not add up to the account's: see Totals across members in Before you group or filter. The account's number comes from the metric without the grouping, such as coverage_rate.

Time

• metric_time is each metric's own date: when an alert was created, when an event was detected, the day credits were consumed. Group by it at a grain: metric_time__day, metric_time__week or metric_time__month.
• Filter dates are dates (YYYY-MM-DD), not expressions such as "last 30 days": compute the date first. The examples on these pages say "30 days ago" for the date 30 days before today.
• Periods ("this quarter", "last month") and how far back a daily, weekly or monthly series goes: Time in the Glossary.
• Some metrics are current state, not a series: coverage and the asset health metrics named with a window (asset_health_score_7d, domain_asset_health_score_30d). Do not group them by metric_time. Monitor counts and asset_health_score are a series: the value on each day, week or month.
• Every metric keeps a set history: 13 full months unless its description says less (daily asset health keeps 30 days, weekly 26 weeks). Asking for earlier dates returns the rows from that start, without an error: check the first row's date, and use the weekly or monthly metric for older periods.

Filters

A filter keeps the rows where a dimension has the values you name. A query can have several filters, and a row has to pass all of them. The pages write a filter in words:

For example, the number of monitors per monitor type, without deleted monitors and without validation monitors:

• Metrics: monitor_count
• Grouped by: monitor__monitor_type
• Filter: monitor__is_monitor_deleted is false
• Filter: monitor__monitor_type is not validation

Values are strings, numbers or true / false. Values of a dimension are your own, such as your domain names; the dimension's description tells what they mean.

• Filter on a dimension, never on a metric. To keep only monitors with a breach, group by monitor__monitor_uuid and read the metric.
• To filter on a list of tables or monitors, use asset__asset_mcon or monitor__monitor_uuid.
• A row with an empty value passes neither "is" nor "is not": "is none of a, b" leaves out the empty rows too. To see the empty group, group by the dimension and read its empty row.
• "At least" and "at most" include the value itself. A filter matches whole values: to find values by part of a name (every domain with "finance" in it), list the dimension's values first, with a count grouped by the dimension, and filter on the ones you need.

The answer

• No rows means nothing matched. A filter value that does not exist also gives no rows, so list the dimension's values to tell the two apart.
• A member with nothing in the period has no row, not a row with 0.
• An empty value in a dimension column is a group of its own, such as monitors without a data quality dimension or alerts without a severity, never a total.
• A request grouped by several dimensions has no total rows: a member's total comes from the same metric grouped by the member alone.
• A total or a headline number comes from a request without the grouping. Rows of overlapping members, and rows of a breakdown by several dimensions, do not add up to it.
• An answer marked truncated holds only the first rows: say so, and never estimate the rest.
• A request grouped by asset__asset_mcon includes AI agents and other assets that are not tables; for tables only, filter asset__asset_category is table.
• A request grouped by asset__asset_mcon or monitor__monitor_uuid can return thousands of rows. Ask only for the columns you show, and for a top N with "Sorted by" and "At most N rows".

Access

• Every query is scoped to your account.
• What a query returns goes to the AI tool you connect, and to the model that tool uses, under that tool's terms.
• If your access is limited to some domains, queries are limited to them too. Metrics that cannot be split by domain are refused with a message that points to their per-domain metrics: metrics not tied to a domain are only available to users with access to all domains.