> ## 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.

# Get workspace report

> Sprint report with per-area summaries, estimated effort, and comparisons to the previous sprint.

Returns an existing sprint report for the workspace, with per-area summaries, estimated effort, and sprint-over-sprint comparisons. Reports are workspace-wide and are not generated or refreshed by this call.

> [!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=WORKSPACE_REPORT`. Pass a returned period's `from` and `to` to this endpoint. The report may select a later completed end for the same start, so read `toDate` in the response for the actual end.

Requires workspace Read. Productivity insights appear only with Productivity permission. Repository restrictions do not filter this report, and historical activity from disconnected repositories can contribute. Empty areas or zero totals do not certify that all activity has been processed; there is no completeness/readiness indicator.

## 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 period start (RFC 3339). Send both `from` and `to`, or neither. When both are omitted, the current sprint's report is returned, or the previous sprint's if none is available.

**to** `string`

Exclusive period end (RFC 3339), later than `from`, at most 366 days after it. The latest complete report with the same start is returned, so `toDate` can differ from `to`.

**areaId** `string`

Area ID (UUID) from List areas. Scopes totals and comparisons to one area. Omit to include all areas and uncategorized work.

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

`all` counts all tracked effort. `shipped` counts shipped effort only and returns zero totals when shipped effort is unavailable. Summaries are the same in both modes.

## Response

Use `previous` and `next` to navigate history. An explicit start with no completed report returns `404`; choose an available start with [List workspace reporting periods](https://docs.macroscope.com/api-reference/endpoint/list-workspace-reporting-periods.md) rather than retrying the same range. An existing report can return empty areas and zero totals when no activity matches. Metric fields equal to zero are omitted.

**fromDate** `string`

Inclusive start of the returned period (RFC 3339).

**toDate** `string`

Exclusive end of the returned period (RFC 3339). Can differ from the requested `to`.

**areaReports** `object[]`

One entry per area, sorted by effort descending.

**properties**

**area** `object`

Omitted for uncategorized work.

**properties**

**areaId** `string`

Area ID (UUID).

**name** `string`

Area display name.

**description** `string`

Area description.

**validFrom** `string`

When this area definition took effect (RFC 3339).

**summary** `string`

Summary of the area's work, in Markdown.

**engOutputStats** `EffortStats`

Effort, commits, and share of total effort for this area.

**focusBreakdown** `object`

Effort grouped by summary heading. Omitted when unavailable.

**properties**

**totalMinutes** `integer`

Estimated person-minutes across all buckets.

**totalCommitCount** `integer`

Commits across all buckets.

**buckets** `object[]`

**properties**

**heading** `string`

Summary heading for this group of work.

**minutes** `integer`

Estimated person-minutes for this heading.

**commitCount** `integer`

Commits for this heading.

**contributorGithubIds** `string[]`

GitHub user IDs of contributors. Treat as strings.

**uncategorized** `boolean`

`true` for the uncategorized bucket.

**engOutputStats** `EffortStats`

Totals across the selected areas.

**sprintStats** `object`

**properties**

**elapsedSprintHours** `number`

Working hours in the requested interval, before any adjustment to `toDate`. For explicit dates this runs to `to`, not to now.

**totalSprintHours** `number`

Working hours in the full sprint.

**productivityInsights** `string[]`

Workspace-level insights. Omitted without productivity access. Not recomputed for `areaId` or `effortMode`.

**previous** `Period`

Previous full sprint. Omitted when none exists.

**next** `Period`

Next recorded sprint. Omitted when none exists.

### EffortStats

**totalPersonMinutes** `Metric`

Estimated person-minutes, not wall-clock time.

**totalCommitCount** `Metric`

Commits attributed to the effort.

**focus** `Metric`

Share of the report's total effort, 0 to 100.

### Metric

**value** `number`

Value for this period.

**previousValue** `number`

Value for the previous sprint. Zero when unavailable.

**delta** `number`

`value - previousValue`.

**percentDelta** `number`

Percent change. Zero when `previousValue` is zero.

### Period

**from** `string`

Inclusive start (RFC 3339).

**to** `string`

Exclusive end (RFC 3339).

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

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

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/workspaceReport",
    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/workspaceReport?${params}`,
  { headers: { Authorization: `Bearer ${process.env.MACROSCOPE_API_KEY}` } }
);
console.log(await res.json());
```

```json 200 theme={null}
{
  "fromDate": "2026-09-14T00:00:00Z",
  "toDate": "2026-09-21T00:00:00Z",
  "areaReports": [
    {
      "area": {
        "areaId": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b01",
        "name": "Payments",
        "description": "Checkout, invoicing, and payment processing.",
        "validFrom": "2026-08-01T00:00:00Z"
      },
      "summary": "## Checkout retries\nAdded idempotent retries to card authorization.",
      "engOutputStats": {
        "totalPersonMinutes": {
          "value": 6000,
          "previousValue": 5000,
          "delta": 1000,
          "percentDelta": 20
        },
        "totalCommitCount": {
          "value": 40,
          "previousValue": 50,
          "delta": -10,
          "percentDelta": -20
        },
        "focus": {
          "value": 60,
          "previousValue": 50,
          "delta": 10,
          "percentDelta": 20
        }
      },
      "focusBreakdown": {
        "totalMinutes": 6000,
        "totalCommitCount": 40,
        "buckets": [
          {
            "heading": "Checkout retries",
            "minutes": 4200,
            "commitCount": 28,
            "contributorGithubIds": ["1000001", "1000002"]
          },
          {
            "heading": "Invoice exports",
            "minutes": 1800,
            "commitCount": 12,
            "contributorGithubIds": ["1000003"]
          }
        ]
      }
    }
  ],
  "engOutputStats": {
    "totalPersonMinutes": {
      "value": 10000,
      "previousValue": 10000
    },
    "totalCommitCount": {
      "value": 75,
      "previousValue": 70,
      "delta": 5,
      "percentDelta": 7.14
    },
    "focus": {
      "value": 100,
      "previousValue": 100
    }
  },
  "sprintStats": {
    "elapsedSprintHours": 40,
    "totalSprintHours": 40
  },
  "productivityInsights": [
    "Commit volume rose 7% while estimated effort held flat."
  ],
  "previous": {
    "from": "2026-09-07T00:00:00Z",
    "to": "2026-09-14T00: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.