---
title: "Query Team Usage Statistics"
method: POST
path: "/stats/team_usage"
tags: ["product:chat"]
---

# Query Team Usage Statistics

`POST /stats/team_usage`

Retrieve team-level usage statistics from the warehouse database.
Returns all 16 metrics grouped by team with cursor-based pagination.

**Date Range Options (mutually exclusive):**
- Use 'month' parameter (YYYY-MM format) for monthly aggregated values
- Use 'start_date'/'end_date' parameters (YYYY-MM-DD format) for daily breakdown
- If neither provided, defaults to current month (monthly mode)

This endpoint is server-side only.

## Request body

- QueryTeamUsageStatsRequest, nullable — Request payload for querying team-level usage statistics from the warehouse database
  - `end_date` string — End date in YYYY-MM-DD format. Used with start_date for custom date range. Returns daily breakdown.
  - `limit` integer — Maximum number of teams to return per page (default: 30, max: 30)
  - `month` string — Month in YYYY-MM format (e.g., '2026-01'). Mutually exclusive with start_date/end_date. Returns aggregated monthly values.
  - `next` string — Cursor for pagination to fetch next page of teams
  - `start_date` string — Start date in YYYY-MM-DD format. Used with end_date for custom date range. Returns daily breakdown.

## Response `201`

Query Team Usage Stats Response

- QueryTeamUsageStatsResponse, nullable — Response containing team-level usage statistics
  - `duration` string, required — Duration of the request in milliseconds
  - `next` string — Cursor for pagination to fetch next page
  - `teams` TeamUsageStats[], required — Array of team usage statistics
    - `concurrent_connections` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `concurrent_users` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `image_moderations_daily` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `messages_daily` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `messages_last_24_hours` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `messages_last_30_days` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `messages_month_to_date` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `messages_total` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `team` string, required — Team identifier (empty string for users not assigned to any team)
    - `translations_daily` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_daily` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_engaged_last_30_days` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_engaged_month_to_date` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_last_24_hours` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_last_30_days` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_month_to_date` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value
    - `users_total` MetricStats, required — Statistics for a single metric with optional daily breakdown
      - `daily` DailyValue[] — Per-day values (only present in daily mode)
        - `date` string, required — Date in YYYY-MM-DD format
        - `value` integer, required — Metric value for this date
      - `total` integer, required — Aggregated total value

## Other responses

- `400` — Bad request
- `429` — Too many requests

---

[API](https://skmtc.net/getstream/apis/stream-api.md) · [All operations](https://skmtc.net/getstream/apis/stream-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getstream/stream-api/versions/3dba86aaa0d8/schema)