Insights is a feature that provides an overview of network experience across the entire site, access points, or clients. It offers useful information about current conditions, such as telemetry data from wired switches, edge devices, wireless clients, access points, network applications, and bluetooth low energy (ble) tags. These insights can be used to correct issues, make changes, and ensure a good network experience for users.
openapi: 3.1.0
info:
contact:
email: tmunzer@juniper.net
name: Thomas Munzer
description: '> Version: **2606.1.1**
>
> Date: **July 10, 2026**
<div class="notification"> NOTE:<br>Some important API changes will be introduced. Please make sure to read the <a href="https://www.juniper.net/documentation/us/en/software/mist/api/http/guides/important-api-changes">announcements</a> </div>
---
## Additional Documentation
* [Mist Automation Guide](https://www.juniper.net/documentation/us/en/software/mist/automation-integration/index.html)
* [Mist Location SDK](https://www.juniper.net/documentation/us/en/software/mist/location-services/topics/concept/mist-how-get-mist-sdk.html)
* [Mist Product Updates](https://www.juniper.net/documentation/us/en/software/mist/product-updates/)
## Helpful Resources
* [API Sandbox and Exercises](https://api-class.mist.com/)
* [Postman Collection, Runners and Webhook Samples](https://www.postman.com/juniper-mist/workspace/mist-systems-s-public-workspace)
* [Python Script Examples](https://github.com/tmunzer/mist_library)
* [API Demo Apps](https://apps.mist-lab.fr/)
* [Juniper Blog](https://blogs.juniper.net/)
## Mist Web Browser Extension:
* Google Chrome, Microsoft Edge and other Chromium-based browser: [Chrome Web Store](https://chromewebstore.google.com/detail/mist-extension/ejhpdcljeamillfhdihkkmoakanpbplh)
* Firefox: [Firefox Add-ons](https://addons.mozilla.org/en-US/firefox/addon/mist-extension/)
---'
license:
name: MIT
url: https://raw.githubusercontent.com/tmunzer/Mist-OAS3.0/main/LICENSE
title: Mist Admins Sites Insights API
version: 2606.1.1
x-logo:
altText: Juniper-MistAI
backgroundColor: '#FFFFFF'
url: https://www.mist.com/wp-content/uploads/logo.png
servers:
- description: Mist Global 01
url: https://api.mist.com
- description: Mist Global 02
url: https://api.gc1.mist.com
- description: Mist Global 03
url: https://api.ac2.mist.com
- description: Mist Global 04
url: https://api.gc2.mist.com
- description: Mist Global 05
url: https://api.gc4.mist.com
- description: Mist EMEA 01
url: https://api.eu.mist.com
- description: Mist EMEA 02
url: https://api.gc3.mist.com
- description: Mist EMEA 03
url: https://api.ac6.mist.com
- description: Mist EMEA 04
url: https://api.gc6.mist.com
- description: Mist APAC 01
url: https://api.ac5.mist.com
- description: Mist APAC 02
url: https://api.gc5.mist.com
- description: Mist APAC 03
url: https://api.gc7.mist.com
security:
- apiToken: []
- csrfToken: []
tags:
- description: 'Insights is a feature that provides an overview of network experience across the entire site, access points, or clients.
It offers useful information about current conditions, such as telemetry data from wired switches, edge devices, wireless clients, access points, network applications, and bluetooth low energy (ble) tags.
These insights can be used to correct issues, make changes, and ensure a good network experience for users.'
name: Sites Insights
paths:
/api/v1/sites/{site_id}/insights:
parameters:
- $ref: '#/components/parameters/site_id'
get:
description: Get Site Insight Metrics
operationId: getSiteInsightMetrics
parameters:
- description: Comma separated Metric names, e.g. `num_clients,num_aps`. See possible values at [List Insight Metrics](/#operations/listInsightMetrics)
in: query
name: metrics
required: true
schema:
examples:
- num_clients,num_aps
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/InsightMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetrics
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/ap/{device_id}/stats:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/device_id'
get:
description: Get AP Insight Metrics
operationId: getSiteInsightMetricsForAP
parameters:
- description: Comma separated Metric names, e.g. `num_clients,num_stressed_clients`. See possible values at [List Insight Metrics](/#operations/listInsightMetrics)
in: query
name: metrics
required: true
schema:
examples:
- num_clients,num_stressed_clients
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/DeviceMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForAP
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/client/{client_mac}:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/client_mac'
get:
description: Get Client Insight Metrics
operationId: getSiteInsightMetricsForClient
parameters:
- description: Comma separated Metric names, e.g. `top-app-by-num_client,top-app-by-bytes`. See possible values at [List Insight Metrics](/#operations/listInsightMetrics)
in: query
name: metrics
required: true
schema:
examples:
- top-app-by-num_client,top-app-by-bytes
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/InsightMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForClient
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/device/{device_mac}/{metric}:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/metric'
- $ref: '#/components/parameters/device_mac'
get:
description: 'Get AP Insight Metrics
See metrics possibilities at [List Insight Metrics](/#operations/listInsightMetrics)'
operationId: getSiteInsightMetricsForDevice
parameters:
- description: Port ID of the device, e.g. `ge-0/0/1`. Can be used with metrics related to interfaces, e.g. `rx_bytes`.
in: query
name: port_id
schema:
examples:
- ge-0/0/1
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/DeviceMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForDevice
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/gateway/{device_id}/stats:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/device_id'
get:
description: Get Gateway Insight Metrics
operationId: getSiteInsightMetricsForGateway
parameters:
- description: Comma separated Metric names, e.g. `tx_bps,rx_bps`. See possible values at [List Insight Metrics](/#operations/listInsightMetrics)
in: query
name: metrics
required: true
schema:
examples:
- tx_bps,rx_bps
type: string
- description: Port ID of the gateway device, e.g. `ge-0/0/1`
in: query
name: port_id
schema:
examples:
- ge-0/0/1
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/DeviceMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForGateway
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/mxedge/{device_mac}/{metric}:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/metric'
- $ref: '#/components/parameters/device_mac'
get:
description: 'Get MxEdge Insight Metrics
See metrics possibilities at [List Insight Metrics](/#operations/listInsightMetrics)'
operationId: getSiteInsightMetricsForMxEdge
parameters:
- description: Port ID of the MxEdge device, e.g. `port0`. Can be used with metrics related to interfaces, e.g. `rx_bytes`.
in: query
name: port_id
schema:
examples:
- port0
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/DeviceMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForMxEdge
tags:
- Sites Insights
/api/v1/sites/{site_id}/insights/switch/{device_mac}/{metric}:
parameters:
- $ref: '#/components/parameters/site_id'
- $ref: '#/components/parameters/metric'
- $ref: '#/components/parameters/device_mac'
get:
description: 'Get Switch Insight Metrics
See metrics possibilities at [List Insight Metrics](/#operations/listInsightMetrics)'
operationId: getSiteInsightMetricsForSwitch
parameters:
- description: Port ID of the switch device, e.g. `ge-0/0/1`. Can be used with metrics related to interfaces, e.g. `rx_bytes`.
in: query
name: port_id
schema:
examples:
- ge-0/0/1
type: string
- $ref: '#/components/parameters/start'
- $ref: '#/components/parameters/end'
- $ref: '#/components/parameters/duration'
- $ref: '#/components/parameters/interval'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
responses:
'200':
$ref: '#/components/responses/DeviceMetric'
'400':
$ref: '#/components/responses/HTTP400'
'401':
$ref: '#/components/responses/HTTP401'
'403':
$ref: '#/components/responses/HTTP403'
'404':
$ref: '#/components/responses/HTTP404'
'429':
$ref: '#/components/responses/HTTP429'
summary: getSiteInsightMetricsForSwitch
tags:
- Sites Insights
components:
schemas:
response_device_metrics_results_items:
description: Device metric result value, returned as a string or integer
oneOf:
- type: string
- type: integer
strings:
description: Unique string values returned or accepted by this schema
items:
type: string
type: array
uniqueItems: true
response_http429:
additionalProperties: false
description: Standard HTTP 429 rate limit error response
properties:
detail:
description: Human-readable explanation of the rate limit error
examples:
- Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
type: string
type: object
response_http401:
additionalProperties: false
description: Standard HTTP 401 authentication error response
properties:
detail:
description: Human-readable explanation of the authentication error
examples:
- Authentication credentials were not provided.
type: string
type: object
response_device_metrics:
additionalProperties: false
description: Time-series insight metric response for a device
properties:
end:
description: Epoch timestamp for the end of the metric query window
type: integer
interval:
description: Aggregation interval in seconds for each metric sample
type: integer
limit:
description: Maximum number of metric samples returned in this page
type: integer
page:
description: Returned page number for paginated metric samples
type: integer
results:
$ref: '#/components/schemas/response_device_metrics_results'
description: Metric values for the requested insight metric, aligned by position with the `rt` timestamps
rt:
$ref: '#/components/schemas/strings'
description: Timestamps for the metric samples, aligned by position with the `results` values
start:
description: Epoch timestamp for the start of the metric query window
type: integer
required:
- end
- interval
- results
- start
type: object
insight_metrics_results:
description: Results depends on the `metric` - some return numbers (e.g. bytes, ap-count), others return objects
items:
$ref: '#/components/schemas/insight_metrics_results_item'
type: array
uniqueItems: true
response_http403:
additionalProperties: false
description: Standard HTTP 403 permission error response
properties:
detail:
description: Human-readable explanation of the permission error
examples:
- You do not have permission to perform this action.
type: string
type: object
response_device_metrics_results:
description: Device metric result values aligned with the response timestamps
items:
$ref: '#/components/schemas/response_device_metrics_results_items'
type: array
response_http400:
additionalProperties: false
description: Standard HTTP 400 bad request error response
properties:
detail:
description: Human-readable explanation of the bad request error
examples:
- 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
type: string
type: object
insight_metrics_results_item:
anyOf:
- type: number
- additionalProperties: true
type: object
description: Insight metric result item, returned either as a number or an object depending on the requested metric
insight_metrics:
additionalProperties: false
description: Insight metric response for a requested time range and aggregation interval
properties:
end:
description: Window end timestamp for the returned insight metrics
type: integer
interval:
description: Aggregation interval used for the metric results
type: integer
limit:
description: Maximum number of insight metric result items returned
type: integer
results:
$ref: '#/components/schemas/insight_metrics_results'
description: Metric result values for the requested insight metric
start:
description: Window start timestamp for the returned insight metrics
type: integer
required:
- end
- interval
- start
type: object
response_http404:
additionalProperties: false
description: Standard HTTP 404 not found error response
properties:
id:
description: Missing resource identifier, when the API includes one
type: string
type: object
parameters:
client_mac:
in: path
name: client_mac
required: true
schema:
examples:
- 0000000000ab
pattern: ^[0-9a-fA-F]{12}$
type: string
start:
description: Lower bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d` or `-1w`
in: query
name: start
schema:
type: string
duration:
description: Time range duration for the query, using relative units such as `10m`, `7d`, or `2w`
in: query
name: duration
schema:
default: 1d
examples:
- 10m
type: string
limit:
description: Maximum number of results to return per page
in: query
name: limit
schema:
default: 100
minimum: 0
type: integer
device_id:
in: path
name: device_id
required: true
schema:
examples:
- 000000ab-00ab-00ab-00ab-0000000000ab
format: uuid
type: string
page:
description: Select the page number to return when using page-based pagination; starts at `1`
in: query
name: page
schema:
default: 1
minimum: 1
type: integer
device_mac:
in: path
name: device_mac
required: true
schema:
examples:
- 0000000000ab
pattern: ^[0-9a-fA-F]{12}$
type: string
site_id:
in: path
name: site_id
required: true
schema:
examples:
- 000000ab-00ab-00ab-00ab-0000000000ab
format: uuid
type: string
end:
description: Upper bound of the time range, as an epoch timestamp in seconds or a relative value such as `-1d`, `-2h`, or `now`
in: query
name: end
schema:
type: string
interval:
description: Aggregation works by giving a time range plus interval (e.g. 1d, 1h, 10m) where aggregation function would be applied to.
in: query
name: interval
schema:
examples:
- 10m
type: string
metric:
description: See [List Insight Metrics](/#operations/listInsightMetrics) for available metrics
in: path
name: metric
required: true
schema:
type: string
examples:
DeviceMetricExample:
value:
end: 1604347200
interval: 3600
limit: 168
page: 1
results:
- 10
- 11
- 12
- 12
- 10
- 9
- 9
- 9
- 10
- 10
- 11
- 11
- 11
- 11
- 11
- 11
- 11
- 10
- 11
- 11
- 10
- 11
- 11
- 10
rt:
- '2020-11-01 20:00:00+00:00'
- '2020-11-01 21:00:00+00:00'
- '2020-11-01 22:00:00+00:00'
- '2020-11-01 23:00:00+00:00'
- '2020-11-02 00:00:00+00:00'
- '2020-11-02 01:00:00+00:00'
- '2020-11-02 02:00:00+00:00'
- '2020-11-02 03:00:00+00:00'
- '2020-11-02 04:00:00+00:00'
- '2020-11-02 05:00:00+00:00'
- '2020-11-02 06:00:00+00:00'
- '2020-11-02 07:00:00+00:00'
- '2020-11-02 08:00:00+00:00'
- '2020-11-02 09:00:00+00:00'
- '2020-11-02 10:00:00+00:00'
- '2020-11-02 11:00:00+00:00'
- '2020-11-02 12:00:00+00:00'
- '2020-11-02 13:00:00+00:00'
- '2020-11-02 14:00:00+00:00'
- '2020-11-02 15:00:00+00:00'
- '2020-11-02 16:00:00+00:00'
- '2020-11-02 17:00:00+00:00'
- '2020-11-02 18:00:00+00:00'
- '2020-11-02 19:00:00+00:00'
start: 1604260800
InsightMetricExample:
value:
end: 0
interval: 0
results:
- {}
start: 0
HTTP403Example:
value:
detail: You do not have permission to perform this action.
HTTP400Example:
value:
detail: 'JSON parse error - Expecting value: line 5 column 8 (char 56)'
HTTP429Example:
value:
detail: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
HTTP401Example:
value:
detail: Authentication credentials were not provided.
responses:
HTTP400:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/HTTP400Example'
schema:
$ref: '#/components/schemas/response_http400'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/HTTP400Example'
schema:
$ref: '#/components/schemas/response_http400'
description: Bad Syntax
HTTP403:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/HTTP403Example'
schema:
$ref: '#/components/schemas/response_http403'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/HTTP403Example'
schema:
$ref: '#/components/schemas/response_http403'
description: Permission Denied
DeviceMetric:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/DeviceMetricExample'
schema:
$ref: '#/components/schemas/response_device_metrics'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/DeviceMetricExample'
schema:
$ref: '#/components/schemas/response_device_metrics'
description: OK
InsightMetric:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/InsightMetricExample'
schema:
$ref: '#/components/schemas/insight_metrics'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/InsightMetricExample'
schema:
$ref: '#/components/schemas/insight_metrics'
description: OK
HTTP404:
content:
application/json:
schema:
$ref: '#/components/schemas/response_http404'
application/vnd.api+json:
schema:
$ref: '#/components/schemas/response_http404'
description: Not found. The API endpoint doesn’t exist or resource doesn’ t exist
HTTP429:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/HTTP429Example'
schema:
$ref: '#/components/schemas/response_http429'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/HTTP429Example'
schema:
$ref: '#/components/schemas/response_http429'
description: Too Many Request. The API Token used for the request reached the 5000 API Calls per hour threshold
HTTP401:
content:
application/json:
examples:
Example:
$ref: '#/components/examples/HTTP401Example'
schema:
$ref: '#/components/schemas/response_http401'
application/vnd.api+json:
examples:
Example:
$ref: '#/components/examples/HTTP401Example'
schema:
$ref: '#/components/schemas/response_http401'
description: Unauthorized
securitySchemes:
apiToken:
description: "Preferred authentication method for automation and integrations. Send the API token in the HTTP `Authorization` header.\n\n**Format**:\n `Authorization: Token {apitoken}`\n\n**Notes**:\n* An API token generated for a specific admin has the same privileges as that admin\n* An API token is automatically removed if it is not used for more than 90 days\n* SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed."
in: header
name: Authorization
type: apiKey
csrfToken:
description: 'Session-based authentication for browser or login/password flows. After a successful [Login](/#operations/login) request, Mist returns a `csrftoken` cookie. Send that value in the `X-CSRFToken` header on later API requests that use the login session.
**Format**:
```
X-CSRFToken: vwvBuq9qkqaKh7lu8tNc0gkvBfEaLAmx
```
For automation, API Token authentication is preferred.'
in: header
name: X-CSRFToken
type: apiKey