Compute Impact Reports API
How to fetch a monthly impact report, choose a revision, and check the report and its files by hash.
Retrieve the filed report for this period. The account-bound reporting permission, period selector, revision, and snapshot identity determine which immutable report you receive; the endpoint and exact fields below define how to request and verify it.
Your agent can read an authorized report through the reporting:read API or an approved report file.
Reporting is separate from the five Work MCP tools. The report describes its recorded populations and
evidence; it does not establish semantic correctness, confirmed payment, or environmental savings.
Endpoint
GET /v1/impact-reports/{period_id}Required scope:
reporting:readThe API separately authorizes reporting access through the account-bound finance bearer it describes. That credential cannot execute work or write finance records. A normal customer work key does not gain reporting access merely because it can submit or read jobs.
Select the filed report
period_id selects the reporting period accepted by the API. The account bound to the credential remains the authority; selectors cannot choose another account.
| Parameter | Location | Required | Exact value |
|---|---|---|---|
period_id | Path | Yes | A 64-character lowercase hexadecimal canonical period ID, or a reporting month in YYYY-MM form. |
revision | Query | No | An integer from 1 through 2147483647. Omit it to select the latest filed revision. |
snapshot_digest | Query | No | A 64-character lowercase hexadecimal snapshot digest. Send it with revision to pin the filed revision and its snapshot. |
Only revision and snapshot_digest are accepted query keys. Duplicate keys and unknown query keys return BODY_INVALID.
This example selects the August 2026 report at revision 2. It omits credentials; a real request requires the account's owner-provisioned finance bearer with reporting:read.
GET /v1/impact-reports/2026-08?revision=2 HTTP/1.1Do not substitute a different account's report identity or assume the latest visible report is the revision an external filing used.
Response and client boundary
A successful 200 response uses ComputeImpactReportV1Success; its data member is a ComputeImpactReportV1 report with schema_version: "v1" and contract_id: "ComputeImpactReportV1".
Use the REST contract above when you need revision selectors. If your SDK returns status: "unavailable", code: "SDK_CONTRACT_UNAVAILABLE" and p_next_action: "check_published_reporting_contract", it has made no reporting request. That local client result is not a report response or evidence that the report is missing.
Report identity
A filed impact report carries report_id, period_id, revision, and snapshot_digest. It also carries reporting_month, period_start_utc, period_end_utc, source_watermark, finalised_at, method_version: "compute_impact_report.v1", methodology_authority: "/trust/impact", and late_event_grace_hours: 72.
period_id and snapshot_digest are 64-character lowercase hexadecimal strings. revision starts at 1. A later correction or newly qualified evidence creates a later revision with lineage to the earlier report; supersedes_snapshot_digest and revision_reason identify that relationship. The earlier snapshot is not rewritten under the same digest.
Keep report populations separate
The report keeps three participation populations distinct:
| Report population | Contract field | What it tells you |
|---|---|---|
| Macs recorded with accepted work | accepted_work_macs | Macs linked to accepted work in the report population. |
| Macs recorded with physical activity | physical_activity_macs | Macs with recorded physical activity, which can include work that failed or was retried. |
| Provider accounts recorded with participation | provider_accounts | Provider accounts linked to the report population, including participation beyond accepted work; an account can represent a person or an organization. |
These populations can overlap, but they are not additive totals. A provider-account count is not a verified human count, and none of these fields confirms payment or claimed savings. Use the report's availability labels and counting rule with each value.
Energy, evidence, and coverage fields
The report keeps accepted work and physical activity separate:
| Contract field | Exact value or meaning |
|---|---|
work.population | accepted_customer_outcomes_by_completion_time |
energy.population | physical_consumption_intervals_including_failed_and_unpaid_work |
energy.grid_input.energy_boundary | grid_input |
energy.grid_input.device_load.energy_boundary | device_load |
energy.platform_allocation.method_version | contemporaneous_active_time.v1 |
energy.platform_allocation.allocation_basis | overlapping_customer_active_time |
energy.physical_time_coverage.population | all physical intervals including failed and unpaid work |
energy.grid_factor_coverage.population | qualified grid input with approved factor |
This endpoint returns the monthly ComputeImpactReportV1, not the underlying device observations or resolved energy lines. Use its aggregate energy, provenance and coverage fields. The impact methodology explains the measurement and estimation evidence behind those figures. A grid-input amount that already includes device electricity is not added to the nested device-load amount again.
Coverage fields use a numerator and denominator and may carry coverage_ppm or a corresponding *_ppm value. Coverage is evidence for the named population; it is not a claim about all work or all emissions. availability_state: "unavailable" is a typed gap, not zero.
File identity is separate
A rendered JSON or PDF artifact has its own artifact_sha256. Do not substitute snapshot_digest for artifact_sha256.
The JSON and PDF files can identify the same report while having different SHA-256 values because their bytes are different.
Availability is typed
An unavailable report section carries typed availability_state and unavailable_reason data; it is not a zero-impact result. Use the API's typed state, error, and next action. Do not synthesize a report from partial portal counters or replace an unavailable quantity with zero.
Methodology is not defined by this endpoint
The API returns the filed report. It does not redefine how energy, coverage, emissions, or comparison claims are calculated. Use Compute impact methodology for the evidence and claim boundary and Read a Compute impact report for customer interpretation.