Queries | Docs

Queries

Overview

GraphQL queries are used to read data from the Meter API. Unlike REST, where each endpoint returns a fixed response, a GraphQL query lets you specify exactly which fields you need, and the response matches that shape. This means fewer round-trips and no wasted payload.

Every query listed below accepts typed arguments and returns a typed response. For example, hardwareDevice accepts a serialNumber argument and returns a HardwareDevice with only the fields you select. Arguments marked with ! are required.

activeClients

Active clients are clients that currently appear both in the MAC and ARP tables of one or more networks, as a single series.

activeClients(
  filter: MetricsFilterInput!
  input: ActiveClientsInput
  networkUUID: UUID
  networkUUIDs: [UUID!]
): ActiveClientsMetricsResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Metrics filter to specify time range and interval.
`input`	`ActiveClientsInput`	Additional input options for the query.
`networkUUID`	`UUID`	The UUID of the network. One of `networkUUID` and `networkUUIDs` must be set.
`networkUUIDs`	`[UUID!]`	The UUIDs of the networks. One of `networkUUID` and `networkUUIDs` must be set.

alertReceiver

Get an alert receiver and its targets.

alertReceiver(
  UUID: UUID!
): AlertReceiver!

Argument	Type	Description
`UUID`	`UUID!`	Unique identifier of the alert receiver.

alertReceiversForCompany

Get all alert receivers and their targets for a company.

alertReceiversForCompany(
  companyUUID: UUID!
): [AlertReceiver!]!

Argument	Type	Description
`companyUUID`	`UUID!`	Unique identifier of the company.

allClientMetricsByClient

Timeseries data of data usage metrics for a single client.

allClientMetricsByClient(
  filter: AllClientMetricsTimeseriesFilterInput!
  macAddress: MacAddress!
  networkUUID: UUID!
): AllClientMetricsTimeseriesResponse!

Argument	Type	Description
`filter`	`AllClientMetricsTimeseriesFilterInput!`	Filter to specify time range.
`macAddress`	`MacAddress!`	The MAC address of the client.
`networkUUID`	`UUID!`	The UUID of the network.

allClientMetricsByVLAN

Timeseries data of data usage metrics for clients on a VLAN.

allClientMetricsByVLAN(
  filter: AllClientMetricsTimeseriesFilterInput!
  networkUUID: UUID!
  vlanUUID: UUID!
): AllClientMetricsTimeseriesResponse!

Argument	Type	Description
`filter`	`AllClientMetricsTimeseriesFilterInput!`	Filter to specify time range.
`networkUUID`	`UUID!`	The UUID of the network.
`vlanUUID`	`UUID!`	The UUID of the VLAN to get client metrics.

apHealthScores

Retrieves the latest health metrics for a specified device.

apHealthScores(
  filter: MetricsFilterInput!
  serialNumber: String!
): [AccessPointHealthScores!]!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	The criteria to filter the returned metrics, such as time range and aggregation settings.
`serialNumber`	`String!`	The UUID of the access point whos health scores are being requested.

blockedClientsForNetwork

Returns all currently blocked clients for the given network.

blockedClientsForNetwork(
  networkUUID: UUID!
): [NetworkClientBlocklistEntry!]!

Argument	Type	Description
`networkUUID`	`UUID!`	The network to check for blocked mac addresses

bssidsForNetwork

Return all of the BSSIDs associated with hardware devices linked to virtual devices in a given network.

bssidsForNetwork(
  includeInactive: Boolean
  networkUUID: UUID!
): [BSSID!]!

Argument	Type	Description
`includeInactive`	`Boolean`	Whether or not to include inactive BSSIDs.
`networkUUID`	`UUID!`	The UUID of the network for which to retrieve BSSIDs.

channelUtilizationByAP

Returns one timeseries per radio band for all of the radio bands broadcasted by the AP.

channelUtilizationByAP(
  apVirtualDeviceUUID: UUID!
  band: RadioBand
  filter: ChannelUtilizationTimeseriesFilterInput!
  networkUUID: UUID!
): [ChannelUtilizationResponseV2!]!

Argument	Type	Description
`apVirtualDeviceUUID`	`UUID!`	The UUID of the AP's virtual device to retrieve data for.
`band`	`RadioBand`	Optional filter of the UUID of the radio band for which to retrieve the channel utilization metrics. If not provided, metrics for all bands will be returned.
`filter`	`ChannelUtilizationTimeseriesFilterInput!`	Filtering options for the timeseries data, including time range.
`networkUUID`	`UUID!`	The UUID of the network containing the AP.

channelUtilizationByClient

Returns a timeseries for channel utilization for the client, aggregated over the APs that the client has been connected to.

channelUtilizationByClient(
  filter: ChannelUtilizationTimeseriesFilterInput!
  macAddress: MacAddress!
  networkUUID: UUID!
): [ClientChannelUtilizationTimeseriesValue!]!

Argument	Type	Description
`filter`	`ChannelUtilizationTimeseriesFilterInput!`	Filter to specify bands, channels, SSIDs, and time range.
`macAddress`	`MacAddress!`	The MAC address of the client.
`networkUUID`	`UUID!`	The UUID of the network.

channelUtilizationByNetwork

Returns a time series for each radio band for the APs in the network.

channelUtilizationByNetwork(
  band: RadioBand
  filter: ChannelUtilizationTimeseriesFilterInput!
  networkUUID: UUID!
): [ChannelUtilizationResponseV2!]!

Argument	Type	Description
`band`	`RadioBand`	Optional filter of the UUID of the radio band for which to retrieve the channel utilization metrics. If not provided, metrics for all bands will be returned.
`filter`	`ChannelUtilizationTimeseriesFilterInput!`	Filtering options for the timeseries data, including time range.
`networkUUID`	`UUID!`	The UUID of the network for which to retrieve channel utilization data.

companyBySlug

Get a company by its slug.

companyBySlug(
  slug: String!
): Company!

Argument	Type	Description
`slug`	`String!`	The slug of the company to retrieve.

controllerDNSRequestRates

Timeseries data of requests/sec per DNS server for a single controller.

controllerDNSRequestRates(
  filter: MetricsFilterInput!
  virtualDeviceUUID: UUID!
): ControllerDNSRequestRatesResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Metrics filter specifying time range and other parameters.
`virtualDeviceUUID`	`UUID!`	UUID of the virtual device (controller).

controllerPortMetricsRate

Per port timeseries metrics data as a rate per second for a single controller.

controllerPortMetricsRate(
  filter: MetricsFilterInput!
  portNumber: Int
  virtualDeviceUUID: UUID!
): ControllerPortMetricsRateResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Metrics filter specifying time range and other parameters.
`portNumber`	`Int`	Optional port number to retrieve metrics for. If not provided, metrics for all ports will be returned.
`virtualDeviceUUID`	`UUID!`	UUID of the virtual device (controller).

controllerPortStats

Per port stats for a specified controller over a lookback period. Encompasses receive/transmission data counters and hardware operational status.

controllerPortStats(
  lookbackHours: Int
  portNumber: Int
  virtualDeviceUUID: UUID!
): [ControllerPortStat!]!

Argument	Type	Description
`lookbackHours`	`Int`	Number of hours to look back for stats. Defaults to 24 hours if not specified.
`portNumber`	`Int`	Optional port number to retrieve stats for. If not provided, stats for all ports will be returned.
`virtualDeviceUUID`	`UUID!`	UUID of the virtual device (controller).

encryption8021XsForNetwork

Lists the 802.1X encryption configurations for a specific network.

encryption8021XsForNetwork(
  networkUUID: UUID!
): [Encryption8021X!]!

Argument	Type	Description
`networkUUID`	`UUID!`	The UUID of the network for which to retrieve encryption configurations.

hardwareDevice

Return a hardware device by its serial number.

hardwareDevice(
  serialNumber: String!
): HardwareDevice!

Argument	Type	Description
`serialNumber`	`String!`	The serial number of the hardware device to retrieve.

interVLANCommunicationPermittedPairs

List all links between VLANs that are allowed to communicate with each other.

interVLANCommunicationPermittedPairs(
  networkUUID: UUID!
): [InterVLANCommunicationPermittedPair!]!

Argument	Type	Description
`networkUUID`	`UUID!`	The UUID of the network for which to list the permitted inter-VLAN communication pairs.

network

Get a network.

network(
  UUID: UUID!
): Network!

Argument	Type	Description
`UUID`	`UUID!`	The UUID of the network to retrieve.

networkBySlug

Get a network by its slug.

networkBySlug(
  companySlug: String!
  networkSlug: String!
): Network!

Argument	Type	Description
`companySlug`	`String!`	The slug identifier of the company.
`networkSlug`	`String!`	The slug identifier of the network to retrieve.

networkClients

Get the latest connected clients for a network. The values in filter can alter this behavior.

networkClients(
  filter: NetworkClientsFilter
  networkUUID: UUID!
): [NetworkClient!]!

Argument	Type	Description
`filter`	`NetworkClientsFilter`	Optional filters to apply to the clients query.
`networkUUID`	`UUID!`	The UUID of the network to query clients from.

networkUplinkQuality

Get metrics about uplink quality (i.e., the ISP quality) for one or more networks. Quality is the percentage of successful pings to common web servers over the ISP connection.

networkUplinkQuality(
  filter: MetricsFilterInput!
  networkUUID: UUID
  networkUUIDs: [UUID!]
  phyInterfaceUUID: UUID
  virtualDeviceUUID: UUID
): NetworkUplinkQualityResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	The criteria to filter the returned metrics, such as time range and aggregation settings.
`networkUUID`	`UUID`	The UUID of the network for which to retrieve the uplink quality metrics. One of `networkUUID` and `networkUUIDs` must be set.
`networkUUIDs`	`[UUID!]`	The UUIDs of the networks for which to retrieve the uplink quality metrics. One of `networkUUID` and `networkUUIDs` must be set.
`phyInterfaceUUID`	`UUID`	Optional filter of the UUID of the physical interface for which to retrieve the uplink quality metrics. Cannot specify both phyInterfaceUUID and virtualDeviceUUID.
`virtualDeviceUUID`	`UUID`	Optional filter of the UUID of the controller for which to retrieve the uplink quality metrics. Cannot specify both phyInterfaceUUID and virtualDeviceUUID.

networkUplinkThroughput

Get metrics about uplink throughput (i.e., the ISP throughput) for one or more networks. Throughput is the amount of data transferred over the ISP connection, measured in bits per second.

networkUplinkThroughput(
  filter: MetricsFilterInput!
  networkUUID: UUID
  networkUUIDs: [UUID!]
  phyInterfaceUUID: UUID
  virtualDeviceUUID: UUID
): NetworkUplinkThroughputMetricsResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	The criteria to filter the returned metrics, such as time range and aggregation settings.
`networkUUID`	`UUID`	The UUID of the network for which to retrieve the uplink throughput metrics. One of `networkUUID` and `networkUUIDs` must be set.
`networkUUIDs`	`[UUID!]`	The UUID of the networks for which to retrieve the uplink throughput metrics. One of `networkUUID` and `networkUUIDs` must be set.
`phyInterfaceUUID`	`UUID`	Optional filter of the UUID of the physical interface for which to retrieve the uplink throughput metrics. Cannot specify both phyInterfaceUUID and virtualDeviceUUID.
`virtualDeviceUUID`	`UUID`	Optional filter of the UUID of the controller for which to retrieve the uplink throughput metrics. Cannot specify both phyInterfaceUUID and virtualDeviceUUID.

networksClients

Get the latest connected clients for multiple networks. The values in filter can alter this behavior.

networksClients(
  companyUUID: UUID!
  filter: NetworkClientsFilter
  networkUUIDs: [UUID!]!
): [NetworkClient!]!

Argument	Type	Description
`companyUUID`	`UUID!`	The UUID of the company to query clients from.
`filter`	`NetworkClientsFilter`	Optional filters to apply to the clients query.
`networkUUIDs`	`[UUID!]!`	The UUIDs of the networks to query clients from.

networksForCompany

Get all of a company's networks.

networksForCompany(
  companySlug: String!
  filter: CompanyNetworksFilterInput
): [Network!]!

Argument	Type	Description
`companySlug`	`String!`	The slug identifier of the company.
`filter`	`CompanyNetworksFilterInput`	Filter the networks.

networksUplinkQualities

Get uplink quality metrics for multiple networks.

networksUplinkQualities(
  filter: MetricsFilterInput!
  networkUUIDs: [UUID!]!
): [NetworkUplinkQualityResponse!]!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	The criteria to filter the returned metrics, such as time range and aggregation settings.
`networkUUIDs`	`[UUID!]!`	The list of UUIDs of networks for which to retrieve the uplink quality metrics.

pduMetrics

Timeseries data of PDU device.

pduMetrics(
  filter: MetricsFilterInput!
  virtualDeviceUUID: UUID!
): PDUMetricsTimeseriesResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Filter to specify time range.
`virtualDeviceUUID`	`UUID!`	The UUID of the PDU virtual device.

pdusMetrics

Timeseries data of PDU devices.

pdusMetrics(
  filter: MetricsFilterInput!
  virtualDeviceUUIDs: [UUID!]!
): [PDUMetricsTimeseriesResponse!]!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Filter to specify time range.
`virtualDeviceUUIDs`	`[UUID!]!`	The UUIDs of the PDU virtual devices.

phyInterfacesForVirtualDevice

Get the physical interfaces associated with a virtual device.

phyInterfacesForVirtualDevice(
  virtualDeviceUUID: UUID!
): [PhyInterface!]!

Argument	Type	Description
`virtualDeviceUUID`	`UUID!`	The UUID of the virtual device whose physical interfaces are being requested.

recentEventLogEventsPage

A page of events in the event log that includes the total number of records.

recentEventLogEventsPage(
  endTime: DateTime
  limit: Int!
  networkUUID: UUID!
  offset: Int
  startTime: DateTime
  typeFilter: [EventType!]
  virtualDeviceUUIDFilter: [UUID!]
): EventLogEventsPage!

Argument	Type	Description
`endTime`	`DateTime`	Fetch events generated before this time.
`limit`	`Int!`	The maximum number of events to return.
`networkUUID`	`UUID!`	The UUID of the network to fetch events for.
`offset`	`Int`	The number of events to skip before starting to collect the result set.
`startTime`	`DateTime`	Fetch events generated after this time.
`typeFilter`	`[EventType!]`	Filter to match on event type.
`virtualDeviceUUIDFilter`	`[UUID!]`	Filter to match on virtual device UUID.

spareHardwareDevicesForNetwork

Return the hardware devices that are not associated with a virtual device; they're not in use but affiliated with the network for potential future use.

spareHardwareDevicesForNetwork(
  filter: HardwareDevicesFilter
  networkUUID: UUID!
): [HardwareDevice!]!

Argument	Type	Description
`filter`	`HardwareDevicesFilter`	Filter criteria to apply when retrieving spare hardware devices.
`networkUUID`	`UUID!`	The UUID of the network to retrieve spare hardware devices for.

ssid

Get an SSID

ssid(
  UUID: UUID!
): SSID!

Argument	Type	Description
`UUID`	`UUID!`	UUID of SSID.

ssidsForNetwork

List all SSIDs for a network.

ssidsForNetwork(
  filter: SSIDFilterInput
  networkUUID: UUID!
): [SSID!]!

Argument	Type	Description
`filter`	`SSIDFilterInput`	Optional filters for the SSIDs.
`networkUUID`	`UUID!`	UUID of the network to fetch the SSIDs from.

switchMACTable

Retrieve the MAC address table for a specified switch. The MAC table contains all MAC addresses observed on the switch's ports.

switchMACTable(
  virtualDeviceUUID: UUID!
): [SwitchMACTableEntry!]!

Argument	Type	Description
`virtualDeviceUUID`	`UUID!`	The unique identifier of the virtual device representing the switch.

switchPortMetricsRate

Retrieve per-port timeseries metrics data expressed as rates (per second) for a specified switch.

switchPortMetricsRate(
  filter: MetricsFilterInput!
  portNumber: Int
  virtualDeviceUUID: UUID!
): SwitchPortMetricsRateResponse!

Argument	Type	Description
`filter`	`MetricsFilterInput!`	Filter parameters specifying time range and resolution.
`portNumber`	`Int`	Optional port number to retrieve metrics for. If not provided, metrics for all ports will be returned.
`virtualDeviceUUID`	`UUID!`	The unique identifier of the virtual device representing the switch.

switchPortStats

Retrieve aggregated per-port statistics for a specified switch over a given lookback period.

switchPortStats(
  lookbackHours: Int
  portNumber: Int
  virtualDeviceUUID: UUID!
): [SwitchPortStat!]!

Argument	Type	Description
`lookbackHours`	`Int`	The number of hours to look back for stats aggregation. Defaults to 24 hours if not specified.
`portNumber`	`Int`	Optional port number to retrieve stats for. If not provided, stats for all ports will be returned.
`virtualDeviceUUID`	`UUID!`	The unique identifier of the virtual device representing the switch.

uplinkPhyInterfacesForNetwork

Returns network uplink (WAN) physical interfaces for the network (controller interfaces only).

uplinkPhyInterfacesForNetwork(
  networkUUID: UUID!
): [PhyInterface!]!

Argument	Type	Description
`networkUUID`	`UUID!`	The UUID of the network to retrieve uplink physical interfaces for.

virtualDevice

Return a virtual device by its UUID.

virtualDevice(
  UUID: UUID!
): VirtualDevice!

Argument	Type	Description
`UUID`	`UUID!`	The UUID of the virtual device to retrieve.

virtualDevicesForNetwork

Return a list of virtual devices for a network that match the given filter.

virtualDevicesForNetwork(
  filter: DevicesForNetworkFilter
  networkUUID: UUID!
): [VirtualDevice!]!

Argument	Type	Description
`filter`	`DevicesForNetworkFilter`	Filter criteria to apply when retrieving virtual devices.
`networkUUID`	`UUID!`	The UUID of the network to retrieve virtual devices for.

vlan

Get a VLAN by UUID.

vlan(
  UUID: UUID!
): VLAN!

Argument	Type	Description
`UUID`	`UUID!`	The UUID of the VLAN to retrieve.

vlans

Get all VLANs for a network.

vlans(
  networkUUID: UUID!
): [VLAN!]!

Argument	Type	Description
`networkUUID`	`UUID!`	The UUID of the network for which to retrieve VLANs.

wirelessClientMetrics

Timeseries data of wireless connectivity metrics for all clients on a network. Returns an aggregated timeseries for each client.

wirelessClientMetrics(
  filter: ClientMetricsTimeseriesFilterInput!
  networkUUID: UUID!
): [WirelessClientMetricsResponse!]!

Argument	Type	Description
`filter`	`ClientMetricsTimeseriesFilterInput!`	Filter to specify bands, channels, SSIDs, and time range.
`networkUUID`	`UUID!`	The UUID of the network.

wirelessClientMetricsByAP

Timeseries data of wireless connectivity metrics for all clients connected to an AP. Returns a single aggregated timeseries, rather than one per client.

wirelessClientMetricsByAP(
  apVirtualDeviceUUID: UUID!
  filter: ClientMetricsTimeseriesFilterInput!
  networkUUID: UUID!
): ClientMetricsTimeseriesResponse!

Argument	Type	Description
`apVirtualDeviceUUID`	`UUID!`	The UUID of the AP virtual device.
`filter`	`ClientMetricsTimeseriesFilterInput!`	Filter to specify bands, channels, SSIDs, and time range.
`networkUUID`	`UUID!`	The UUID of the network.

wirelessClientMetricsByClient

Timeseries data of wireless connectivity metrics for a single client.

wirelessClientMetricsByClient(
  filter: ClientMetricsTimeseriesFilterInput!
  macAddress: MacAddress!
  networkUUID: UUID!
): ClientMetricsTimeseriesResponse!

Argument	Type	Description
`filter`	`ClientMetricsTimeseriesFilterInput!`	Filter to specify bands, channels, SSIDs, and time range.
`macAddress`	`MacAddress!`	The MAC address of the client.
`networkUUID`	`UUID!`	The UUID of the network.

Need help?

If you run into any issues or have questions, please reach out to our Support Engineering team by opening a ticket via the Dashboard: https://dashboard.meter.com/support

Was this helpful?

PreviousInput types NextScalars