---
title: "Get material consumption by material type, brand and color, the most-used spools, how long each spool will last, and waste."
method: GET
path: "/api/Analytics/materials"
tags: ["Analytics"]
---

# Get material consumption by material type, brand and color, the most-used spools, how long each spool will last, and waste.

`GET /api/Analytics/materials`

## Request

- Base URL: `https://api.3dprintlog.com`
- URL: `https://api.3dprintlog.com/api/Analytics/materials`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://3dprintlog.auth0.com/authorize`, token URL `https://3dprintlog.auth0.com/oauth/token`)
  - API key in header `X-Api-Key`
  - API key in query parameter `api_key`

Covers the authenticated user's own prints only. Every analytics endpoint takes the same
filter: a half-open `fromDate`/`toDate` range (omit both for all time), an IANA
`timeZone` for bucketing (default UTC), optional `printerIds`,
`filamentIds`, `projectIds` and `statuses`, a `granularity`
(Auto, Day, Week or Month) and `comparePrevious` to add the preceding window of the
same length. Ids the caller does not own match nothing.

## Query parameters

- `FromDate` string, date-time
- `ToDate` string, date-time
- `TimeZone` string
- `PrinterIds` integer[]
- `FilamentIds` string[]
- `ProjectIds` string[]
- `Statuses` PrintLogApiModelsPrintPrintStatus[]
- `Granularity` 0 | 1 | 2 | 3: Sent as an integer: `0` = Auto, `1` = Day, `2` = Week, `3` = Month.
- `ComparePrevious` boolean
- `HasRange` boolean

## Response `200`

Material usage for the filtered window.

- PrintLogApiModelsDTOsAnalyticsMaterialsResponse: Coverage counts prints. Adjustments (#231) are counted on their own: AdjustmentCount is the adjustment rows the figures include, and RowCapExceeded says the tab was emptied because usage and adjustment rows together exceeded the row cap, which the print coverage cannot say when there are no prints to exclude.
  - `from` string, date-time, nullable
  - `to` string, date-time, nullable
  - `timeZone` string, nullable
  - `granularity` string, nullable
  - `currency` string, nullable
  - `byType` PrintLogApiModelsDTOsAnalyticsMaterialGroup[], nullable
    - `key` string, nullable
    - `label` string, nullable
    - `printCount` integer
    - `materialMg` integer
    - `swatch` PrintLogApiModelsDTOsAnalyticsSwatchDto: A filament's appearance, sent raw. The UI turns it into CSS or SVG through its shared swatch descriptor — the server never emits presentation strings.
      - `colors` string[], nullable
      - `colorPattern` integer
      - `finishType` integer
      - `effects` integer[], nullable
    - `adjustmentMg` integer
  - `byBrand` PrintLogApiModelsDTOsAnalyticsMaterialGroup[], nullable
    - `key` string, nullable
    - `label` string, nullable
    - `printCount` integer
    - `materialMg` integer
    - `swatch` PrintLogApiModelsDTOsAnalyticsSwatchDto: A filament's appearance, sent raw. The UI turns it into CSS or SVG through its shared swatch descriptor — the server never emits presentation strings.
      - `colors` string[], nullable
      - `colorPattern` integer
      - `finishType` integer
      - `effects` integer[], nullable
    - `adjustmentMg` integer
  - `byColor` PrintLogApiModelsDTOsAnalyticsMaterialGroup[], nullable
    - `key` string, nullable
    - `label` string, nullable
    - `printCount` integer
    - `materialMg` integer
    - `swatch` PrintLogApiModelsDTOsAnalyticsSwatchDto: A filament's appearance, sent raw. The UI turns it into CSS or SVG through its shared swatch descriptor — the server never emits presentation strings.
      - `colors` string[], nullable
      - `colorPattern` integer
      - `finishType` integer
      - `effects` integer[], nullable
    - `adjustmentMg` integer
  - `consumptionOverTime` PrintLogApiModelsDTOsAnalyticsMaterialSeriesBucket[], nullable
    - `index` integer
    - `localStart` string, date
    - `materialMgByType` object, nullable
    - `adjustmentMg` integer
  - `topSpools` PrintLogApiModelsDTOsAnalyticsSpoolRow[], nullable
    - `filamentId` string, nullable
    - `label` string, nullable
    - `swatch` PrintLogApiModelsDTOsAnalyticsSwatchDto: A filament's appearance, sent raw. The UI turns it into CSS or SVG through its shared swatch descriptor — the server never emits presentation strings.
      - `colors` string[], nullable
      - `colorPattern` integer
      - `finishType` integer
      - `effects` integer[], nullable
    - `usedMg` integer
    - `remainingMg` integer, nullable
    - `initialMg` integer, nullable
    - `percentConsumed` number, double, nullable
    - `costConsumed` number, double, nullable
    - `adjustmentMg` integer
  - `runway` PrintLogApiModelsDTOsAnalyticsRunwayRow[], nullable
    - `filamentId` string, nullable
    - `label` string, nullable
    - `swatch` PrintLogApiModelsDTOsAnalyticsSwatchDto: A filament's appearance, sent raw. The UI turns it into CSS or SVG through its shared swatch descriptor — the server never emits presentation strings.
      - `colors` string[], nullable
      - `colorPattern` integer
      - `finishType` integer
      - `effects` integer[], nullable
    - `remainingGrams` number, double
    - `burnRateGramsPerDay` number, double
    - `runwayDays` number, double, nullable
  - `wasteGrams` PrintLogApiModelsDTOsAnalyticsMetric: A scalar metric. Previous is null unless comparePrevious was requested.
    - `value` number, double, nullable
    - `previous` number, double, nullable
    - `coverage` PrintLogApiModelsDTOsAnalyticsCoverage: Population is named explicitly ("prints", "spools", "printers") because a count of excluded spools is not a count of excluded prints.
      - `population` string, nullable
      - `counted` integer
      - `total` integer
      - `undatedCount` integer
      - `exclusions` PrintLogApiModelsDTOsAnalyticsCoverageExclusion[], nullable
        - `reason` string, nullable
        - `count` integer
  - `wasteCost` PrintLogApiModelsDTOsAnalyticsMoneyMetric: Money is decimal, never double, and always carries its currency.
    - `value` number, double, nullable
    - `previous` number, double, nullable
    - `currency` string, nullable
    - `coverage` PrintLogApiModelsDTOsAnalyticsCoverage: Population is named explicitly ("prints", "spools", "printers") because a count of excluded spools is not a count of excluded prints.
      - `population` string, nullable
      - `counted` integer
      - `total` integer
      - `undatedCount` integer
      - `exclusions` PrintLogApiModelsDTOsAnalyticsCoverageExclusion[], nullable
        - `reason` string, nullable
        - `count` integer
  - `coverage` PrintLogApiModelsDTOsAnalyticsCoverage: Population is named explicitly ("prints", "spools", "printers") because a count of excluded spools is not a count of excluded prints.
    - `population` string, nullable
    - `counted` integer
    - `total` integer
    - `undatedCount` integer
    - `exclusions` PrintLogApiModelsDTOsAnalyticsCoverageExclusion[], nullable
      - `reason` string, nullable
      - `count` integer
  - `adjustmentCount` integer
  - `rowCapExceeded` boolean

## Other responses

- `400`: The filter is invalid, for example a one-sided or reversed date range.
- `401`: Unauthorized
- `403`: Forbidden

---

[API](https://skmtc.dev/3dprintlog/apis/3d-print-log-api.md) · [All operations](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/llms.txt) · [OpenAPI document](https://skmtc.dev/3dprintlog/apis/3d-print-log-api/revisions/dfc3a4df4e38?raw)