Repository Public
1---2title: Plugins3url: https://platform.claude.com/docs/en/api/beta/organization/analytics/plugins4---56# Plugins78## Get Plugin Usage910**GET** `/v1/organizations/analytics/plugins`1112Get per-plugin install + invocation usage for a given day, with pagination.1314Returns plugin usage metrics for the organization across Cowork and Claude15Code, sorted by plugin name. The `plugin_name` value `third-party` is16an aggregate bucket, not a plugin: it collects plugin activity, from17either surface, for which the reporting client did not provide a plugin18name — so an organization's own plugins can contribute both to their own19named rows and to this bucket. Use `group_by[]` to break usage out per20member, per RBAC group, or per product surface (Cowork / Claude Code),21and `filter[]` to scope results; the parameter descriptions list the22supported dimensions. Requires an API key with the23`read:analytics` scope. `starting_date` / `ending_date` select24range-rollup mode like `/skills`.2526### Query parameters2728- `date: optional string`2930 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.3132 format: date3334- `ending_date: optional string`3536 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`.3738 format: date3940- `filter: optional array of string`4142 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.4344 maxItems: 1004546- `group_by: optional array of "product" or "rbac_group_id" or "user_id"`4748 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.4950 maxItems: 1005152 - `"product"`5354 - `"rbac_group_id"`5556 - `"user_id"`5758- `limit: optional number`5960 Number of results per page (1-1000, default 100).6162 minimum: 1, maximum: 10006364- `order: optional "asc" or "desc"`6566 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.6768 - `"asc"`6970 - `"desc"`7172- `order_by: optional string`7374 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).7576- `page: optional string`7778 Opaque cursor from a previous response's `next_page` field.7980- `starting_date: optional string`8182 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.8384 format: date8586### Returns8788- `BetaPluginUsage object`8990 Response for GET /v1/organizations/analytics/plugins.9192 - `data: array of object`9394 - `claude_code_metrics: object`9596 Claude Code activity metrics for a single plugin on a given day.9798 - `distinct_session_plugin_used_count: number or null`99100 Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.101102 - `cowork_metrics: object`103104 Cowork activity metrics for a single plugin on a given day.105106 - `distinct_session_plugin_used_count: number or null`107108 Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.109110 - `distinct_user_count: number`111112 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.113114 - `install_count: number or null`115116 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.117118 - `invocation_count: number`119120 Number of plugin invocations on the requested day121122 - `plugin_name: string`123124 Name of the plugin125126 - `plugin_id: optional string or null`127128 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.129130 - `product: optional string or null`131132 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`.133134 - `rbac_group_id: optional string or null`135136 Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`.137138 - `rbac_group_name: optional string or null`139140 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.141142 - `user_id: optional string or null`143144 Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`.145146 - `next_page: string or null`147148 Opaque cursor for the next page, or null if no more results149150### Example151152```bash153curl https://api.anthropic.com/v1/organizations/analytics/plugins \154 -H 'anthropic-version: 2023-06-01' \155 -H "X-Api-Key: $ANTHROPIC_API_KEY"156```157158#### Response (200)159160```json161{162 "data": [163 {164 "claude_code_metrics": {165 "distinct_session_plugin_used_count": 0166 },167 "cowork_metrics": {168 "distinct_session_plugin_used_count": 0169 },170 "distinct_user_count": 0,171 "install_count": 0,172 "invocation_count": 0,173 "plugin_name": "plugin_name",174 "plugin_id": "plugin_id",175 "product": "product",176 "rbac_group_id": "rbac_group_id",177 "rbac_group_name": "rbac_group_name",178 "user_id": "user_id"179 }180 ],181 "next_page": "next_page"182}183```184185## Domain types186187### Beta Plugin Usage188189- `BetaPluginUsage object`190191 Response for GET /v1/organizations/analytics/plugins.192193 - `data: array of object`194195 - `claude_code_metrics: object`196197 Claude Code activity metrics for a single plugin on a given day.198199 - `distinct_session_plugin_used_count: number or null`200201 Number of distinct Claude Code sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.202203 - `cowork_metrics: object`204205 Cowork activity metrics for a single plugin on a given day.206207 - `distinct_session_plugin_used_count: number or null`208209 Number of distinct Cowork sessions in which the plugin was invoked. Null on aggregated rows where a distinct count cannot be computed.210211 - `distinct_user_count: number`212213 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.214215 - `install_count: number or null`216217 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.218219 - `invocation_count: number`220221 Number of plugin invocations on the requested day222223 - `plugin_name: string`224225 Name of the plugin226227 - `plugin_id: optional string or null`228229 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.230231 - `product: optional string or null`232233 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`.234235 - `rbac_group_id: optional string or null`236237 Tagged RBAC group identifier (`rbac_group_...`), matching the spend-limits API spelling. Present only when the request grouped by `rbac_group_id`.238239 - `rbac_group_name: optional string or null`240241 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.242243 - `user_id: optional string or null`244245 Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`.246247 - `next_page: string or null`248249 Opaque cursor for the next page, or null if no more results250