No matching sections.

Account, usage & quota

Four reads on account:read that answer the questions a client asks before it acts - what is this account allowed to do, how much of it has it already done, and how many API calls are left - and one write on account:write that changes the account's own details.

GET /account

{
  "id": "3fa85f64-…",
  "login": "acme",
  "timezone": "Etc/UTC",
  "language": "it",
  "profile": {
    "firstName": "QA29437", "lastName": "", "company": "",
    "phone": "", "country": "", "email": "[email protected]"
  },
  "defaultAgentPools": { "legacy": ["allworld"] },
  "flags": { "enabled": true, "active": true, "overlimited": false, "apiEnabled": false },
  "package": { "id": "…", "name": "30-Days Free Trial", "features": { /* … */ } },
  "usage": { "monitor": { "used": 14, "allowed": 100 }, /* contact, report, maintenance */ },
  "overlimits": [],
  "limits": { "intervals": [60, 120, 180, /* 14 total */], "maxBulkItems": 5000, /* … */ },
  "badges": { "unconfirmedContacts": 0, "alerts24h": 0, "openIncidents": 0 }
}

This account is on the 30-Days Free Trial, whose package does not sell API access - hence flags.apiEnabled: false above; see flags below for why that is informational, not a gate. flags.disableReason and flags.stoppedAt are themselves omitted here rather than sent as null - both apply only to a disabled/stopped account, and this one is neither.

badges is the dashboard's attention row, readable programmatically: contacts still waiting for confirmation, alerts delivered in the last 24 hours, and currently-open incidents.

flags: the account's own state

flags is a bag of independent booleans, not a lifecycle: enabled, active and overlimited, plus disableReason and stoppedAt when they apply. Any combination can hold at once, which is precisely why it is not one word.

overlimits beside it says which dimensions are over - task, contact, report, maintenance - and is empty when the account is inside its package. So flags.overlimited tells you that, and overlimits tells you what.

profile and default locations

profile is who the account is registered to, and defaultAgentPools is where a new monitor starts checking from. Both ride GET /account and both are written by PATCH /account - so a client reads the resource, edits it, and sends it back without ever leaving this endpoint.

PATCH /account

Changes the members the body names and leaves the rest alone. Answers 200 with the whole updated account - the same document GET /account returns - so nothing has to be re-read to confirm what was written. Scope account:write; a delegated member needs the profile-edit right. Idempotency-Key is accepted and not required.

A minimal patch, changing three members:

{
  "company": "Acme Ltd",
  "country": "GB",
  "timezone": "Europe/London"
}

Reads back with the whole account - the touched members updated, and timezone already in its IANA spelling:

{
  "id": "3fa85f64-…",
  "login": "acme",
  "timezone": "Europe/London",
  "profile": {
    "firstName": "QA29437", "lastName": "", "company": "Acme Ltd",
    "phone": "", "country": "GB", "email": "[email protected]"
  },
  /* language, defaultAgentPools, flags, package, usage, overlimits, limits, badges - unchanged, same shape as GET /account above */
}

package and features

package.features is the entitlement map: booleans and numeric caps, camelCase, and exactly the names a 403 package_limit problem puts in its feature field. That is the point of the shared spelling - a refusal names a key you can look up here, rather than prose you have to map by hand.

usage: what you have spent

GET /account/usage - and the identical block on GET /account - reports consumption per domain under four singular keys, each {used, allowed}:

{
  "monitor":     { "used": 14, "allowed": 100 },
  "contact":     { "used": 3,  "allowed": 20 },
  "report":      { "used": 0,  "allowed": null },   // null = no limit
  "maintenance": { "used": 1,  "allowed": 0 }       // 0 = a real cap of none
}

limits: what a request may ask for

Where usage is about your rows, limits is about your requests - the numbers a client needs before it composes one:

quota: API call headroom

GET /account/quota reports how many API calls are left, without spending any of them. When at least one window is configured, its top-level limit/used/remaining/ resetAt describe the tightest-binding window - the one you will hit first. On an account with none configured - like the capture below - those members, each pool's own limit, and tokenCap are omitted rather than sent as null, the same omit-when-absent rule flags.disableReason/stoppedAt follow above. And pools breaks it down:

{
  "pools": {
    "check":   { "quotas": [] },   // instant checks
    "account": { "quotas": [] }    // everything else
  },
  "scopes": [ { "scope": "monitor:read", "description": "…" }, /* 20 rows */ ],
  "apiEnabled": false
}

Each entry of a pool's quotas[] is one configured window:

scopes[] is the mintable scope catalogue - all 20 (thirteen leaves plus seven families), each with a one-line description from the source registry. Build a token-scope picker from it rather than from a hardcoded list. tokenCap echoes the presented token's own self-cap when it carries one.

apiEnabled repeats GET /account's flags.apiEnabled here, because this is the document you read when you are asking "may I, and how much" - and those two halves should not cost two calls. false beside an empty pools means "the API is not enabled for this account", which is a different statement from "this account is not metered".

Shared access

GET /account/member lists the contacts holding shared access to this account - the subaccount graph, read-only here: