Skip to main content
Lists reporting periods with processed data available for Get workspace report or List contributor statistics. 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.
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.
​
string
required
Bearer <key>. See Authentication.

​
Path parameters

​
string
required
GITHUB_ORGANIZATION or GITHUB_USER.
​
string
required
Numeric GitHub ID of the organization or user, as a string. Must match the key’s workspace.

​
Query parameters

​
string
required
WORKSPACE_REPORT or CONTRIBUTOR_STATISTICS. There is no default; REPORTING_PERIOD_OPERATION_UNSPECIFIED is invalid.
​
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.
​
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.
​
integer
default:"50"
Maximum windows per page, 1 to 200. Explicit 0 is invalid. May change between pages.
​
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

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

​
string
Inclusive start of the resolved search range (RFC 3339). Returned even when no periods match; not necessarily the start of a returned period.
​
string
Inclusive end of the resolved search range (RFC 3339). Returned even when no periods match; not necessarily the end of a returned period.
​
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.
​
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. 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.