Printago API
GET /v1/reports/usage-by-user

Usage by user report

Each person's and API key's filament use, and what to bill them A print counts for whoever queued its job: a person or an API key. Prints whose job has no creator recorded are counted under `unattributedGrams` and `unattributedPrints`, and never billed to anyone. `from` and `to` are inclusive days in the store's timezone, matched against when each print ended. Each job line is what one print drew from one spool or color (grams from the stock ledger, so this needs the filament-inventory add-on). `rate` picks what a line bills: `cost` at the spool's price, else the color's, else the material's; `billable` at the material's billable rate in effect when the print ended. A line with no rate (or, at cost, no price) has a null `billCents`, is counted in `unratedGrams`, and adds nothing to the bill. Grams are rounded to the tenth and money to the cent on each line, and every total is the sum of its lines. `actors` lists everyone with usage in the range and printers, whatever `actorIds` selects, for a picker.

Requires: analytics.view

Query Parameters

from required
string
YYYY-MM-DD, inclusive, in the store's timezone.
to required
string
YYYY-MM-DD, inclusive, in the store's timezone.
printerIds optional
string
Comma-separated printer ids; omitted = all printers.
actorIds optional
string
Comma-separated actor ids (whoever queued the job); omitted = everyone.
rate optional
"cost" | "billable"
What a print is billed at. Default `cost`.

Response Schema

UsageByUserReport
actorsrequired
object[]
Everyone with usage in the range and printers, whatever `actorIds` picks.
actorIdrequired
string
labelrequired
string
A person's email or an API key's name, as recorded when the job was queued.
namerequirednullable
string
A person's display name, when they have one.
typerequirednullable
string
`user`, `api_key`, or another recorded actor type; null when unknown.
fromrequired
string
raterequired
"cost" | "billable"
costbillable
summaryrequired
object
billCentsrequired
number
Equals the users' bill, summed.
costCentsrequired
number
Every print in range at cost, like `grams`: the users' plus the unattributed.
gramsrequired
number
Every print in range: the users' plus the unattributed. With `actorIds`, the picked people's alone.
printsrequired
number
unattributedCostCentsrequired
number
unattributedGramsrequired
number
The part of `grams` and `prints` whose job has no creator recorded. Never billed to anyone. Zero with `actorIds`.
unattributedPrintsrequired
number
unratedGramsrequired
number
usersrequired
number
timezonerequired
string
torequired
string
unattributedJobsrequired
object[]
The lines of prints whose job has no creator recorded, newest first; never billed. Empty with `actorIds`.
atrequired
string
When the print ended.
format: date-time
billCentsrequirednullable
number
Rounded to the cent. Null when there is no rate (or, at cost, no price): it is not billed.
colorrequirednullable
string
The color's hex, when it has one.
costCentsrequirednullable
number
At the spool's price when it printed, else the color's, else the material's; null with none.
gramsrequired
number
labelrequired
string
The job's name.
materialIdrequirednullable
string
materialLabelrequired
string
Color · material, e.g. `Black · Bambu Lab PLA Basic`.
printHistoryIdrequired
string
printJobIdrequirednullable
string
ratePer1000grequirednullable
number
Cents per kg the line was billed at: the cost price, or the billable rate in effect when it printed.
spoolCoderequirednullable
string
The spool's serial or label code, when it has one.
spoolDeletedrequired
boolean
The spool has since been deleted, so it has no page to open.
spoolIdrequirednullable
string
The tracked spool it drew from, still set once that spool is deleted; null for untracked stock.
usersrequired
object[]
Highest bill first.
actorIdrequired
string
billCentsrequired
number
Sum of the lines' bill. Lines with no rate add nothing.
costCentsrequired
number
Sum of the lines' cost.
gramsrequired
number
jobsrequired
object[]
Newest first.
atrequired
string
When the print ended.
format: date-time
billCentsrequirednullable
number
Rounded to the cent. Null when there is no rate (or, at cost, no price): it is not billed.
colorrequirednullable
string
The color's hex, when it has one.
costCentsrequirednullable
number
At the spool's price when it printed, else the color's, else the material's; null with none.
gramsrequired
number
labelrequired
string
The job's name.
materialIdrequirednullable
string
materialLabelrequired
string
Color · material, e.g. `Black · Bambu Lab PLA Basic`.
printHistoryIdrequired
string
printJobIdrequirednullable
string
ratePer1000grequirednullable
number
Cents per kg the line was billed at: the cost price, or the billable rate in effect when it printed.
spoolCoderequirednullable
string
The spool's serial or label code, when it has one.
spoolDeletedrequired
boolean
The spool has since been deleted, so it has no page to open.
spoolIdrequirednullable
string
The tracked spool it drew from, still set once that spool is deleted; null for untracked stock.
labelrequired
string
A person's email or an API key's name, as recorded when the job was queued.
namerequirednullable
string
A person's display name, when they have one.
printsrequired
number
Prints, counted once however many spools each drew from.
typerequirednullable
string
`user`, `api_key`, or another recorded actor type; null when unknown.
unratedGramsrequired
number
Grams on lines with no rate, which are not billed.

Example Response

200 OK — application/json 
{
  "from": "string",
  "to": "string",
  "timezone": "string",
  "rate": "cost",
  "summary": {
    "billCents": 1,
    "costCents": 1,
    "grams": 1,
    "prints": 1,
    "users": 1,
    "unratedGrams": 1,
    "unattributedGrams": 1,
    "unattributedPrints": 1,
    "unattributedCostCents": 1
  },
  "users": [
    {
      "prints": 1,
      "grams": 1,
      "costCents": 1,
      "billCents": 1,
      "unratedGrams": 1,
      "jobs": [
        {
          "at": "2025-01-15T12:00:00.000Z",
          "printHistoryId": "string",
          "printJobId": "string",
          "label": "string",
          "materialId": "string",
          "materialLabel": "string",
          "color": "string",
          "spoolId": "string",
          "spoolCode": "string",
          "spoolDeleted": true,
          "grams": 1,
          "costCents": 1,
          "ratePer1000g": 1,
          "billCents": 1
        }
      ],
      "actorId": "string",
      "label": "string",
      "name": "string",
      "type": "string"
    }
  ],
  "actors": [
    {
      "actorId": "string",
      "label": "string",
      "name": "string",
      "type": "string"
    }
  ],
  "unattributedJobs": [
    {
      "at": "2025-01-15T12:00:00.000Z",
      "printHistoryId": "string",
      "printJobId": "string",
      "label": "string",
      "materialId": "string",
      "materialLabel": "string",
      "color": "string",
      "spoolId": "string",
      "spoolCode": "string",
      "spoolDeleted": true,
      "grams": 1,
      "costCents": 1,
      "ratePer1000g": 1,
      "billCents": 1
    }
  ]
}