{"type":"api","title":"Get Organization Switch Ports Usage By Device By Interval","meta":{"id":"/apps/pubhub/media/Meraki-Dashboard-API-v1-Documentation/e92a64d0814b40091de22f4a93378df69809b95e/401c6d5b-0873-3519-be2b-c203501ad95c","info":{"title":"Meraki Dashboard API","description":"A RESTful API to programmatically manage and monitor Cisco Meraki networks at scale.\n\n\u003e Date: 20 November, 2024\n\u003e\n\u003e [Recent Updates](https://meraki.io/whats-new/)\n\n---\n\n[API Documentation](https://meraki.io/api)\n\n[Community Support](https://meraki.io/community)\n\n[Meraki Homepage](https://www.meraki.com)\n","contact":{"name":"Meraki Developer Community","url":"https://meraki.io/community"},"version":"1.52.0-beta.2"},"security":[{"meraki_api_key":[]},{"bearerAuth":[]}],"tags":[{"name":"organizations"},{"name":"networks"},{"name":"devices"},{"name":"insight"},{"name":"wireless"},{"name":"camera"},{"name":"appliance"},{"name":"switch"},{"name":"cellularGateway"},{"name":"sm"},{"name":"sensor"},{"name":"administered"},{"name":"wirelessController"},{"name":"accessControlLists"},{"name":"accessPolicies"},{"name":"accounts"},{"name":"aclHitCount"},{"name":"acls"},{"name":"actionBatches"},{"name":"activities"},{"name":"adaptivePolicy"},{"name":"addresses"},{"name":"admins"},{"name":"afc"},{"name":"airMarshal"},{"name":"alertTypes"},{"name":"alerts"},{"name":"alternateManagementInterface"},{"name":"analytics"},{"name":"api"},{"name":"apiRequests"},{"name":"apnsCert"},{"name":"apple"},{"name":"appliances"},{"name":"applicationCategories"},{"name":"applicationUsage"},{"name":"applications"},{"name":"areas"},{"name":"arpInspection"},{"name":"arpTable"},{"name":"artifacts"},{"name":"assets"},{"name":"assignments"},{"name":"auth"},{"name":"authenticationToken"},{"name":"autoLocate"},{"name":"autoRf"},{"name":"automations"},{"name":"availabilities"},{"name":"bandwidthUsageHistory"},{"name":"bgp"},{"name":"billing"},{"name":"blink"},{"name":"bluetooth"},{"name":"bluetoothClients"},{"name":"bonjourForwarding"},{"name":"boots"},{"name":"boundaries"},{"name":"brandingPolicies"},{"name":"bulk"},{"name":"bulkCreate"},{"name":"bulkDelete"},{"name":"bulkEnrollment"},{"name":"bulkUpdate"},{"name":"byBoundary"},{"name":"byClient"},{"name":"byDevice"},{"name":"byEnergyUsage"},{"name":"byInterval"},{"name":"byMetric"},{"name":"byModel"},{"name":"byNetwork"},{"name":"byStack"},{"name":"byStatus"},{"name":"bySwitch"},{"name":"bySwitchProfile"},{"name":"byType"},{"name":"byUsage"},{"name":"byUtilization"},{"name":"bypassActivationLockAttempts"},{"name":"cableTest"},{"name":"callbacks"},{"name":"captures"},{"name":"categories"},{"name":"cellular"},{"name":"cellularFirewallRules"},{"name":"cellularUsageHistory"},{"name":"certificates"},{"name":"certs"},{"name":"changeHistory"},{"name":"channelUtilization"},{"name":"channelUtilizationHistory"},{"name":"channels"},{"name":"claim"},{"name":"claimKey"},{"name":"clientCountHistory"},{"name":"clients"},{"name":"cloud"},{"name":"cloudEnrollment"},{"name":"cloudMonitoring"},{"name":"commands"},{"name":"communicationPlans"},{"name":"compliance"},{"name":"configTemplates"},{"name":"configurationChanges"},{"name":"configure"},{"name":"configuredDevices"},{"name":"connectionStats"},{"name":"connections"},{"name":"connectivity"},{"name":"connectivityEvents"},{"name":"connectivityMonitoringDestinations"},{"name":"contentFiltering"},{"name":"contents"},{"name":"coterm"},{"name":"current"},{"name":"customAnalytics"},{"name":"customPerformanceClasses"},{"name":"cyclePort"},{"name":"dataRateHistory"},{"name":"delegated"},{"name":"deltas"},{"name":"desktopLogs"},{"name":"details"},{"name":"detections"},{"name":"deviceCertificateAuthorities"},{"name":"deviceCommandLogs"},{"name":"deviceProfiles"},{"name":"deviceTypeGroupPolicies"},{"name":"dhcp"},{"name":"dhcpServerPolicy"},{"name":"discovery"},{"name":"disenrollments"},{"name":"dns"},{"name":"doorLocks"},{"name":"download"},{"name":"dscpTaggingOptions"},{"name":"dscpToCosMappings"},{"name":"eapOverride"},{"name":"earlyAccess"},{"name":"electronicShelfLabel"},{"name":"enrollments"},{"name":"entitlements"},{"name":"esims"},{"name":"ethernet"},{"name":"eventTypes"},{"name":"events"},{"name":"exportEvents"},{"name":"extensions"},{"name":"failedConnections"},{"name":"failover"},{"name":"features"},{"name":"fields"},{"name":"firewall"},{"name":"firewalledServices"},{"name":"firmware"},{"name":"firmwareUpgrades"},{"name":"floorPlans"},{"name":"groupPolicies"},{"name":"groups"},{"name":"health"},{"name":"healthByTime"},{"name":"healthScores"},{"name":"historical"},{"name":"history"},{"name":"hotspot20"},{"name":"httpServers"},{"name":"identities"},{"name":"identityPsks"},{"name":"idps"},{"name":"import"},{"name":"imports"},{"name":"inboundCellularFirewallRules"},{"name":"inboundFirewallRules"},{"name":"integration"},{"name":"interfaces"},{"name":"internetPolicies"},{"name":"intrusion"},{"name":"inventory"},{"name":"ipv6"},{"name":"jobs"},{"name":"keys"},{"name":"l2"},{"name":"l3"},{"name":"l3FirewallRules"},{"name":"l7FirewallRules"},{"name":"lan"},{"name":"latencyHistory"},{"name":"latencyStats"},{"name":"latest"},{"name":"leds"},{"name":"license"},{"name":"licenses"},{"name":"licensing"},{"name":"lines"},{"name":"linkAggregations"},{"name":"linkLayer"},{"name":"live"},{"name":"liveTools"},{"name":"lldpCdp"},{"name":"local"},{"name":"locationScanning"},{"name":"loginSecurity"},{"name":"logs"},{"name":"lossAndLatencyHistory"},{"name":"macTable"},{"name":"malware"},{"name":"managementInterface"},{"name":"manufacturers"},{"name":"me"},{"name":"merakiAuthUsers"},{"name":"meshStatuses"},{"name":"mirror"},{"name":"mirrors"},{"name":"models"},{"name":"monitor"},{"name":"monitoredMediaServers"},{"name":"mqttBrokers"},{"name":"mtu"},{"name":"multicast"},{"name":"multicastForwarding"},{"name":"netflow"},{"name":"networkAdapters"},{"name":"networkHealth"},{"name":"objectDetectionModels"},{"name":"onboarding"},{"name":"onboardingHistory"},{"name":"oneToManyNatRules"},{"name":"oneToOneNatRules"},{"name":"openapiSpec"},{"name":"opportunisticPcap"},{"name":"optIns"},{"name":"order"},{"name":"ospf"},{"name":"overview"},{"name":"packetCapture"},{"name":"packetLoss"},{"name":"packets"},{"name":"payloadTemplates"},{"name":"performance"},{"name":"performanceHistory"},{"name":"permissions"},{"name":"pii"},{"name":"piiKeys"},{"name":"ping"},{"name":"pingDevice"},{"name":"planning"},{"name":"policies"},{"name":"policy"},{"name":"policyObjects"},{"name":"portForwardingRules"},{"name":"portSchedules"},{"name":"ports"},{"name":"position"},{"name":"power"},{"name":"powerLimits"},{"name":"powerModules"},{"name":"prefixes"},{"name":"prepare"},{"name":"priorities"},{"name":"privateApplicationGroups"},{"name":"privateApplications"},{"name":"profiles"},{"name":"provisioning"},{"name":"publicApplications"},{"name":"qosRules"},{"name":"qualityAndRetention"},{"name":"qualityRetentionProfiles"},{"name":"radSec"},{"name":"radio"},{"name":"radius"},{"name":"ratePlans"},{"name":"readings"},{"name":"recent"},{"name":"records"},{"name":"redundancy"},{"name":"regions"},{"name":"relationships"},{"name":"remoteAccessLog"},{"name":"remoteAccessLogsExports"},{"name":"remove"},{"name":"rendezvousPoints"},{"name":"requests"},{"name":"requirements"},{"name":"responseCodes"},{"name":"restrictions"},{"name":"revocationList"},{"name":"rfProfiles"},{"name":"roles"},{"name":"rollbacks"},{"name":"routing"},{"name":"routingTable"},{"name":"rules"},{"name":"salesRepresentatives"},{"name":"saml"},{"name":"samlRoles"},{"name":"schedules"},{"name":"sdwan"},{"name":"search"},{"name":"secureConnect"},{"name":"security"},{"name":"securityCenters"},{"name":"seen"},{"name":"sense"},{"name":"sentry"},{"name":"servers"},{"name":"serviceProviders"},{"name":"settings"},{"name":"signalQualityHistory"},{"name":"sims"},{"name":"singleLan"},{"name":"siteToSiteVpn"},{"name":"sites"},{"name":"smDevicesForKey"},{"name":"smOwnersForKey"},{"name":"snmp"},{"name":"softwares"},{"name":"spaces"},{"name":"speedTest"},{"name":"speedTestResults"},{"name":"splash"},{"name":"splashAuthorizationStatus"},{"name":"splashLoginAttempts"},{"name":"split"},{"name":"ssids"},{"name":"stacks"},{"name":"staged"},{"name":"stages"},{"name":"staticRoutes"},{"name":"statics"},{"name":"stats"},{"name":"status"},{"name":"statuses"},{"name":"stormControl"},{"name":"stp"},{"name":"subnetPool"},{"name":"subnets"},{"name":"subscription"},{"name":"subscriptions"},{"name":"summary"},{"name":"support"},{"name":"supported"},{"name":"swap"},{"name":"swaps"},{"name":"switches"},{"name":"syncJobs"},{"name":"syslogServers"},{"name":"system"},{"name":"targetGroups"},{"name":"tests"},{"name":"themes"},{"name":"thirdPartyVPNPeers"},{"name":"thousandEyes"},{"name":"throughputTest"},{"name":"token"},{"name":"tokens"},{"name":"top"},{"name":"topology"},{"name":"traceRoute"},{"name":"traffic"},{"name":"trafficAnalysis"},{"name":"trafficHistory"},{"name":"trafficShaping"},{"name":"transceivers"},{"name":"traps"},{"name":"trustedAccessConfigs"},{"name":"trustedServers"},{"name":"upgrades"},{"name":"uplink"},{"name":"uplinkBandwidth"},{"name":"uplinkSelection"},{"name":"uplinks"},{"name":"uplinksLossAndLatency"},{"name":"usage"},{"name":"usageHistories"},{"name":"usageHistory"},{"name":"userAccessDevices"},{"name":"utilization"},{"name":"v4"},{"name":"video"},{"name":"videoLink"},{"name":"vlanAssignments"},{"name":"vlanProfiles"},{"name":"vlans"},{"name":"vmx"},{"name":"vpn"},{"name":"vpnExclusions"},{"name":"vpnFirewallRules"},{"name":"vppAccounts"},{"name":"wakeOnLan"},{"name":"warmSpare"},{"name":"warnings"},{"name":"webApps"},{"name":"webhookTests"},{"name":"webhooks"},{"name":"wirelessControllers"},{"name":"wirelessProfiles"},{"name":"wlanLists"},{"name":"xdr"},{"name":"zigbee"},{"name":"zones"}],"x-parser-conf":{"overview":{"markdownPath":"docs/overview-early-access.md"},"theme":"meraki","serverConfig":true,"httpBearer":{"bearerToken":"75dd5334bef4d2bc96f26138c163c0a3fa0b5ca6"},"labelConfig":{"endpoint":{"field":"operationId","format":"startCase"}},"groupBy":{"$remoteModule":"config/group_platform.js"},"filterBy":{"$remoteModule":"config/filter_only_beta.js"},"sortBy":{"$remoteModule":"config/sort_by.js"},"exampleAsDefault":true,"expand":0,"variables":{"organizationId":"1215707","networkId":"N_784752235069315754","serial":"QBSB-VQ3J-XZ54"}},"openapi":"3.0.1","servers":[{"url":"https://api.meraki.com/{basePath}","variables":{"basePath":{"default":"api/v1"}}}],"securitySchemes":{"meraki_api_key":{"type":"apiKey","name":"X-Cisco-Meraki-API-Key","in":"header"},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key"}}},"spec":{"description":"List the historical usage and traffic data of switchports in an organization.","operationId":"getOrganizationSwitchPortsUsageByDeviceByInterval","parameters":[{"name":"organizationId","in":"path","description":"Organization ID","schema":{"type":"string"},"required":true},{"name":"t0","in":"query","description":"The beginning of the timespan for the data. The maximum lookback period is 31 days from today.","schema":{"type":"string"}},{"name":"t1","in":"query","description":"The end of the timespan for the data. t1 can be a maximum of 31 days after t0.","schema":{"type":"string"}},{"name":"timespan","in":"query","description":"The timespan for which the information will be fetched. If specifying timespan, do not specify parameters t0 and t1. The value must be in seconds and be less than or equal to 31 days. The default is 1 day. If interval is provided, the timespan will be autocalculated.","schema":{"type":"number","format":"float","maximum":2678400}},{"name":"interval","in":"query","description":"The time interval in seconds for returned data. The valid intervals are: 300, 1200, 14400, 86400. The default is 1200. Interval is calculated if time params are provided.","schema":{"type":"integer"}},{"name":"perPage","in":"query","description":"The number of entries per page returned. Acceptable range is 3 - 50. Default is 10.","schema":{"type":"integer"}},{"name":"startingAfter","in":"query","description":"A token used by the server to indicate the start of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, prev, or next page in the HTTP Link header should define it.","schema":{"type":"string"}},{"name":"endingBefore","in":"query","description":"A token used by the server to indicate the end of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, prev, or next page in the HTTP Link header should define it.","schema":{"type":"string"}},{"name":"configurationUpdatedAfter","in":"query","description":"Optional parameter to filter items to switches where the configuration has been updated after the given timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"mac","in":"query","description":"Optional parameter to filter items to switches with MAC addresses that contain the search term or are an exact match.","schema":{"type":"string"}},{"name":"macs","in":"query","description":"Optional parameter to filter items to switches that have one of the provided MAC addresses.","schema":{"type":"array","items":{"type":"string"}}},{"name":"name","in":"query","description":"Optional parameter to filter items to switches with names that contain the search term or are an exact match.","schema":{"type":"string"}},{"name":"networkIds","in":"query","description":"Optional parameter to filter items to switches in one of the provided networks.","schema":{"type":"array","items":{"type":"string"}}},{"name":"portProfileIds","in":"query","description":"Optional parameter to filter items to switches that contain switchports belonging to one of the specified port profiles.","schema":{"type":"array","items":{"type":"string"}}},{"name":"serial","in":"query","description":"Optional parameter to filter items to switches with serial number that contains the search term or are an exact match.","schema":{"type":"string"}},{"name":"serials","in":"query","description":"Optional parameter to filter items to switches that have one of the provided serials.","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"The name of the switch."},"serial":{"type":"string","description":"The serial number of the switch."},"mac":{"type":"string","description":"The MAC address of the switch."},"network":{"type":"object","properties":{"name":{"type":"string","description":"The name of the network."},"id":{"type":"string","description":"The ID of the network."}},"description":"Identifying information of the switch's network."},"model":{"type":"string","description":"The model of the switch."},"ports":{"type":"array","items":{"type":"object","properties":{"portId":{"type":"string","description":"The string identifier of this port on the switch. This is commonly just the port number but may contain additional identifying information such as the slot and module-type if the port is located on a port module."},"history":{"type":"array","items":{"type":"object","properties":{"startTs":{"type":"string","format":"date-time","description":"The starting timestamp of the given interval."},"endTs":{"type":"string","format":"date-time","description":"The end timestamp of the given interval."},"data":{"type":"object","properties":{"usage":{"type":"object","properties":{"total":{"type":"integer","description":"The total amount of data sent and received (in kilobytes)."},"upstream":{"type":"integer","description":"The amount of data sent (in kilobytes)."},"downstream":{"type":"integer","description":"The amount of data received (in kilobytes)."}},"description":"Usage data for the given interval."}},"description":"A breakdown of how many kilobytes have passed through this port during the interval timespan."},"bandwidth":{"type":"object","properties":{"usage":{"type":"object","properties":{"total":{"type":"number","format":"float","description":"The average speed of the data sent and received (in kilobits-per-second)."},"upstream":{"type":"number","format":"float","description":"The average speed of the data sent (in kilobits-per-second)."},"downstream":{"type":"number","format":"float","description":"The average speed of the data received (in kilobits-per-second)."}},"description":"Bandwidth usage data for the given interval."}},"description":"A breakdown of the average speed of data that has passed through this port during the interval."},"energy":{"type":"object","properties":{"usage":{"type":"object","properties":{"total":{"type":"number","format":"float","description":"The total energy in watt-hours delivered by this port during the interval"}},"description":"Energy data for the given interval."}},"description":"How much energy (in watt-hours) has been delivered by this port during the interval."}}},"description":"An array of intervals for a port with bandwidth, traffic, and power usage data."}}},"description":"The number of ports on the switch with usage data."}}},"description":"Switches"},"meta":{"type":"object","properties":{"counts":{"type":"object","properties":{"items":{"type":"object","properties":{"total":{"type":"integer","description":"The total number of items in the dataset"},"remaining":{"type":"integer","description":"The number of items in the dataset that are available on subsequent pages"}},"description":"Counts relating to the paginated items"}},"description":"Counts relating to the paginated dataset"}},"description":"Metadata relevant to the paginated dataset"}}},"example":{"items":[{"name":"Example Switch","serial":"Q555-5555-5555","mac":"01:23:45:67:ab:cd","network":{"name":"Example Network","id":"L_12345"},"model":"MS120-8","ports":[{"portId":"1","history":[{"startTs":"2024-02-11T00:00:00.090210Z","endTs":"2024-02-11T00:20:00.090210Z","data":{"usage":{"total":40867,"upstream":23008,"downstream":17859}},"bandwidth":{"usage":{"total":2.2,"upstream":1.2,"downstream":1}},"energy":{"usage":{"total":2.2}}}]}]}],"meta":{"counts":{"items":{"total":1,"remaining":0}}}}}},"headers":{"Link":{"schema":{"type":"string"},"description":"A comma-separated list of first, last, prev, and next relative links used for subsequent paginated requests."}}}},"summary":"List the historical usage and traffic data of switchports in an organization.","tags":["switch","monitor","ports","usage","byDevice","byInterval"],"x-release-stage":"beta","__originalOperationId":"getOrganizationSwitchPortsUsageByDeviceByInterval","security":[{"meraki_api_key":[]},{"bearerAuth":[]}],"method":"get","path":"/organizations/{organizationId}/switch/ports/usage/byDevice/byInterval"}}