> ## Documentation Index
>
> Fetch the complete documentation index at: https://lithi.ai/llms.txt
>
> Use this file to discover all available pages before exploring further.

# Compute Impact Reports API

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

~~~text title="Impact report request syntax" kind="pseudocode"
GET /v1/impact-reports/{period_id}
~~~

Required scope:

~~~text title="Required reporting scope" kind="rules"
reporting:read
~~~

The 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`.

```http title="Select the filed report payload" kind="data"
GET /v1/impact-reports/2026-08?revision=2 HTTP/1.1
```

Do 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](/trust/impact) 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](/trust/impact) for the evidence and claim boundary and [Read a Compute impact report](/docs/compute/impact-report) for customer interpretation.