> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List team statistics

> Enabled teams ranked by productivity score, with effort, commits, and the previous-period score.

Returns per-team statistics for a reporting period, ranked by descending productivity score. Teams can share members, so team values do not sum to a workspace total. Disabled teams are omitted, and secret teams are omitted for API keys.

Requires workspace Read and Productivity. Repository restrictions do not filter historical member activity. Current and previous team visibility are resolved separately. All visible enabled teams and their members are returned without pagination or truncation. If a response is too large to return, the request fails with `429` and no partial results or continuation token; retrying unchanged does not resolve it.

## Authorization

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `string` *required*

Numeric GitHub ID of the organization or user.

## Query parameters

**from** `string`

Inclusive start (RFC 3339). Supply both `from` and `to`, or neither. When both are omitted, the latest completed interval of the current reporting period is used, or the previous period if none is available. When supplied, must be on or after `0001-01-15T00:00:00Z` and fall on a UTC quarter-hour (minute 00, 15, 30, or 45, zero seconds).

**to** `string`

Exclusive end (RFC 3339). Same quarter-hour rule as `from`. Must be after `from`, and the range can be at most 366 days. A member counts toward a team only if their membership covers all of `[from, to)`.

**effortMode** `string` (default: ALL)

`ALL` counts all tracked activity. `SHIPPED` counts landed activity. Neither measures deployments.

## Response

**teams** `object[]`

Teams sorted by descending `productivityScore.value`, then `engineeringOutputMinutes`. There is no pagination or row limit.

**properties**

**team** `Team`

Team identity and its members for the whole period.

**productivityScore** `object`

Team score with previous-period comparison.

**properties**

**value** `number`

`engineeringOutputMinutes / (workingMinutes * weightedMembers)`. Zero when the denominator is zero.

**previousValue** `number`

Comparison-period score, normalized independently.

**delta** `number`

`value - previousValue`. Zero when previous data is unavailable.

**percentDelta** `number`

Relative change as a percentage (`25` means 25%). Zero when `previousValue` is zero or unavailable.

**engineeringOutputMinutes** `string`

Estimated engineering effort in person-minutes (int64 as string). Zero can mean activity not yet processed.

**commitCount** `string`

Commits for the selected `effortMode` (int64 as string).

**workingMinutes** `string`

Working minutes in the period (int64 as string). Not multiplied by member count.

**weightedMembers** `number`

Sum of member contribution factors, excluding known bots.

**from** `string`

Start of the effective period (RFC 3339).

**to** `string`

End of the effective period (RFC 3339).

**previousFrom** `string`

Start of the comparison period, 7 or 14 days before `from` depending on the workspace schedule.

**previousTo** `string`

End of the comparison period. Equal to `from`.

**timezone** `string`

Workspace IANA timezone used for working minutes.

Previous-period counts and minutes are not scaled to the current period's length. Fields with zero or empty values are omitted from the JSON.

### Team

**id** `string`

GitHub team ID.

**slug** `string`

GitHub team slug.

**displayName** `string`

Current team name.

**description** `string`

Team description, when set.

**privacy** `string`

GitHub team visibility, `closed` or `secret`.

**enabled** `boolean`

Whether the team is enabled in Macroscope.

**nodeId** `string`

GitHub GraphQL node ID.

**members** `object[]`

Members for the whole period, each with `id`, `login`, `displayName`, `avatarUrl`, and `nodeId`, as in [List team memberships](https://docs.macroscope.com/api-reference/endpoint/list-team-memberships.md). A blank display name may use `login` as a fallback. There is no member pagination.

```bash cURL theme={null}
curl --get https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/teamStatistics \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY" \
  --data-urlencode "from=2026-09-14T00:00:00Z" \
  --data-urlencode "to=2026-09-21T00:00:00Z"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/teamStatistics",
    headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
    params={"from": "2026-09-14T00:00:00Z", "to": "2026-09-21T00:00:00Z"},
)
print(r.json())
```

```javascript JavaScript theme={null}
const params = new URLSearchParams({
  from: "2026-09-14T00:00:00Z",
  to: "2026-09-21T00:00:00Z",
});
const res = await fetch(
  `https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/teamStatistics?${params}`,
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "teams": [
    {
      "team": {
        "id": "2001",
        "nodeId": "T_platform",
        "slug": "platform",
        "displayName": "platform",
        "privacy": "closed",
        "enabled": true,
        "members": [
          {
            "id": "1001",
            "login": "alice",
            "avatarUrl": "https://avatars.githubusercontent.com/u/1001?v=4",
            "nodeId": "U_alice"
          }
        ]
      },
      "productivityScore": { "value": 0.5, "previousValue": 0.4, "delta": 0.1, "percentDelta": 25 },
      "engineeringOutputMinutes": "2400",
      "commitCount": "30",
      "workingMinutes": "2400",
      "weightedMembers": 2
    }
  ],
  "from": "2026-09-14T00:00:00Z",
  "to": "2026-09-21T00:00:00Z",
  "previousFrom": "2026-09-07T00:00:00Z",
  "previousTo": "2026-09-14T00:00:00Z",
  "timezone": "America/Los_Angeles"
}
```

```json 401 theme={null}
{ "code": 16, "message": "unauthenticated" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.