---
title: "List company user usage"
method: GET
path: "/user-usage-by-company/users"
tags: ["entitlements"]
---

# List company user usage

`GET /user-usage-by-company/users`

## Query parameters

- `company_id` string, required — Company to break usage down for
- `end_time` string, date-time — End of the usage window (exclusive); defaults to now
- `feature_id` string — The event-based feature to break down; required when metric is feature
- `metric` 'credits' | 'feature', required
- `limit` integer — Page limit (default 100)
- `offset` integer — Page offset (default 0)
- `start_time` string, date-time — Start of the usage window; defaults to 30 days before the end

## Response `200`

OK

- object
  - `data` CompanyUserUsageResponseData, required
    - `end_time` string, date-time, required — End of the usage window (exclusive)
    - `rows` CompanyUserUsageRowResponseData[], required — This page of per-user consumption within the window, heaviest first
      - `last_seen` string, date-time, nullable — When the user last used the feature within the window; null for the credits metric, which aggregates balances rather than timestamped events
      - `share` number, double, required — This row's fraction (0-1) of consumption within the window, including unattributed consumption
      - `user` UserResponseData
        - `created_at` string, date-time, required
        - `environment_id` string, required
        - `id` string, required
        - `last_seen_at` string, date-time, nullable
        - `name` string, required
        - `updated_at` string, date-time, required
      - `user_id` string, nullable — The user the consumption is attributed to; null for unattributed consumption
      - `value` number, double, required — The user's consumption of the metric within the window
    - `start_time` string, date-time, required — Start of the usage window
    - `top_user_share` number, double, required — The heaviest user's fraction (0-1) of consumption, measured across every user in the window and not just this page
    - `total` number, double, required — Consumption across every user in the window including unattributed, not just this page
    - `unattributed` CompanyUserUsageRowResponseData
      - `last_seen` string, date-time, nullable — When the user last used the feature within the window; null for the credits metric, which aggregates balances rather than timestamped events
      - `share` number, double, required — This row's fraction (0-1) of consumption within the window, including unattributed consumption
      - `user` UserResponseData
        - `created_at` string, date-time, required
        - `environment_id` string, required
        - `id` string, required
        - `last_seen_at` string, date-time, nullable
        - `name` string, required
        - `updated_at` string, date-time, required
      - `user_id` string, nullable — The user the consumption is attributed to; null for unattributed consumption
      - `value` number, double, required — The user's consumption of the metric within the window
  - `params` object, required — Input parameters
    - `company_id` string — Company to break usage down for
    - `end_time` string, date-time — End of the usage window (exclusive); defaults to now
    - `feature_id` string — The event-based feature to break down; required when metric is feature
    - `limit` integer — Page limit (default 100)
    - `metric` 'credits' | 'feature'
    - `offset` integer — Page offset (default 0)
    - `start_time` string, date-time — Start of the usage window; defaults to 30 days before the end

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

## Changes

- **2026-09-28** `eb32b6d1c979` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/schematichq/apis/schematic-api/changes/user-usage-by-company/users/get.md)

---

[API](https://skmtc.dev/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/schematichq/apis/schematic-api/revisions/2c923705baad?raw)