---
title: "Start a wording review of a report version"
method: POST
path: "/reports/{id}/versions/{versionId}/review/runs"
tags: ["Reports"]
---

# Start a wording review of a report version

`POST /reports/{id}/versions/{versionId}/review/runs`

## Request

- Base URL: `https://api.greentally.ai/v1`
- URL: `https://api.greentally.ai/v1/reports/{id}/versions/{versionId}/review/runs`
- Auth: HTTP bearer

Report review spec §8. Starts an async wording review (202): the version must be the report's and made by the current report builder (409 REPORT_NOT_REVIEWABLE) and hold written paragraphs (422 REPORT_REVIEW_NO_WRITTEN_TEXT). One review runs per version at a time (409 REPORT_REVIEW_RUNNING, details.runId). At most 30 reviews start per organisation per UTC day (429 REPORT_REVIEW_DAILY_LIMIT). Follow it with GET …/review every 2 s while run.status is pending or running. Reviews are free: no credit check, nothing debited; the tokens a reviewed run used are recorded unbilled for the caller's account. Needs report.edit_draft.

## Path parameters

- `id` string, required
- `versionId` string, required

## Response `202`

The run, pending

- ReportReviewRunResponse
  - `data` ReportReviewRun, required
    - `counts` object, required
      - `dropped` integer, required
      - `findings` integer, required
      - `unitsFailed` integer, required
    - `createdAt` string, date-time, required
    - `error` object
      - `code` string, required
      - `message` string, required
    - `finishedAt` string, date-time
    - `id` string, required
    - `outcome` 'reviewed' | 'unavailable'
    - `startedAt` string, date-time
    - `status` 'pending' | 'running' | 'done' | 'failed', required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: A referenced id is not an active record of the selected organization (ENTITY_NOT_ASSIGNABLE, SITE_NOT_ASSIGNABLE), or the reference would be invalid for it, such as an entity parent that forms a cycle (ENTITY_CYCLE)
- `429`: REPORT_REVIEW_DAILY_LIMIT: the organisation has started 30 reviews this UTC day (runs of every outcome count; owner 2026-10-07). Refused before a run is written; the count resets at the next UTC midnight.

## Changes

- **2026-10-08** `adccfaee8514`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/greentally/apis/esgai-api/changes/reports/:id/versions/:versionId/review/runs/post.md)

---

[API](https://skmtc.dev/greentally/apis/esgai-api.md) · [All operations](https://skmtc.dev/greentally/apis/esgai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/greentally/apis/esgai-api/revisions/7eab940f1dd0?raw)