Counting devices for a dashboard

Counting devices for a dashboard

If you are building an inventory dashboard, you do not need to download every device just to display a number. The API can count for you and return the totals already grouped:

GET /api/public/v1/assets/count?group_by=asset_class&site=38&checked_out=false 

{
  "total": 15,
  "results": [
    { "asset_class": { "id": 3, "name": "Chromebook" }, "count": 15 }
  ]
}

This is a read-only call. It needs a key with the assets:read permission, the same one that lets you list devices.

Choosing what to group by

group_by is the one required parameter. It takes asset_class, site, or both:

group_by=asset_class          one row per device class
group_by=site                 one row per site
group_by=site,asset_class     one row per class at each site

Each dimension you group by appears as a member on every row, so group_by=site,asset_class returns rows carrying both a site and an asset_class.

Narrowing what is counted

Any of these can take several values, separated by commas, and — as everywhere else in the API — you can use a name instead of an id.

The zero-fill rule (the important one)

If you name the values you want, you get all of them back — including the empty ones.

A library that stocks Chromebooks and iPads but has run out of laptops still returns a laptop row, with a count of zero:

GET /api/public/v1/assets/count?group_by=asset_class&site=15&asset_class=Chromebook,Laptop,iPad&checked_out=false 

{
  "total": 7,
  "results": [
    { "asset_class": { "id": 3, "name": "Chromebook" }, "count": 5 },
    { "asset_class": { "id": 4, "name": "Laptop" },     "count": 0 },
    { "asset_class": { "id": 5, "name": "iPad" },       "count": 2 }
  ]
}

That "count": 0 is deliberate. It means your dashboard can display "0 Available Laptops" as an alert state without having to handle a missing entry, and it means a class you asked about never silently disappears from the response.

If you leave a filter off, it behaves as a wildcard, and you get back only the values actually present. Omit asset_class entirely and you will see every class that exists at that site — and nothing for the ones that do not.

So the rule in one line: ask for something explicitly and it always comes back, even at zero; leave it out and you only see what is there.

One call for an entire dashboard

Because the values you name are always returned, filtering several sites and several classes at once gives you every combination — a complete grid, zeros filled in:

GET /api/public/v1/assets/count?group_by=site,asset_class&site=15,16,17,18&asset_class=Chromebook,Laptop,iPad&checked_out=false 

That is one request for a four-building, three-class panel: 12 rows, every one of them present whether or not the building stocks that class.

Which devices are counted

By default, counts include devices that are in inventory — active and inactive ones. Archived and trashed devices are left out, so a repair-bench tile is not quietly inflated by devices that were thrown away months ago.

To count differently, name the states you want, or ask for everything:

state=active                  only active devices
state=active,archived         active plus archived
state=any                     every device, whatever its state

The states available to you are listed at GET /api/public/v1/meta.

Counting a class and its subclasses together

Device classes can be nested — "Laptop" might have "MacBook" and "ThinkPad" beneath it. By default a count is for the exact class you asked for, so a district with only MacBooks would see Laptop: 0.

Add include_descendants=true and each class you asked for absorbs everything beneath it:

GET /api/public/v1/assets/count?group_by=asset_class&asset_class=Laptop&include_descendants=true 

Now the MacBooks are counted under Laptop. This applies only to classes and sites you name explicitly; a wildcard always counts by exact class.

Reading total

total is the number of distinct devices matching your filters. It is usually the sum of the rows, but not always: if you ask for a class and one of its subclasses while include_descendants=true is on, a device legitimately counts in both rows. total never double-counts, so trust it as the true figure.

Devices with no class

A device that has never been assigned a class still exists, and it appears as a row with "asset_class": null. This is intentional — it makes unclassified devices visible rather than quietly dropping them and leaving your rows short of the total. If you don't want them on a dashboard, filter to the classes you care about.