---
title: "List consumption analytics facets"
method: POST
path: "/api/w/{wId}/analytics/consumption/facets"
tags: ["Private Analytics"]
---

# List consumption analytics facets

`POST /api/w/{wId}/analytics/consumption/facets`

Lists current entities and historical indexed values present in the selected period for each consumption dimension. The workspace route requires a manager; the /me route is restricted server-side to the authenticated member; the agent route is restricted server-side to workspace managers and editors of the selected agent. A facet is disabled when it has no indexed document in that period after applying every active filter except the facet's own dimension.

## Path parameters

- `wId` string, required

## Request body

- object
  - `period` 'cycle' | 'days'
  - `days` integer
  - `scope` 'all' | 'automations' — Restricts which documents the facets are computed over. `automations` counts only trigger-originated runs.
  - `dimensions` string[] — Dimensions to compute facets for. Defaults to every dimension. Omitted dimensions come back as empty arrays. The personal route omits user and group dimensions, and the agent route omits the agent dimension.
  - `filter` object — Map of consumption dimensions to selected values.
    - `agents` string[]
    - `users` string[]
    - `api_keys` string[]
    - `groups` string[]
    - `models` string[]
    - `tools` string[]
    - `skills` string[]
    - `sources` string[]

## Response `200`

Consumption facets and their contextual availability

- object
  - `period` object, required
    - `startDate` string, date-time, required
    - `endDate` string, date-time, required
  - `facets` object, required
    - `agent` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `user` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `api_key` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `group` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `model` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `tool` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `skill` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.
    - `source` PrivateConsumptionFacet[], required
      - `value` string, required — Raw indexed value accepted by the corresponding consumption filter.
      - `label` string, required — Human-readable label, falling back to the raw value when its resource was deleted.
      - `pictureUrl` string, nullable, required
      - `icon` string, nullable — Design-system icon name for tool and skill facets when known.
      - `documentCount` integer, required — Number of matching indexed documents after applying the selected period and every other facet.
      - `disabled` boolean, required — Whether selecting this value would produce no matching indexed document.
      - `scope` 'global' | 'visible' | 'hidden' — Current agent scope, when the agent still has accessible configuration metadata.
      - `maker` string — Model maker, for known model facets.
      - `tier` 'cost_efficient' | 'balanced' | 'premium' — Default reasoning-effort tier, for known model facets.

## Other responses

- `400` — Invalid request body
- `403` — Not authorized for this analytics view
- `500` — Failed to retrieve consumption facets

## Changes

- **2026-08-21** `2e785b62895f` — 2 info
  - added the new optional request property `dimensions`
  - added the new optional request property `scope`
- **2026-08-14** `24a308e0da1c` — 2 info
  - added the new optional request property `filter/api_keys`
  - added the required property `facets/api_key` to the response with the `200` status
- **2026-08-12** `41617009c89a` — 1 breaking, 1 warning, 2 info
  - removed the required property `facets/team` from the response with the `200` status
  - removed the request property `filter/teams`
  - added the new optional request property `filter/groups`
  - added the required property `facets/group` to the response with the `200` status
- **2026-08-11** `90cdd6d971e7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/dust-tt/apis/dust-api-documentation/changes/api/w/:wId/analytics/consumption/facets/post.md)

---

[API](https://skmtc.dev/dust-tt/apis/dust-api-documentation.md) · [All operations](https://skmtc.dev/dust-tt/apis/dust-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/dust-tt/dust-api-documentation/revisions/957ecf7d86f2/schema)