---
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 - Count distinct launchers active for one tool within a time range

**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 the number of distinct launchers that recorded any activity within the time range. The count is derived from `device_tool_launcher_hourly` filtered to `tool_id` and is a distinct count over the window (not additive across sub-ranges).
A tool with no launcher activity in the window returns 200 with a count of 0; this endpoint does not distinguish an unknown tool_id.


**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}/launchers/count": {
      "get": {
        "operationId": "countToolLaunchers",
        "tags": [
          "tools"
        ],
        "summary": "Preview - Count distinct launchers active for one tool within a time range",
        "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 the number of distinct launchers that recorded any activity within the time range. The count is derived from `device_tool_launcher_hourly` filtered to `tool_id` and is a distinct count over the window (not additive across sub-ranges).\nA tool with no launcher activity in the window returns 200 with a count of 0; this endpoint does not distinguish an unknown tool_id.\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"
          }
        ],
        "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": "Distinct launcher count for the tool over the time range",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tool_id",
                    "start",
                    "end",
                    "launcher_count"
                  ],
                  "properties": {
                    "tool_id": {
                      "type": "string"
                    },
                    "start": {
                      "$ref": "#/components/schemas/Timestamp"
                    },
                    "end": {
                      "$ref": "#/components/schemas/Timestamp"
                    },
                    "launcher_count": {
                      "type": "integer",
                      "format": "int64",
                      "minimum": 0,
                      "description": "COUNT(DISTINCT launcher_id) for the tool over the range."
                    }
                  }
                }
              }
            }
          },
          "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"
        }
      },
      "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"
        ]
      },
      "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"
  ]
}
```