> ## 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 contributor statistics

> Contributors ranked by productivity score, with effort, commits, and pull requests compared to the previous period.

Returns per-contributor statistics for a reporting period, ranked by descending productivity score. Aggregates are workspace-wide and are not filtered by repository.

> [!NOTE]
>
> To choose a date range, use [List workspace reporting periods](https://docs.macroscope.com/api-reference/endpoint/list-workspace-reporting-periods.md) (`GET /reportingPeriods`) with `operation=CONTRIBUTOR_STATISTICS`. Pass a returned period's `from` and `to` to this endpoint. Discovery is guidance, not an exhaustive list of accepted ranges: partial or gapped ranges are also accepted. The current period can extend beyond the discovered end; read `from` and `to` in the response for the range actually used.

Requires workspace Read and Productivity. Historical activity from inaccessible repositories can contribute; external-contributor inclusion follows the workspace setting. Secret-team associations are omitted for API keys without removing those contributors or changing their statistics.

## 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). If `from` or `to` is omitted, both are ignored and the latest available portion of the current reporting period is used, or the previous period if the current one has no elapsed working hours. When both are supplied, each must fall on a UTC quarter-hour (minute 00, 15, 30, or 45, zero seconds), and `from` must be on or after `0001-01-15T00:00:00Z`. Values are not rounded.

**to** `string`

End (RFC 3339). Must be after `from`, and the range can be at most 366 days. Commits at either endpoint are included, so adjacent ranges can overlap. If `from` is the start of the current reporting period, the effective end can extend to the latest processed data. Read `from` and `to` in the response for the period actually used.

**limit** `integer`

Maximum number of contributors to return, applied after ranking. Omit for all contributors. `0` returns none. Does not affect `workingMinutes`. There is no pagination.

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

`all` counts all tracked activity. `shipped` counts landed activity and accounts for squashed commits. Neither measures deployments.

## Response

**contributors** `object[]`

Contributors sorted by descending `productivityScore.value`. Tie order is not guaranteed.

**properties**

**contributor** `Contributor`

GitHub identity. Omitted when unavailable; statistics are still returned.

**contributorType** `string`

`FullTime`, `PartTime`, `Occasional`, `Bot`, `KnownBot`, `Agent`, or `Unverified`.

**productivityScore** `Metric`

Engineering effort normalized by the contributor's working minutes. Dimensionless.

**engineeringOutputMinutes** `Metric`

Estimated engineering effort in person-minutes.

**commitCount** `Metric`

Commits for the selected `effortMode`.

**pullRequestCount** `Metric`

Pull requests for the selected `effortMode`.

**contributionFactor** `number`

Weighting factor applied to the contributor.

**weeklyWorkingHours** `number`

Configured maximum working hours per week, not hours worked.

**includeEngineeringOutput** `boolean`

Whether the contributor counts toward engineering output totals.

**shippedNotReady** `boolean`

`true` when this contributor's current-period shipped metrics are not ready yet.

**teams** `Team[]`

Teams the contributor belonged to during the period. Secret teams are omitted for API keys.

**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 calendar and working-time calculations.

**workingMinutes** `string`

Workspace working minutes in the period (int64 as string). Not summed contributor effort.

**previousWorkingMinutes** `string`

Workspace working minutes in the comparison period (int64 as string).

**dataAsOf** `string`

Oldest calculation time for current-period data (RFC 3339). Not a completeness guarantee.

**historyUpdating** `boolean`

`true` when part of either period is still being processed. Results can change.

**shippedNotReady** `boolean`

`true` when shipped metrics for either period are not ready yet.

An empty `contributors` list can mean no activity, shipped metrics not ready, or `limit=0`. Fields with `false`, zero, or empty values are omitted from the JSON.

### Metric

**value** `number`

Current-period value.

**previousValue** `number`

Comparison-period value. Counts and minutes are scaled to the current period's length, so they can be fractional. Scores are 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.

### Contributor

**id** `string`

GitHub user ID.

**login** `string`

GitHub username.

**displayName** `string`

GitHub display name, when set.

**avatarUrl** `string`

GitHub avatar URL.

**nodeId** `string`

GitHub GraphQL node ID.

### Team

**id** `string`

GitHub team ID.

**slug** `string`

GitHub team slug.

**displayName** `string`

Team name.

**description** `string`

Team description, when set.

**privacy** `string`

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

**enabled** `boolean`

Whether team metrics are enabled for this team in **Settings → Teams**.

**nodeId** `string`

GitHub GraphQL node ID.

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

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

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

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

```json 200 theme={null}
{
  "contributors": [
    {
      "contributor": {
        "id": "1001",
        "login": "alice",
        "avatarUrl": "https://avatars.githubusercontent.com/u/1001?v=4",
        "nodeId": "U_alice"
      },
      "contributorType": "FullTime",
      "productivityScore": { "value": 0.42, "previousValue": 0.35, "delta": 0.07, "percentDelta": 20 },
      "engineeringOutputMinutes": { "value": 1200, "previousValue": 1000, "delta": 200, "percentDelta": 20 },
      "commitCount": { "value": 24, "previousValue": 20, "delta": 4, "percentDelta": 20 },
      "pullRequestCount": { "value": 6, "previousValue": 5, "delta": 1, "percentDelta": 20 },
      "contributionFactor": 1,
      "weeklyWorkingHours": 40,
      "includeEngineeringOutput": true,
      "teams": [
        {
          "id": "2001",
          "nodeId": "T_platform",
          "slug": "platform",
          "displayName": "platform",
          "privacy": "closed",
          "enabled": true
        }
      ]
    }
  ],
  "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",
  "workingMinutes": "2400",
  "previousWorkingMinutes": "2400",
  "dataAsOf": "2026-09-21T06:00:00Z"
}
```

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


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