---
updatedAt: 2026-10-03T00:46:29.000Z
agentTools:
  siteIndex: https://developer.jamf.com/llms.txt
  projectIndex: https://developer.jamf.com/platform-api/llms.txt
---

# Preview - Per-command breakdown of metrics for one AI tool

**Preview:** _This endpoint is currently in a preview state and is subject to breaking changes without warning._

**Preview endpoint.** This endpoint is in preview: its request and response shapes may change without a version increment. A v2 of this API is planned to supersede it, targeting 2026-11.

For a single tool, returns `event_count` and `device_count` per distinct command within the time range, ordered by the optional `metric` parameter (defaults to `event_count`). Each row is annotated with the highest observed severity for that command in the window.
A tool with no command activity in the window returns 200 with an empty results array; this endpoint does not distinguish an unknown tool_id.
Backed by `device_tool_command_hourly` (separate from the launcher-grain table), so per-command totals are computed independently of the per-launcher and per-tool views.
Note: device_count here is per command and remains a distinct count, so the per-command values do not sum to the tool's overall device_count - a device that issued more than one command is counted under each.
The optional, mutually exclusive `min_severity` (floor) and `severity` (exact match) query parameters filter the underlying hourly rows before aggregation, so the returned counts and per-command `severity` reflect only that activity. When both are omitted the filter defaults to 0 (informational), which keeps every row.


**Required Permissions:** `ai-visibility:read`

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Visibility - Preview",
    "version": "0.1.0",
    "description": "Read API for which AI tools run across managed devices, through which launchers, and how often\n\n**Preview:** Every endpoint is in preview: request and response shapes may change without a version increment, and preview endpoints are exempt from the Jamf API deprecation strategy. A v2 of this API is planned to supersede it, targeting 2026-11.",
    "termsOfService": "https://www.jamf.com/developer-resources/api-license-agreement/",
    "contact": {
      "name": "Jamf Developer",
      "url": "https://developer.jamf.com"
    }
  },
  "x-preview": true,
  "servers": [
    {
      "url": "https://{region}.api.jamfcloud.com/ai/governance/visibility",
      "description": "Jamf Beta API Gateway - prod",
      "variables": {
        "region": {
          "default": "us",
          "enum": [
            "us",
            "eu",
            "apac"
          ],
          "description": "Geographic deployment region"
        }
      }
    }
  ],
  "security": [
    {
      "oauth2": []
    }
  ],
  "tags": [
    {
      "name": "tools",
      "description": "AI tools observed running on managed devices, with per-tool launcher and command breakdowns.\n"
    }
  ],
  "paths": {
    "/v1/tools/{tool_id}/commands": {
      "get": {
        "operationId": "getToolCommands",
        "tags": [
          "tools"
        ],
        "summary": "Preview - Per-command breakdown of metrics for one AI tool",
        "description": "**Preview:** _This endpoint is currently in a preview state and is subject to breaking changes without warning._\n\n**Preview endpoint.** This endpoint is in preview: its request and response shapes may change without a version increment. A v2 of this API is planned to supersede it, targeting 2026-11.\n\nFor a single tool, returns `event_count` and `device_count` per distinct command within the time range, ordered by the optional `metric` parameter (defaults to `event_count`). Each row is annotated with the highest observed severity for that command in the window.\nA tool with no command activity in the window returns 200 with an empty results array; this endpoint does not distinguish an unknown tool_id.\nBacked by `device_tool_command_hourly` (separate from the launcher-grain table), so per-command totals are computed independently of the per-launcher and per-tool views.\nNote: device_count here is per command and remains a distinct count, so the per-command values do not sum to the tool's overall device_count - a device that issued more than one command is counted under each.\nThe optional, mutually exclusive `min_severity` (floor) and `severity` (exact match) query parameters filter the underlying hourly rows before aggregation, so the returned counts and per-command `severity` reflect only that activity. When both are omitted the filter defaults to 0 (informational), which keeps every row.\n\n\n**Required Permissions:** `ai-visibility:read`",
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Environment-Id"
          },
          {
            "$ref": "#/components/parameters/ToolId"
          },
          {
            "$ref": "#/components/parameters/Start"
          },
          {
            "$ref": "#/components/parameters/End"
          },
          {
            "$ref": "#/components/parameters/RangeDuration"
          },
          {
            "$ref": "#/components/parameters/Timezone"
          },
          {
            "$ref": "#/components/parameters/OrderMetric"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Order"
          },
          {
            "$ref": "#/components/parameters/MinSeverity"
          },
          {
            "$ref": "#/components/parameters/CommandSeverity"
          }
        ],
        "responses": {
          "200": {
            "headers": {
              "Jamf-Preview": {
                "description": "Always `true`. Marks this as a preview response; the header is removed only if this API leaves preview.\n",
                "required": true,
                "schema": {
                  "type": "boolean",
                  "enum": [
                    true
                  ]
                }
              }
            },
            "description": "Per-command metric values for the tool",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tool_id",
                    "start",
                    "end",
                    "severity",
                    "results"
                  ],
                  "properties": {
                    "tool_id": {
                      "type": "string"
                    },
                    "start": {
                      "$ref": "#/components/schemas/Timestamp"
                    },
                    "end": {
                      "$ref": "#/components/schemas/Timestamp"
                    },
                    "severity": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/SeverityFilter"
                        }
                      ],
                      "description": "The severity filter applied to the underlying hourly rows (echoes the `min_severity` or `severity` query parameter; `op` is \">=\" or \"=\" accordingly, defaulting to `value` 0 with `op` \">=\" when both were omitted).\n"
                    },
                    "results": {
                      "type": "array",
                      "description": "One row per distinct command, ordered by `metric`.",
                      "items": {
                        "$ref": "#/components/schemas/CommandStat"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "oauth2": [
              "ai-visibility:read"
            ]
          }
        ],
        "x-required-privileges": [
          "ai-visibility:read"
        ],
        "x-preview": true
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "Obtain an access token by calling the API Gateway's token endpoint using the OAuth2 client-credentials flow.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{region}.api.jamfcloud.com/auth/token",
            "scopes": {
              "ai-visibility:read": ""
            }
          }
        }
      }
    },
    "parameters": {
      "Start": {
        "name": "start",
        "in": "query",
        "required": false,
        "description": "Absolute inclusive UTC start timestamp (RFC3339). Must be paired with `end`; cannot be combined with `range`.\n",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "examples": {
          "absolute": {
            "value": "2026-05-25T00:00:00Z"
          }
        }
      },
      "End": {
        "name": "end",
        "in": "query",
        "required": false,
        "description": "Absolute exclusive UTC end timestamp (RFC3339). Must be paired with `start`; cannot be combined with `range`.\n",
        "schema": {
          "type": "string",
          "format": "date-time"
        },
        "examples": {
          "absolute": {
            "value": "2026-06-01T00:00:00Z"
          }
        }
      },
      "RangeDuration": {
        "name": "range",
        "in": "query",
        "required": false,
        "description": "Relative look-back duration composed of optional weeks (`w`), days (`d`), and hours (`h`) segments, in that order (e.g. `24h`, `7d`, `1w`, `1w2d3h`). Resolved server-side to `[now-range, now)`. Mutually exclusive with `start`/`end`. Defaults to `24h` when no time parameters are supplied.\n",
        "schema": {
          "type": "string",
          "pattern": "^\\s*(?:\\d+w)?\\s*(?:\\d+d)?\\s*(?:\\d+h)?\\s*$",
          "examples": [
            "24h",
            "7d",
            "1w",
            "1w2d3h"
          ]
        }
      },
      "Timezone": {
        "name": "tz",
        "in": "query",
        "required": false,
        "description": "IANA timezone name (e.g. `America/New_York`, `Europe/Paris`) used to express the resolved range. For the stats endpoints it aligns `day` and `week` bin boundaries to that timezone's local midnight / start-of-week before the window is normalized to UTC for querying. Has no effect on endpoints that do not bucket by time. Defaults to `UTC` when omitted.\n",
        "schema": {
          "type": "string",
          "default": "UTC",
          "examples": [
            "UTC",
            "America/New_York",
            "Europe/Paris",
            "Asia/Kolkata"
          ]
        }
      },
      "ToolId": {
        "name": "tool_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "OrderMetric": {
        "name": "metric",
        "in": "query",
        "required": false,
        "description": "Single metric to order the grouped results by. Allowed values: `event_count`, `device_count`. Defaults to `event_count`. Both metrics are always returned on each row regardless of this value.\n",
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/MetricName"
            }
          ],
          "default": "event_count"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Max number of grouped rows to return (top-N by the ordering metric). Defaults to 50 when omitted.\n",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 50
        }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "1-indexed page number used together with `limit` to page through results. The row offset is computed as `(page - 1) * limit`. Defaults to 1 when omitted. A page past the end of the result set returns an empty list.\n",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "Order": {
        "name": "order",
        "in": "query",
        "required": false,
        "description": "Sort direction for grouped results by the metric.",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "default": "desc"
        }
      },
      "MinSeverity": {
        "name": "min_severity",
        "in": "query",
        "required": false,
        "description": "Keep only command rows whose own severity is at least this value before aggregation (0=informational, 1=low, 2=medium, 3=high). The filter is applied to the underlying hourly rows, so the reported `severity` (MAX over the surviving rows) and the `event_count` / `device_count` totals reflect only activity at or above this level. Mutually exclusive with `severity`.\n",
        "schema": {
          "$ref": "#/components/schemas/Severity"
        }
      },
      "CommandSeverity": {
        "name": "severity",
        "in": "query",
        "required": false,
        "description": "Keep only command rows whose own severity is exactly this value before aggregation (0=informational, 1=low, 2=medium, 3=high). Unlike `min_severity`, this is an equality match rather than a floor. The filter is applied to the underlying hourly rows, so the reported `severity` and the `event_count` / `device_count` totals reflect only activity at exactly this level. Mutually exclusive with `min_severity`.\n",
        "schema": {
          "$ref": "#/components/schemas/Severity"
        }
      },
      "X-Environment-Id": {
        "name": "X-Environment-Id",
        "in": "header",
        "required": true,
        "description": "The environment UUID identifier.",
        "schema": {
          "type": "string",
          "format": "uuid",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
          "example": "e77c1408-10c8-4007-b177-abc9157fbcaa"
        }
      }
    },
    "schemas": {
      "Timestamp": {
        "type": "string",
        "format": "date-time",
        "examples": [
          "2026-05-25T00:00:00Z"
        ]
      },
      "MetricName": {
        "type": "string",
        "description": "event_count = SUM(count); device_count = COUNT(DISTINCT device_id).\n",
        "enum": [
          "event_count",
          "device_count"
        ]
      },
      "EventCount": {
        "type": "integer",
        "format": "int64",
        "minimum": 0,
        "description": "SUM(count) over the range. Additive across groups."
      },
      "DeviceCount": {
        "type": "integer",
        "format": "int64",
        "minimum": 0,
        "description": "COUNT(DISTINCT device_id). NOT additive: do not sum across groups.\n"
      },
      "CommandStat": {
        "type": "object",
        "description": "A per-command row for /v1/tools/{tool_id}/commands, carrying both the event_count and device_count for that command in the window. `severity` is the highest observed severity for that command in the window. When the `severity` filter is supplied, all three values are computed only over the hourly rows at or above that level, so `severity` is the max among the surviving rows rather than the command's true window-wide peak.\n",
        "required": [
          "command_id",
          "severity",
          "event_count",
          "device_count"
        ],
        "properties": {
          "command_id": {
            "type": "string"
          },
          "severity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Severity"
              }
            ],
            "description": "Highest observed severity for the command in the window (restricted to rows at or above the `severity` filter when one is supplied).\n"
          },
          "event_count": {
            "$ref": "#/components/schemas/EventCount"
          },
          "device_count": {
            "$ref": "#/components/schemas/DeviceCount"
          }
        }
      },
      "Severity": {
        "type": "integer",
        "description": "Alert/fact severity level. Mirrors the on-the-wire encoding of the Swift `Severity` enum: 0=informational, 1=low, 2=medium, 3=high.\n",
        "enum": [
          0,
          1,
          2,
          3
        ]
      },
      "SeverityFilter": {
        "type": "object",
        "description": "The resolved severity filter that was applied to the underlying hourly rows before aggregation. It echoes the `min_severity` (floor) or `severity` (exact match) query parameter, carrying both the comparison `value` and the `op` (SQL comparison operator) used against each row's severity.\n",
        "required": [
          "value",
          "op"
        ],
        "properties": {
          "value": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Severity"
              }
            ],
            "description": "The severity value each row's severity is compared against. Defaults to 0 (informational) when no filter was supplied.\n"
          },
          "op": {
            "type": "string",
            "enum": [
              "",
              "=",
              ">="
            ],
            "description": "The comparison operator applied to row severity: \">=\" for a `min_severity` floor, \"=\" for an exact `severity` match, and \"\" (empty) when the resolved filter is not echoed into the response envelope (as on `/v1/commands`).\n"
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 7807 problem details object returned by the API on errors. Served with `Content-Type: application/problem+json`.\n",
        "required": [
          "status",
          "title"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI reference identifying the problem type."
          },
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "examples": [
              400
            ]
          },
          "title": {
            "type": "string",
            "description": "Short, human-readable summary of the problem.",
            "examples": [
              "Bad Request"
            ]
          },
          "detail": {
            "type": "string",
            "description": "Human-readable explanation specific to this occurrence.",
            "examples": [
              "invalid range duration: invalid duration format: \"foo\""
            ]
          },
          "instance": {
            "type": "string",
            "description": "URI reference identifying the specific occurrence (request path).",
            "examples": [
              "/v1/tools"
            ]
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Missing or invalid parameter - e.g. unparseable `start`/`end`/`range`, `range` combined with `start`+`end`, invalid `metric`, out-of-range `limit`/`order`, invalid `bin`/`fill`, an `analytic` UUID or `severity` integer that doesn't parse, or a malformed `cursor`.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed, expired, or otherwise invalid JWT bearer token. Returned by the auth middleware before the handler runs.\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The token is valid but its tenant claim could not be resolved into a usable tenant schema (e.g. the `tenantId` is missing or malformed).\n",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected error querying the backing store.",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      }
    }
  },
  "x-scope-types": [
    "environment"
  ]
}
```