Team productivity API

Reference

Team reports describe current primary members over a selected reporting period. See Team report semantics and Explore engineering outcomes for definitions and the page workflow.

Endpoints

These routes require an active administrator account. A report belongs to the account that captures it; knowing an ID does not grant access. Analytical capture and cancellation do not change Team or source configuration.

Endpoint	Purpose
`POST /api/v1/team-productivity/reports`	Capture a new `overview` root.
`POST /api/v1/team-productivity/reports/{rootId}/views`	Derive a presentation or evidence view from the accepted root.
`GET /api/v1/team-productivity/reports/{id}`	Poll a job or read its first page.
`GET /api/v1/team-productivity/reports/{artifactId}?cursor=SIGNED_CURSOR`	Read the next page of the artifact that issued the cursor.
`GET /api/v1/team-productivity/reports/{artifactId}?bin=SIGNED_BIN&cursor=SIGNED_CURSOR`	Inspect a signed density bin when an artifact returns one; omit the cursor for its first page.
`DELETE /api/v1/team-productivity/reports/{id}`	Cancel the account's analytical job; success returns `204`.

POST routes accept a JSON body and no query parameters. GET accepts one cursor and one optional signed bin, with no selection changes. DELETE accepts no query parameters. Completed report pages use Cache-Control: private, no-store.

Report request

Resolve an authorized Team context through POST /api/v1/outcomes/analytics/context, using the Team scope, period, PR filters, and your saved reporting preference revision. Pass its returned contextToken to the report request. The server resolves dates, timezone, current roster, repository eligibility, identity, and source revisions; do not supply these as trusted facts.

Field	Meaning
`contextToken`	Authorized native context for the selected Team and reporting period.
`version`	`1`.
`adapter`	`team_productivity_v1`.
`section`	`overview`, `points`, `investment`, `reviews`, `sessions`, `output_rankings`, `spending_rankings`, or derived `relationships`. A new root must start with `overview`.
`limit`	Page size from 1 through 50. The page offers 10, 25, and 50.
`parameters`	Selection and presentation fields below. Unknown fields are rejected.
`relationships`	Required only for the derived Relationships section; exact fields are listed below.

Example new-root body, after resolving the context:

{
  "contextToken": "RETURNED_CONTEXT_TOKEN",
  "version": 1,
  "adapter": "team_productivity_v1",
  "section": "overview",
  "limit": 25,
  "parameters": {
    "teamId": "TEAM_ID",
    "source": "gateway_recorded_estimate",
    "filters": {
      "repositoryIds": [],
      "personIds": [],
      "contributorKeys": [],
      "workTypes": [],
      "prFilters": { "branches": [], "excludeDelivery": [] }
    },
    "trendMetric": "productivity_points",
    "selectedPeriodTrend": true,
    "sort": "name",
    "descending": false,
    "search": ""
  }
}

Selection and presentation parameters

Parameter	Values and behavior
`teamId`	Canonical Team ID matching the authorized context. The server captures current primary members.
`source`	`gateway_recorded_estimate` or `observer_current_rate_estimate`. Sources are separate captures, never a combined bill.
`filters`	Native delivery filters, including `prFilters` and `workTypes`. Repository, person, and contributor-key selectors are rejected for this adapter. Filters do not redefine Gateway activity.
`trendMetric`	`productivity_points`, `points_per_active_contributor`, `merged_prs`, `estimated_spend`, `gateway_requests`, or `five_minute_peak_sessions`. Gateway activity metrics are unavailable for Observer.
`selectedPeriodTrend`	Selects the captured reporting-period series when `true`; the overview uses this setting.
`sort`	`name`, `productivity_points`, `merged_prs`, `estimated_spend`, or `gateway_requests`, subject to the section restrictions below.
`descending`, `search`	Server ordering and search before paging. Search is at most 256 UTF-8 bytes.
`memberId`, `prId`	Optional captured member or PR focus for supported evidence sections. A focus does not grant access or change headline totals.
`mode`	A section-specific mode listed below; empty selects the section default.
`rankingView`	`all_observed`, `highest`, or `lowest`, for ranking sections only.
`preview`	A bounded ranking preview, for ranking sections only.

Retained views keep the root's Team, source, filters, dates, and roster. Change presentation fields to sort, search, page, or open evidence. A different source requires its own authorized capture. Do not reuse a Gateway root for Observer.

Section	Supported modes and restrictions
`overview`	Default mode. Supports the member chart orders; `gateway_requests` sorting is restricted to this section.
`points`	Default, `prs`, or `work_mix`; supports member or PR focus, except PR focus with `work_mix`. Numeric sorting supports points, and PR count for `work_mix`.
`investment`	Default, `cost`, `models`, `providers`, `participation`, or `ratios`. Supports spending sort. `participation` and `ratios` do not accept member focus; PR focus is rejected.
`reviews`	Default, `received`, or `performed`. `performed` counts observed submitted-in-period events and distinct reviewed PRs for current confirmed reviewers. It supports member focus, rejects PR focus, and retains quiet members with zero observed events.
`sessions`	Default mode; supports member or PR focus. Linked lifetime session cost is not selected-period or exclusive PR spending.
`output_rankings`	Default or `peers`. `peers` cannot be combined with preview or ranking selectors. No member or PR focus.
`spending_rankings`	Default mode; no member or PR focus.
`relationships`	Name order without search, member/PR focus, ranking selectors, or section mode. Requires the typed Relationships selector below.

All sections support name sorting. Other unsupported combinations fail validation.

Retained Relationships selector

Send section: "relationships" to the accepted root's views endpoint with the same Team parameters and a relationships object:

Field	Values
`mode`	`across_members` or `over_time`.
`windowId`	A window ID in the accepted report context. Across-member views support `current` and `prior`.
`x`	`gateway_requests` or `five_minute_peak_sessions`.
`y`	`productivity_points` or `merged_prs`.
`lagWeeks`	`0` across members; `0`, `1`, `2`, or `4` over time.
`quality`	`observed` or `complete_only`.

Across-member pairs use the complete frozen roster. Over-time pairs use Monday weeks within the exact selected window, including explicit partial/unpaired-week exclusions. PR filters constrain delivery operands, not request attribution. Unsupported source operands remain unavailable. Changing the selector derives another view from the same root; it does not recapture evidence.

header.relationships contains native full-population counts, exclusions and a Spearman coefficient or unavailable reason. Typed rows retain both operands and their exact ranges. Signed pages preserve the selector, root, owner and expiry. The Team source selection admits at most 1,000 canonical members. Its chart shows all admitted pairs while the exact evidence table is paged. The shared artifact format uses density bins above 2,000 admitted pairs; Team's current admission bound stays below that threshold. Bin tokens and cursors are not interchangeable. The separate Outcomes Relationships tab continues to use its own context.

Responses and signed pages

A request can return 200 with a completed page or 202 with a job containing id, state, and expiresAt. For 202, respect Retry-After and poll the Team GET route with that job ID. Terminal failed, cancelled, or expired jobs return an error rather than partial report data.

A completed page contains header, rows, totalCount, and nullable nextCursor. Keep these two IDs distinct:

header.context.snapshotId identifies the accepted root. Use it in the views route.
header.snapshotId identifies the returned artifact. Use it with that artifact's cursor.

Send a cursor unchanged and URL-encoded with its issuing artifact ID. Cursors cannot move between accounts, roots, or views. Search and numeric ordering use the complete eligible population before paging; changing pages does not change the totals or ranks.

The header retains context, source, windows, basis, capabilities, coverage, comparisons, series, and population counts. Each typed metric carries its unit, population, window, basis digest, status, reason, and any ratio operands. Null is unavailable evidence, not zero. Quiet and pending-score members remain visible; qualified output and spending rankings exclude unsupported operands.

Team peer standing is unavailable when the period or native source coverage cannot qualify any Team. In that case, capture retains the Team directory and selected Team's raw output, and skips organization-wide peer output reductions. The peer view preserves directory entries, but other Teams' metrics are null with reason peer_output_not_captured; it does not fetch them later under the same root. The eligible count is zero because the qualification gate applies to all candidates, not because missing peer output was treated as zero.

Snapshot lifecycle and limits

Ordinary event arrivals do not fill in an existing root. On-demand evidence uses its retained cutoff. Explicit Refresh captures a new coherent root. Expiry, roster or identity changes, destructive source changes, and loss of account authority can invalidate protected content. Clear invalid content and resolve a new authorized context before capturing again.

When Gateway support is uninitialized or rebuilding, independently qualified roster and PR output can remain available while AI activity and cost stay null. Recovery invalidates the old unavailable basis; only explicit Refresh captures the recovered evidence. Integrity, database, cancellation, and capacity errors do not become an empty successful report.

Observer estimates use qualified identities and a captured price basis. Imported session lifetime totals are not period-cost alternatives. Reviews received on selected merged PRs have a different population and time basis from reviews performed during the interval. Team performed evidence uses the full eligible repository catalog captured with the root, including repositories without Team-authored PRs. Its review cohort is independent of PR author, merge date and PR-output filters. Counts distinguish review events from distinct reviewed PRs.

Named attribution is limited to current confirmed public GitHub OAuth reviewers whose active canonical account, email claim and self-service mapping history agree. Only events at or after the latest qualifying confirmation are counted; earlier events are not backfilled. Historical ownership without that proof, reassigned handles, other hosts, administrator overrides and unsupported identities remain unresolved. Mapping or account changes can invalidate retained results. A zero means no attributed event was observed in this subset, not that the member performed no reviews. Collection completeness remains unavailable, independently of authored-PR delivery coverage. Repository-wide diagnostics are explicitly separate from Team-attributed counts; missing-time diagnostics cannot be scoped to the selected period. No score credit, saved-labor estimate, or causal claim follows from this evidence.

Page bounds and a bounded fixture are not a target-scale capacity guarantee. Capacity errors remain explicit; clients must not present truncated populations as complete reports.

Endpoints​

Report request​

Selection and presentation parameters​

Retained Relationships selector​

Responses and signed pages​

Snapshot lifecycle and limits​