--- title: "Query data usage" method: POST path: "/public/v2/data-usage/query" tags: ["Account"] --- # Query data usage `POST /public/v2/data-usage/query` Required permission: Service plan, View.
Retrieve the real-time data tracking info for this account's data usage. For detailed instructions, please refer to the API documentation: https://starlink.readme.io/docs/data-usage-api ## Query parameters - `page` integer - `limit` integer ## Request body - QueryDataUsageRequest - `serviceLineNumbers` string[], nullable — Service line numbers to filter by. Queries for all service lines on account if omitted - `previousBillingCycles` integer, nullable — Number of previous billing cycles to include in addition to the current one. Defaults to 1 - `activeServiceLinesOnly` boolean — Whether to filter by only active service lines. Defaults to true - `queryStartDate` string, date-time, nullable — Override the first cycle's start date with the provided query start date ## Response `200` Successfully retrieved data usage - ServiceLineDataUsageForBillingCyclesPaginatedServiceResponse - `errors` ValidationResult[], nullable - `memberNames` string[], nullable - `errorMessage` string, nullable - `warnings` ValidationResult[], nullable - `memberNames` string[], nullable - `errorMessage` string, nullable - `information` string[], nullable - `isValid` boolean - `content` ServiceLineDataUsageForBillingCyclesPaginated - `pageIndex` integer - `limit` integer - `isLastPage` boolean - `results` ServiceLineDataUsageForBillingCycles[], nullable - `accountNumber` string — Account number that owns this service line. - `serviceLineNumber` string — Service line number for which usage data is reported. - `startDate` string, date-time — Start date of the first billing cycle in the response (UTC). - `endDate` string, date-time — End date of the last billing cycle in the response (UTC). - `billingCycles` DataUsageBillingCycleV2[] — Data usage grouped by billing cycle, ordered chronologically. The most recent cycle appears last in the array. - `startDate` string, date-time — Start date of the billing cycle. - `endDate` string, date-time — End date of the billing cycle. - `dailyDataUsage` DataUsageDailyV2[] — Daily data usage breakdown for each day in the billing cycle. Omits days with no recorded usage. - `date` string, date-time — Date of usage (UTC). - `priorityGB` number, double — Total priority (unrestricted, high-speed) data consumed on this day in GB. Includes opt-in priority data. - `optInPriorityGB` number, double — Portion of priority data consumed while opted into overage on this day in GB. This is a subset of PriorityGB, not additive. - `standardGB` number, double — Standard (deprioritized) data consumed on this day in GB. - `nonBillableGB` number, double — Non-billable data consumed on this day in GB. - `overageLines` DataUsageOverageLine[] — Overage lines for metered plans showing usage beyond plan limits. Empty for plans without overage or cycles with no overage. May contain multiple lines if subscription changed mid-cycle. - `restricted` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 - `unrestricted` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 - `pricePerGB` number, double — Price per GB for overage consumption (e.g., 1.00 for $1.00/GB). - `usageLimitGB` number, double — Plan's included priority data limit in GB before overage charges apply. Zero for plans that are restricted by default. - `overageAmountGB` number, double — Amount of priority data consumed beyond the usage limit while opted into overage, in GB. Only opt-in priority data counts toward overage. - `consumedAmountGB` number, double — Amount of priority data consumed up to the usage limit, in GB. - `overagePrice` number, double — Total overage cost before taxes and fees. - `productId` string — Product ID for the overage product. - `dataOverageType` 0 | 1 | 2 | 3 - `activeFrom` string, date-time, nullable — Date when this overage period began tracking usage (UTC). Null if no usage has been recorded yet. - `dataPoolUsage` DataPoolUsagePublicResponse[] — Data pool usage information for Priority data plans. Empty for metered plans or if no data pools are attached. - `accountNumber` string — Account number that owns this data pool. - `dataPoolId` string — Data pool ID. - `lastUpdated` string, date-time — Timestamp when the data pool usage was last updated (UTC). - `dataBlocks` DataBlockUsagePublicResponse[] — Usage by data blocks in the pool. - `dataBlockId` string — Data block ID - `startDateUtc` string, date-time — UTC start date of the data block. - `expirationDateUtc` string, date-time — UTC expiration date of the data block. - `totalAmountGB` number, double — Total GB capacity, calculated by multiplying BlocksCount and PerBlockAmountGB. - `consumedAmountGB` number, double — How much data has been used on the block. - `perBlockAmountGB` number, double — GB capacity per individual block. - `dataBlockType` 'IncludedWithBaseSubscription' | 'RecurringPerBillingCycle' | 'Overage' | 'OneTimePurchase' - `productId` string — Product ID of the data block. - `blocksCount` integer — Number of data blocks. - `perBlockPrice` number, double — Price per individual data block. - `totalPrice` number, double — Total price, calculated by multiplying PerBlockPrice and BlocksCount. - `isoCurrencyCode` string — Currency code for the price. - `serviceLineUsage` DataBlockServiceLineUsagePublicResponse[] — Usage breakdown by service lines. - … - `monthlyUsage` DataBlockMonthlyPublicResponse[] — Usage breakdown by month. - … - `totalPriorityGB` number, double — Total priority data consumed in this billing cycle (GB), rounded to 2 decimal places. Includes opt-in priority data. - `totalStandardGB` number, double — Total standard data consumed in this billing cycle (GB), rounded to 2 decimal places. - `totalOptInPriorityGB` number, double — Total priority data consumed while opted into overage in this billing cycle (GB), rounded to 2 decimal places. This is a subset of TotalPriorityGB. - `totalNonBillableGB` number, double — Total non-billable data consumed in this billing cycle (GB), rounded to 2 decimal places. - `servicePlan` DataServicePlan - `isoCurrencyCode` string, nullable — ISO currency code for displaying prices (e.g., "USD", "EUR"). Null if no subscription exists. - `isMobilePlan` boolean, required — Indicates if this is a mobile-type plan (mobility class is nomadic or mobile). - `activeFrom` string, date-time, nullable — Date when data usage tracking began for this product (UTC). May differ from subscription start date. - `subscriptionActiveFrom` string, date-time, nullable — Date when the service line's subscription started (UTC). - `subscriptionEndDate` string, date-time, nullable — Date when the subscription ended (UTC). Null for active subscriptions. - `overageName` string — Display name for the overage product shown in opt-in/out interfaces. Empty string if no overage product exists. - `overageDescription` string — Description of the overage product shown in opt-in/out interfaces. Empty string if no overage product exists. - `isOptedIntoOverage` boolean, required — Indicates whether the service line is currently opted into overage for metered plans. - `overageLineDeactivatedDate` string, date-time, nullable — Most recent date and time when overage opt-in was disabled (UTC). Null if never disabled or currently opted in. - `overageLine` DataUsageOverageLine - `restricted` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 - `unrestricted` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 - `pricePerGB` number, double — Price per GB for overage consumption (e.g., 1.00 for $1.00/GB). - `usageLimitGB` number, double — Plan's included priority data limit in GB before overage charges apply. Zero for plans that are restricted by default. - `overageAmountGB` number, double — Amount of priority data consumed beyond the usage limit while opted into overage, in GB. Only opt-in priority data counts toward overage. - `consumedAmountGB` number, double — Amount of priority data consumed up to the usage limit, in GB. - `overagePrice` number, double — Total overage cost before taxes and fees. - `productId` string — Product ID for the overage product. - `dataOverageType` 0 | 1 | 2 | 3 - `activeFrom` string, date-time, nullable — Date when this overage period began tracking usage (UTC). Null if no usage has been recorded yet. - `dataPoolUsage` DataPoolUsagePublicResponse - `accountNumber` string — Account number that owns this data pool. - `dataPoolId` string — Data pool ID. - `lastUpdated` string, date-time — Timestamp when the data pool usage was last updated (UTC). - `dataBlocks` DataBlockUsagePublicResponse[] — Usage by data blocks in the pool. - `dataBlockId` string — Data block ID - `startDateUtc` string, date-time — UTC start date of the data block. - `expirationDateUtc` string, date-time — UTC expiration date of the data block. - `totalAmountGB` number, double — Total GB capacity, calculated by multiplying BlocksCount and PerBlockAmountGB. - `consumedAmountGB` number, double — How much data has been used on the block. - `perBlockAmountGB` number, double — GB capacity per individual block. - `dataBlockType` 'IncludedWithBaseSubscription' | 'RecurringPerBillingCycle' | 'Overage' | 'OneTimePurchase' - `productId` string — Product ID of the data block. - `blocksCount` integer — Number of data blocks. - `perBlockPrice` number, double — Price per individual data block. - `totalPrice` number, double — Total price, calculated by multiplying PerBlockPrice and BlocksCount. - `isoCurrencyCode` string — Currency code for the price. - `serviceLineUsage` DataBlockServiceLineUsagePublicResponse[] — Usage breakdown by service lines. - … - `monthlyUsage` DataBlockMonthlyPublicResponse[] — Usage breakdown by month. - … - `productId` string, required — Product ID identifying the current subscription plan. Empty string if no subscription exists. - `usageLimitGB` number, double, required — Usage limit in GB for this plan. For metered plans, this is the priority data limit. For Priority data plans, this is the total data pool capacity. - `dataCategoryMapping` object, required — Deprecated. Value will always be empty dictionary. - `lastUpdated` string, date-time, nullable — Timestamp when the usage data was last updated in the cache. Only present for cached data (typically yesterday and later). - `totalCount` integer ## Other responses - `400` — Bad Request - `401` — Unauthorized - `403` — Missing required permission for this endpoint or resource - `422` — Failed to query data usage --- [API](https://skmtc.net/starlink/apis/starlink-management-api.md) · [All operations](https://skmtc.net/starlink/apis/starlink-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/starlink/starlink-management-api/revisions/a730bd0ddb42/schema)