Repository productivity API

Reference

Repository reports use a server-resolved canonical repository set and the administrator's saved reporting timezone. See Repository report semantics for metric definitions and Explore engineering outcomes for the page workflow.

Endpoints

Both endpoints require administrator authentication, return JSON with Cache-Control: no-store, and accept a JSON body with no query parameters. They do not modify configuration.

Endpoint	Purpose
POST /api/v1/outcomes/analytics/repository/report	Capture a report or request a view of an existing report root.
POST /api/v1/outcomes/analytics/repository/report/page	Poll a pending job, read its first page, or follow its signed cursor.

Report request

Field	Meaning
report.contextToken	Native authorized Outcomes context containing the selected period, timezone and PR filters.
report.version	1.
report.adapter	repository_productivity_v1.
report.section	overview, points, investment, reviews, sessions, output_rankings or spending_rankings.
report.limit	Page size from 1 through 50.
report.parameters	Repository selection and presentation controls below.
rootSnapshotId	Empty for a new capture; the accepted root ID for a retained view.

Selection parameters:

Parameter	Values and behavior
repositoryId	Legacy single canonical repository ID. Omit when scope is supplied.
scope	{kind: "organization", repositoryIds: []}, {kind: "manual", repositoryIds: [...]}, {kind: "project", id: "PROJECT_ID", repositoryIds: []}, or {kind: "team", id: "TEAM_ID", repositoryIds: []}. Manual sets contain 1–1,000 unique canonical IDs. Organization and Project membership are resolved by the server. Team scope requires an organization context, discovers repositories touched by current primary-team members in the selected period and PR filters, and includes all authors in the discovered set. Use __unassigned__ for people without a primary Team. Roster and access remain live; later PR arrivals require Refresh to expand the retained repository set. Incomplete Project membership is rejected rather than silently narrowed.
source	gateway_recorded_estimate or observer_current_rate_estimate. Observer repository spending remains unavailable without a trusted repository bridge.
contributorKeys	Up to 100 captured safe contributor keys; empty selects all observed identities. Provider accounts do not imply developer accounts.
workTypes	Native effective PR work types; empty includes all types. Cost/output ratios are unavailable under incompatible PR filters.
population	all_observed, pr_active or ai_active; changes the contributor table, not headline totals.
trendWindow	current, weekly_trend or monthly_trend.
trendMetric	productivity_points, merged_prs, points_per_active_contributor_identity or estimated_spend.
sortMetric, descending, search	Complete-population ordering and search before paging. Search is bounded to 256 UTF-8 bytes.
focusContributorKey, focusPrId	Optional mutually exclusive focus for retained evidence. These do not change report totals.
rankingView	all_observed, highest or lowest. Ordinary table order does not assert a qualified rank.
detail, detailSort	Supported focused mode and numeric evidence column. Unknown modes or columns are rejected.

For overview previews, use section: "overview", detail: "overview_leaders", trendWindow: "current", and the same sortMetric and trendMetric: either merged_prs or productivity_points. The response contains the complete-scope metric and selected-period series, with up to three server-selected observed contributors, tie labels, and no cursor. No band or percentile is assigned. These are derived views of the accepted root; they do not recapture evidence.

For output concentration, use section: "points" and detail: "concentration" without a PR or contributor focus. The two rows contain point_share metrics with retained numerator and denominator operands for the largest known contributor and up to three contributors. The complete selected-scope denominator includes unassigned author points. Named-contributor filters and incomplete scores return unavailable shares with reasons. detailSort: "point_share" and search change row presentation only. This mode reuses root output facts without loading PR evidence.

For review concentration, use section: "reviews" and detail: "review_concentration" without a PR or contributor focus. It uses lazy received-review evidence for the root's merged-PR cohort. The two count rows preserve distinct original human reviews, actual known reviewer counts, unmapped reviewer evidence, and boundary ties. The denominator includes human reviews with missing identities. Submissions outside the merge period remain in this received cohort; no performed-in-period or reviewer-effort claim is made. Numeric detailSort: "review_events" and search apply after full-population calculation.

The server resolves authorization, identity, repository eligibility, source revisions and time bounds. A client cannot supply a trusted basis or convert an unavailable source into attributable spending.

Pages and availability

A pending response identifies a native job. Poll the page endpoint with {"jobId":"RETURNED_JOB_ID","cursor":""}. A completed page contains header, rows, totalCount and nextCursor. Preserve the returned root and basis for subsequent views; send cursors unchanged with the job that issued them.

The header carries the retained context, typed metrics and comparisons, selected series, columns and full population counts. A row carries its safe ID, display name, typed metrics, evidence cells and any qualified rank. Each metric retains its unit, population, window, basis, coverage, status and reason. A null value is not zero. Source links use verified canonical repository or native session identity; opening a destination independently checks authorization.

Repository catalog search and contributor paging do not narrow headline totals. Numeric ordering precedes search and paging, with missing values last. Output rankings exclude incomplete scores; spending rankings also require accepted usage and compatible attribution/pricing. Excluded identities remain visible in the all-observed table.

Snapshot lifecycle

Ordinary new activity does not replace a retained report. Explicit Refresh creates a new coherent root. Expiry, access loss and destructive identity/source changes invalidate protected data; retry with a newly authorized context. Cursors cannot move between owners, roots or views. Capacity failures return an error rather than a silently truncated population.

Linked session lifetime costs are not PR spending. Gateway originals are classified from full repository support before repository or contributor filters. Shared, unresolved, fallback and unpriced evidence is disclosed separately from accepted exclusive estimates. If native attribution support is still processing, spending is unavailable until a refreshed report can capture complete support. PR output remains available; partial spending is not published as a completed estimate.

Investment details distinguish shared usage wholly within the selected repository set from shared usage crossing its boundary. Both stay excluded from exclusive spending, even when a Project contains every repository supporting an original request. Filtering the view does not reclassify that request as exclusive.

Pooled PR-flow evidence

A retained reviews view accepts detail: "flow_summary" without a focused PR or contributor. It lazily reads the same received-review evidence as the PR table at the accepted root cutoff, then pools one native qualified duration per distinct PR and endpoint pair. It publishes three evidence rows, not overview metrics or rankings. The median_seconds, p75_seconds and valid_prs columns sort on retained numeric values before search and paging. Displayed durations use hours; missing and invalid endpoints remain absent. Median uses midpoint interpolation for an even sample; p75 is nearest rank. Every row discloses valid n, eligible N, missing counts and timestamp basis. No session costs or deployment timing are used.