# Connectors ## Get Connector Usage ### Query parameters ### Returns ### Example #### Response (200) ## Domain types ### Beta Connector Usage
The whole hunk
354 lines, new page
/
lines
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Connectors
url: https://platform.claude.com/docs/en/api/beta/organization/analytics/connectors
---
# Connectors
## Get Connector Usage
**GET** `/v1/organizations/analytics/connectors`
Get per-connector usage for a given day, with cursor-based pagination.
Returns connector usage metrics for the organization, sorted by connector
name. Connector names are normalized from their various sources — for
example, "Atlassian MCP server" and "mcp-atlassian" both appear as
"atlassian". Use `group_by[]` to break usage out per member, per RBAC
group, or per product surface, and `filter[]` to scope results; the
parameter descriptions list the supported dimensions. Available to
organizations on a Claude Enterprise plan. Requires an API key with the
`read:analytics` scope.
### Query parameters
- `date: optional string`
UTC date in YYYY-MM-DD format. The day to get connector 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.
format: date
- `ending_date: optional string`
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`.
format: date
- `filter: optional array of string`
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: `connector_name`, `product`, `rbac_group_id`, `user_id`. Value forms: `connector_name` matches case-insensitively, a display name such as 'GitHub MCP' also matches its normalized stored form ('github'), and for rows whose `connector_name` is an opaque connector id the connector's display name (`connector_display_name`) also matches; `product` is one of `chat`, `claude_code`, `cowork`, or `office_agent`; `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.
maxItems: 100
- `group_by: optional array of "product" or "rbac_group_id" or "user_id"`
Dimensions to break results out by (e.g. `group_by[]=user_id`). Supported on this endpoint: `product`, `rbac_group_id`, `user_id`. 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.
maxItems: 100
- `"product"`
- `"rbac_group_id"`
- `"user_id"`
- `limit: optional number`
Number of results per page (1-1000, default 100).
minimum: 1, maximum: 1000
- `order: optional "asc" or "desc"`
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.
- `"asc"`
- `"desc"`
- `order_by: optional string`
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).
- `page: optional string`
Opaque cursor from a previous response's `next_page` field.
- `starting_date: optional string`
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.
format: date
### Returns
- `BetaConnectorUsage object`
Response for GET /v1/organizations/analytics/connectors.
- `data: array of object`
- `chat_metrics: object`
Claude.ai activity metrics for a single connector on a given day.
- `distinct_conversation_connector_used_count: number or null`
Number of distinct conversations in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `claude_code_metrics: object`
Claude Code activity metrics for a single connector on a given day.
- `distinct_session_connector_used_count: number or null`
Number of distinct Claude Code sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `connector_name: string`
Name of the connector. Some rows carry an opaque connector id here instead of a readable name; `connector_display_name` holds the resolved name for those rows.
- `cowork_metrics: object`
Cowork activity metrics for a single connector on a given day.
- `distinct_session_connector_used_count: number or null`
Number of distinct Cowork sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `distinct_user_count: number`
Number of distinct users who used the connector 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.
- `office_metrics: object`
Office Agent activity metrics for a single connector on a given day, broken out by Office product.
- `excel: BetaConnectorOfficeProductMetrics`
Office Agent activity metrics for a single connector on a given day within one Office product.
- `distinct_session_connector_used_count: number or null`
Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `outlook: BetaConnectorOfficeProductMetrics`
Office Agent activity metrics for a single connector on a given day within one Office product.
- `powerpoint: BetaConnectorOfficeProductMetrics`
Office Agent activity metrics for a single connector on a given day within one Office product.
- `word: BetaConnectorOfficeProductMetrics`
Office Agent activity metrics for a single connector on a given day within one Office product.
- `connector_display_name: optional string or null`
Human-readable display name for rows whose `connector_name` is an opaque connector id rather than a readable name, resolved at request time from the organization's connectors (including connectors that have since been removed). `connector_name` remains the row's stable key for sorting and pagination, and `filter[]=connector_name:{value}` also matches these rows by display name. Display names are not unique, and the same connector's claude.ai usage can appear under a separate row with a readable `connector_name`. Null when `connector_name` is already a readable name, when the id cannot be resolved to one of the organization's connectors, or when display-name resolution is not enabled for this organization.
- `individual_auth_distinct_user_count: optional number or null`
Number of distinct users whose use of this connector on the requested day ran on their own individual credential, connected through their own consent flow. Companion bucket to `managed_auth_distinct_user_count`, which carries the measurement, attribution, and null rules. Users whose requests used no stored credential count in neither bucket.
- `managed_auth_distinct_user_count: optional number or null`
Number of distinct users whose use of this connector on the requested day ran on Enterprise Managed Auth (an organization-managed credential provisioned through the organization's identity provider), read from the token record each request used. Null, never 0, when managed-auth reporting is not enabled for the organization, the value cannot be attributed to the row, no credentialed requests and no managed-token mint events (a managed credential being provisioned for a user's use of the connector) were observed that day, or the day predates 2026-07-01, the first day the backing data exists (forward-only data, no backfill). When credentialed requests or mint events were observed and attributed, both managed-auth fields populate, reporting 0 for a bucket with no users; the two counts are independent, not a partition — a user whose requests that day used both kinds of credential counts in both. Mint events carry user but not surface attribution, so they count as observed auth activity on `user_id` and `rbac_group_id` cuts — attributed to the user the credential was provisioned for — but never on a cut that references `product` (group or filter). Date-range rollup mode (`starting_date`/`ending_date`) computes both fields exactly over the window — distinct users with at least one qualifying day — when the whole window starts on or after 2026-07-01, with the null-versus-0 and mint-event rules applying with the window in place of the day; a range starting earlier reports every managed-auth field as null, never a partial-window value.
- `product: optional string or null`
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: optional string or null`
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: optional string or null`
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.
- `read_call_count: optional number or null`
Number of connector tool calls on the requested day whose trusted read-only annotation marked them read-only. Call count, not distinct users. Every call recorded on a classified surface lands in exactly one of `read_call_count`, `write_call_count`, or `unclassified_call_count`, so the three sum to the day's classified calls. Classification is forward-only per surface: claude.ai from 2026-06-01, Claude Code from 2026-05-30, Claude in Office from 2026-05-29, Cowork from 2026-06-02 (Cowork clients predating annotation forwarding land in `unclassified_call_count`). Null, never 0, when the value cannot be stated: the read/write split is not enabled for this organization, or the day predates 2026-05-29. For a date-range total, sum the per-day values, but treat a window that extends before 2026-05-29 as null rather than summing only its covered days — date-range rollup mode (`starting_date`/`ending_date`) applies both rules server-side.
- `unclassified_call_count: optional number or null`
Number of connector tool calls on the requested day with no trusted read-only annotation — the annotation is optional in the MCP spec and is discarded when connector access controls are active, so unclassified calls are common. This field shows how much of the day's classified activity the read/write split actually covers. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance.
- `user_id: optional string or null`
Tagged user identifier (e.g. `user_...`). Present only when the request grouped by `user_id`.
- `write_call_count: optional number or null`
Number of connector tool calls on the requested day whose trusted read-only annotation marked them not read-only. Call count, not distinct users. One of the three call-classification buckets; see `read_call_count` for the per-surface data-start dates, null conditions, and date-range guidance.
- `next_page: string or null`
Opaque cursor for the next page, or null if no more results
### Example
```bash
curl https://api.anthropic.com/v1/organizations/analytics/connectors \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response (200)
```json
{
"data": [
{
"chat_metrics": {
"distinct_conversation_connector_used_count": 0
},
"claude_code_metrics": {
"distinct_session_connector_used_count": 0
},
"connector_name": "connector_name",
"cowork_metrics": {
"distinct_session_connector_used_count": 0
},
"distinct_user_count": 0,
"office_metrics": {
"excel": {
"distinct_session_connector_used_count": 0
},
"outlook": {
"distinct_session_connector_used_count": 0
},
"powerpoint": {
"distinct_session_connector_used_count": 0
},
"word": {
"distinct_session_connector_used_count": 0
}
},
"connector_display_name": "connector_display_name",
"individual_auth_distinct_user_count": 0,
"managed_auth_distinct_user_count": 0,
"product": "product",
"rbac_group_id": "rbac_group_id",
"rbac_group_name": "rbac_group_name",
"read_call_count": 0,
"unclassified_call_count": 0,
"user_id": "user_id",
"write_call_count": 0
}
],
"next_page": "next_page"
}
```
## Domain types
### Beta Connector Usage
- `BetaConnectorUsage object`
Response for GET /v1/organizations/analytics/connectors.
- `data: array of object`
- `chat_metrics: object`
Claude.ai activity metrics for a single connector on a given day.
- `distinct_conversation_connector_used_count: number or null`
Number of distinct conversations in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `claude_code_metrics: object`
Claude Code activity metrics for a single connector on a given day.
- `distinct_session_connector_used_count: number or null`
Number of distinct Claude Code sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `connector_name: string`
Name of the connector. Some rows carry an opaque connector id here instead of a readable name; `connector_display_name` holds the resolved name for those rows.
- `cowork_metrics: object`
Cowork activity metrics for a single connector on a given day.
- `distinct_session_connector_used_count: number or null`
Number of distinct Cowork sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `distinct_user_count: number`
Number of distinct users who used the connector 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.
- `office_metrics: object`
Office Agent activity metrics for a single connector on a given day, broken out by Office product.
- `excel: BetaConnectorOfficeProductMetrics`
Office Agent activity metrics for a single connector on a given day within one Office product.
- `distinct_session_connector_used_count: number or null`
Number of distinct Office Agent sessions in which the connector was used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
- `outlook: BetaConnectorOfficeProductMetrics`
Cut at 300 lines. The page has the rest.