The caller's bandwidth allowance for a period: granted, used, remaining, which entitlements contributed, and which domains may draw on it. One allowance covers both the caller's own sites and its visits to sender-pays sites.
Parameters
Output
Encoding
application/jsonapprovals
array
Optional
Domains the caller agreed to let spend its allowance, with the cap it chose for each.
consumption
object
Required
One identity's allowance for one period.
Errors
InvalidRequest
period is not a UTC month formatted as YYYY-MM. Try It
Requests are sent directly from your browser. Some servers may block requests due to CORS.
View raw schema
{
"type": "query",
"errors": [
{
"name": "InvalidRequest",
"description": "period is not a UTC month formatted as YYYY-MM."
}
],
"output": {
"schema": {
"type": "object",
"required": [
"consumption"
],
"properties": {
"approvals": {
"type": "array",
"items": {
"type": "object",
"required": [
"domain",
"approvedAt"
],
"properties": {
"domain": {
"type": "string",
"description": "The domain approved."
},
"capBytes": {
"type": "integer",
"description": "The cap the caller chose for this domain. Absent means no cap."
},
"approvedAt": {
"type": "string",
"format": "datetime",
"description": "When the identity agreed."
}
},
"description": "Standing consent to spend the allowance on one domain."
},
"description": "Domains the caller agreed to let spend its allowance, with the cap it chose for each."
},
"consumption": {
"type": "object",
"required": [
"period",
"periodEndsAt",
"grantedBytes",
"usedBytes",
"remainingBytes",
"freeBytes",
"entitledBytes",
"headerEstimateBytes"
],
"properties": {
"period": {
"type": "string",
"description": "The UTC month, as YYYY-MM."
},
"byDomain": {
"type": "array",
"items": {
"type": "object",
"required": [
"domain",
"bytesBilled"
],
"properties": {
"domain": {
"type": "string",
"description": "The domain."
},
"asVisitor": {
"type": "boolean",
"description": "True when this was someone else's sender-pays site, not one of the caller's own."
},
"bytesBilled": {
"type": "integer",
"description": "Billed bytes."
}
},
"description": "Where the allowance was spent."
},
"description": "Spend by domain."
},
"freeBytes": {
"type": "integer",
"description": "Bytes from the free grant."
},
"usedBytes": {
"type": "integer",
"description": "Billable bytes spent so far."
},
"entitlements": {
"type": "array",
"items": {
"type": "object",
"required": [
"bytesPerPeriod",
"startsAt"
],
"properties": {
"endsAt": {
"type": "string",
"format": "datetime",
"description": "When it ends. Absent if it has no end date."
},
"startsAt": {
"type": "string",
"format": "datetime",
"description": "When it started."
},
"bytesPerPeriod": {
"type": "integer",
"description": "Bytes this entitlement adds per period."
}
},
"description": "One grant that adds to the allowance. The payment processor's reference is not exposed."
}
},
"grantedBytes": {
"type": "integer",
"description": "The free grant plus every active entitlement."
},
"periodEndsAt": {
"type": "string",
"format": "datetime",
"description": "When the allowance resets."
},
"reconciledAt": {
"type": "string",
"format": "datetime",
"description": "When usedBytes was last reconciled against recorded requests. Absent for a period still in progress."
},
"entitledBytes": {
"type": "integer",
"description": "Bytes from entitlements."
},
"remainingBytes": {
"type": "integer",
"description": "What is left, never below zero."
},
"freePerDomainBytes": {
"type": "integer",
"description": "The most the free grant can spend at any one domain this period. Purchased quota has no such cap. Zero means the free grant cannot be spent on other people's sites. This is why a reader can be refused at one domain while their allowance still has room."
},
"headerEstimateBytes": {
"type": "integer",
"description": "The fixed per-response header estimate included in usedBytes. The edge logs only response bodies, so every byte figure here is estimated by this much per response."
}
},
"description": "One identity's allowance for one period."
}
}
},
"encoding": "application/json"
},
"parameters": {
"type": "params",
"properties": {
"period": {
"type": "string",
"description": "A UTC month as YYYY-MM. Defaults to the current month."
}
}
},
"description": "The caller's bandwidth allowance for a period: granted, used, remaining, which entitlements contributed, and which domains may draw on it. One allowance covers both the caller's own sites and its visits to sender-pays sites."
}