---
title: "Get Plugin Usage"
method: GET
path: "/v1/organizations/analytics/plugins?beta=true"
---

# Get Plugin Usage

`GET /v1/organizations/analytics/plugins?beta=true`

Get per-plugin install + invocation usage for a given day, with pagination.

Returns plugin usage metrics for the organization across Cowork and Claude
Code, sorted by plugin name. The `plugin_name` value `third-party` is
an aggregate bucket, not a plugin: it collects plugin activity, from
either surface, for which the reporting client did not provide a plugin
name — so an organization's own plugins can contribute both to their own
named rows and to this bucket. Use `group_by[]` to break usage out per
member, per RBAC group, or per product surface (Cowork / Claude Code),
and `filter[]` to scope results; the parameter descriptions list the
supported dimensions. Requires an API key with the
`read:analytics` scope. `starting_date` / `ending_date` select
range-rollup mode like `/skills`.

## Query parameters

- `date` string, date, nullable — UTC date in YYYY-MM-DD format. The day to get plugin usage for. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
- `starting_date` string, date, nullable — UTC date in YYYY-MM-DD format. Start of a date range (inclusive). Enables rollup mode: one row per entity aggregated over the whole range — addable counters are summed across days, and a distinct count is never summed where summing could double-count (a field's range value is recomputed exactly over the window, approximate via HLL with typical error under 2%, null, or — for the creation-event counts, whose per-day values cannot overlap — a per-day sum that is itself exact; each field's own description says which). Use either `date` or `starting_date`, not both. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day) and may be revised by a few percent over the following days. No earlier than 2026-01-01.
- `ending_date` string, date, nullable — UTC date in YYYY-MM-DD format. End of the date range (exclusive); only valid with `starting_date`. Data is typically available with a 1-day lag (varies by query; the error for a too-recent date names the latest available day), so this can be at most today — which is also the default when omitted, resolved once when the first page is served and reused for the rest of the pagination sequence. At most 366 days after `starting_date`.
- `limit` integer, nullable — Number of results per page (1-1000, default 100).
- `page` string, nullable — Opaque cursor from a previous response's `next_page` field.
- `group_by[]` string[], nullable — Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. On this endpoint `product` takes the values `claude_code` or `cowork` only (the surfaces with plugin attribution). Grouped rows carry the requested dimension values as additional fields and paginate like ungrouped responses via `next_page`; an unsupported dimension returns 400. `rbac_group_id` attributes a user to every group they held at any point during each covered UTC day, so grouped rows are not an exclusive partition and can sum above org-level totals. At most 100 entries.
- `filter[]` string[], nullable — Filters as `dimension:value`, e.g. `filter[]=rbac_group_id:{id}`. Repeat the param for OR within a dimension and across dimensions for AND. Supported dimensions on this endpoint: `plugin_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `plugin_name` matches case-insensitively; `product` is `claude_code` or `cowork` (the only surfaces with plugin attribution); `rbac_group_id` takes the tagged id (`rbac_group_...`, as emitted in responses and by the spend-limits API) or a bare group UUID, and matches users who held the group at any point during each covered UTC day (time-of-usage attribution); `user_id` takes a tagged user id (`user_...`), as emitted in responses. An unsupported dimension returns 400. At most 100 entries.
- `order_by` string, nullable — Sort field. Restricted to the endpoint's sort column plus its rankable metrics (metrics default to descending; a few metrics rank in date-range mode only, per the endpoint's documented orderable set).
- `order` 'asc' | 'desc', nullable — Sort direction: `asc` or `desc`. Defaults to `asc` for the endpoint's sort column and to `desc` when `order_by` names a metric (a top-N ranking). Applies to `order_by`, or to the endpoint's default sort field when `order_by` is omitted.

## Headers

- `x-api-key` string, nullable

## Response `200`

Successful Response

- BetaAnalyticsPluginsResponse — Response for GET /v1/organizations/analytics/plugins.
  - `data` BetaAnalyticsPluginActivity[], required
    - `claude_code_metrics` BetaAnalyticsPluginClaudeCodeMetrics, required — Claude Code activity metrics for a single plugin on a given day.
      - `distinct_session_plugin_used_count` integer, nullable, required — Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
    - `cowork_metrics` BetaAnalyticsPluginCoworkMetrics, required — Cowork activity metrics for a single plugin on a given day.
      - `distinct_session_plugin_used_count` integer, nullable, required — Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.
    - `distinct_user_count` integer, required — Number of distinct users with recorded install or invocation activity for the plugin on the requested day (install-only users count), or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
    - `install_count` integer, nullable, required — Number of distinct users who installed the plugin on the requested day, or, in date-range mode, over the requested window — recomputed as an exact distinct count over the window's per-member daily rows, never a sum of per-day values.
    - `invocation_count` integer, required — Number of plugin invocations on the requested day
    - `plugin_id` string, nullable — Stable plugin identifier when available (e.g. `serena@claude-plugins-official`). Null for third-party Claude Code plugins (redacted at the source) and Cowork slash commands that carry only a hashed id.
    - `plugin_name` string, required — Name of the plugin
    - `product` string, nullable — Product that produced this row's activity: one of `chat`, `claude_code`, `cowork`, or `office_agent` (the canonical Cost & Usage product naming; an `office_agent` row's per-surface breakdown is in its `office_metrics`). On `/plugins` only `cowork` and `claude_code` occur (the only surfaces with plugin attribution); on `/artifacts` only `chat`, `claude_code`, and `cowork` occur (the surfaces that create artifacts); `/apps/chat/projects` does not support the product dimension (a `product` entry in `group_by[]` or `filter[]` there is rejected). Present only when the request grouped by `product`.
    - `rbac_group_id` string, nullable — Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`.
    - `rbac_group_name` string, nullable — Resolved RBAC group display name, alongside `rbac_group_id` when name resolution is available. Null if the group has been deleted or its name could not be resolved; `rbac_group_id` remains the stable key.
    - `user_id` string, nullable — Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`.
  - `next_page` string, nullable, required — Opaque cursor for the next page, or null if no more results

## Other responses

- `400` — Invalid argument - The client specified an invalid argument
- `401` — Unauthenticated - The request does not have valid authentication credentials
- `403` — Permission denied - The caller does not have permission to execute the specified operation
- `404` — Not found - Some requested entity was not found
- `408` — Deadline exceeded - The deadline expired before the operation could complete
- `409` — Aborted - The operation was aborted due to concurrency issue
- `412` — Failed precondition - Operation was rejected because the system is not in required state
- `413` — Out of range - Operation was attempted past the valid range
- `429` — Resource exhausted - Some resource has been exhausted (rate limiting)
- `431` — Request header fields too large - Request metadata was too large
- `499` — Cancelled - The operation was cancelled by the client
- `500` — Internal - Internal server error
- `501` — Unimplemented - The operation is not implemented or supported
- `503` — Unavailable - The service is currently unavailable
- `504` — Deadline exceeded - Upstream service did not respond in time
- `529` — Overloaded - The service is temporarily overloaded

## Changes

- **2026-09-02** `1bb7c7a0a4a9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/anthropics/apis/anthropic-api/changes/v1/organizations/analytics/plugins?beta=true/get.md)

---

[API](https://skmtc.dev/anthropics/apis/anthropic-api.md) · [All operations](https://skmtc.dev/anthropics/apis/anthropic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/anthropics/apis/anthropic-api/revisions/1bb7c7a0a4a9?raw)