> ## 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 workspace reporting periods

> Find available reporting periods for workspace reports and contributor statistics.

Lists reporting periods with processed data available for [Get workspace report](https://docs.macroscope.com/api-reference/endpoint/get-workspace-report.md) or [List contributor statistics](https://docs.macroscope.com/api-reference/endpoint/list-contributor-statistics.md). Set `operation` to the endpoint you plan to call, then pass a returned period's `from` and `to` to that endpoint.

Omit the dates to use the default reporting period, or supply a date range to find historical periods. Results include at most one period per scheduled reporting cycle (sprint), ordered from oldest to newest. A period can cover only part of a sprint.

> [!NOTE]
>
> Discovery reflects currently processed data, not all historical availability or a completeness guarantee. An empty result does not establish zero activity. Windows and results can change as history is processed.

## Authorization

Requires workspace Read, plus Productivity when `operation` is `CONTRIBUTOR_STATISTICS`. API keys can access only their bound workspace.

**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, as a string. Must match the key's workspace.

## Query parameters

**operation** `string` *required*

`WORKSPACE_REPORT` or `CONTRIBUTOR_STATISTICS`. There is no default; `REPORTING_PERIOD_OPERATION_UNSPECIFIED` is invalid.

**from** `string`

Inclusive lower bound on returned period starts (RFC 3339). Must be on or after `0001-01-16T00:00:00Z`. Omit both dates to use the default reporting period. If only `from` is supplied, the search ends at the server time captured for the first page. See [Date selection](#date-selection).

**to** `string`

Inclusive upper bound on returned period ends (RFC 3339). Requires `from` when supplied. The supplied or server-selected end must be after `from` by at most 366 elapsed 24-hour days, independent of daylight saving time. Returned periods are fully contained within the search bounds.

**pageSize** `integer` (default: 50)

Maximum windows per page, 1 to 200. Explicit `0` is invalid. May change between pages.

**pageToken** `string`

Opaque `nextPageToken` from the preceding page. Repeat the workspace, operation and original date inputs, including which dates were omitted. Do not replace omitted dates with the response's resolved bounds; this invalidates the token. Tokens expire after 24 hours and can be invalidated by key rotation. Invalid, altered, expired or mismatched tokens return `400` without identifying the failed token check; restart without a token.

## Date selection

| Date inputs | Search range |
| - | - |
| Neither `from` nor `to` | The latest completed report interval starting at the current scheduled sprint's start, if it contains working hours; otherwise, the previous full sprint. |
| `from` only | From the supplied start through the server time captured for the first page. The start must be in the past and no more than 366 days earlier. |
| Both `from` and `to` | The supplied range. The end must be after the start, with a maximum span of 366 days. |
| `to` only | Invalid: returns `400` because `from` is required. |

The default follows the workspace's timezone and weekly or biweekly reporting schedule, and can cover only part of the current sprint. For `CONTRIBUTOR_STATISTICS`, the default end can advance to the latest processed effort cutoff if it is later than the report end and no later than the captured server time.

The response's top-level `from` and `to` identify the search range, even when no periods match. Use the dates inside `periods` when calling the selected endpoint. Pagination retains the first page's resolved search range and evaluation time; `pageSize` can change between pages, but the original date inputs must stay the same.

## Window selection

* `WORKSPACE_REPORT` prefers the full-sprint report, otherwise the latest available report for that sprint start. A partial report is marked incomplete even for a past sprint. Get workspace report may select a later completed end for the same start.
* `CONTRIBUTOR_STATISTICS` returns sprint windows with gap-free computed coverage for default all effort, including the full preceding comparison. Windows with coverage gaps are omitted. This is guidance, not an exhaustive list of accepted ranges: List contributor statistics also accepts partial or gapped ranges and can process missing historical data.
* The current contributor sprint ends at its latest usable computed point within the date filter and is incomplete. A subsequent contributor-statistics request may extend beyond that returned end and the discovery filter's upper bound as processing progresses.
* Contributor windows follow the current workspace schedule. Biweekly alignment, completion and end cutoffs use the first page's evaluation time throughout pagination. Data and schedules remain live: backfills, updates, deletions and schedule changes can alter later pages. This is not a snapshot export.

## Response

**from** `string`

Inclusive start of the resolved search range (RFC 3339). Returned even when no periods match; not necessarily the start of a returned period.

**to** `string`

Inclusive end of the resolved search range (RFC 3339). Returned even when no periods match; not necessarily the end of a returned period.

**periods** `object[]`

At most one window per sprint start, in ascending start order. An empty list is omitted from REST JSON; absence means no matching computed windows, not zero historical activity.

**properties**

**from** `string`

Start instant to pass as `from` to the selected operation (RFC 3339).

**to** `string`

End instant to pass as `to` (RFC 3339). A consuming operation may select or extend to a later end as described above.

**timezone** `string`

IANA timezone for calendar comparisons with these explicit boundaries. Calendar durations can vary across daylight saving transitions.

**incomplete** `boolean`

True for the current in-progress sprint or a past report without a full-sprint report. False, omitted in REST JSON, means a finished sprint window—not that all historical events have been processed.

**nextPageToken** `string`

Pass as `pageToken` with the original filters to continue. Omitted when no following page remains. Follow any returned token even on a short or empty page.

## Errors

Invalid dates, operation, page size or token return `400`. Missing credentials return `401`; denied workspace or Productivity access returns `403`; an unavailable workspace returns `404`. Unavailable discovery returns `503`; unexpected failures return `500`. See [shared errors and limits](https://docs.macroscope.com/api#errors).

Equal or reversed dates return `to must be after from`. An explicit range longer than 366 days returns `to must be at most 366 days after from`. With `from` alone, a start more than 366 days before the captured server time returns `from must be within 366 days of now when to is omitted`.

```bash Explicit date range theme={null}
curl "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/reportingPeriods?operation=WORKSPACE_REPORT&from=2026-09-01T00%3A00%3A00Z&to=2026-10-01T00%3A00%3A00Z&pageSize=50" \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```bash Default period theme={null}
curl "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/reportingPeriods?operation=WORKSPACE_REPORT" \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```bash From a start date theme={null}
curl "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/reportingPeriods?operation=CONTRIBUTOR_STATISTICS&from=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY"
```

```json 200 theme={null}
{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "periods": [
    {
      "from": "2026-09-07T00:00:00Z",
      "to": "2026-09-14T00:00:00Z",
      "timezone": "Etc/UTC"
    }
  ]
}
```


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