---
title: "GET /uploads/{id}/factor-agent/groups"
method: GET
path: "/uploads/{id}/factor-agent/groups"
tags: ["Uploads"]
---

# GET /uploads/{id}/factor-agent/groups

`GET /uploads/{id}/factor-agent/groups`

Review groups of a row-stored analysis, in document order. An analysis stored whole answers 409 ANALYSIS_NOT_GROUPED; read it with GET /uploads/{id}/factor-agent/analysis. When any row of the analysis carries facets (a ledger's rows do), the first page (no cursor) adds facetSummary, totalRows and filteredRows, and every page takes the smart filter facets[<key>]=<value>: a key repeated ORs its values, keys AND. The filtered page holds the groups with at least one review row matching; each group's summary is still the whole group's. An analysis whose rows carry no facets answers as before, without those three keys, and refuses a filter with 400 FACETS_UNAVAILABLE. Facets never change an emission or what a submit sends.

## Path parameters

- `id` integer, required

## Query parameters

- `cursor` string
- `limit` integer
- `facets` object

## Response `200`

One page of review groups

- DirectUploadFactorGroupsResponse
  - `data` object, required
    - `analysisVersionId` string, uuid, required
    - `facetSummary` object — Present only when a row of the analysis carries facets. Per facet key (journalType, journalSource, department, period, carbon, decisionSource; every key present, possibly empty), its values over every stored row of the analysis, review and listed, whatever the filter: the most rows first (ties by value), at most 50. A row without a value for a key is not counted under it. carbon is the row's own: carbon for a review row, non_carbon for a row only listed (a non-carbon key's, or a levy line of a carbon key). decisionSource is reviewer once a reviewer chose the row's group's factor (reviewers never change the carbon decision itself), else who decided the row's carbon decision when the ledger was stored: model, known (the organization's remembered decision), rule, rule_unanswered (a key a failed model batch left on its rule decision) or levy_rule (a line Core's levy rule listed as non-carbon). Present on the first page only.
    - `filteredRows` integer — The stored rows, review and listed, the filter matches (totalRows without one); present with facetSummary.
    - `groups` DirectUploadFactorGroup[], required
      - `decision` object, required
      - `decisionSource` 'model' | 'memory' | 'reviewer', required
      - `display` object, required
      - `groupKey` string, required
      - `rowCount` integer, required
      - `selectedFactor` DirectUploadFactorCandidate
        - `activityUnit` string
        - `confidence` 'high' | 'medium' | 'low'
        - `factorValue` number, double
        - `id` string, required
        - `libraryId` string
        - `libraryName` string
        - `name` string, required
        - `reason` string
        - `regionCode` string
        - `releaseId` string
        - `releaseYear` integer
        - `scope` integer
        - `unit` string
        - `warnings` string[]
      - `selectedFactorId` string
      - `selections` DirectUploadFactorGroupSelection[], required
        - `regionCode` string
        - `releaseYear` integer
        - `rowCount` integer, required
        - `selectionKey` string, required
        - `unit` string
      - `status` 'processing' | 'completed' | 'needs_input', required
      - `statusCounts` DirectUploadFactorGroupStatusCounts, required — The group's review rows by how the review shows them; each row once: submitted, else excluded, else its decision.
        - `estimated` integer, required
        - `excluded` integer, required
        - `needsInput` integer, required
        - `ready` integer, required
        - `submitted` integer, required
      - `submittedCount` integer, required
      - `totals` DirectUploadFactorGroupTotals, required
        - `emissions` object, required
        - `quantity` object, required
        - `spend` object, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable
    - `totalRows` integer — Every stored row of the analysis, review and listed; present with facetSummary.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — The analysis is not stored as rows

## Changes

- **2026-10-02** `766c2a40e369` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greentally/apis/esgai-api/changes/uploads/:id/factor-agent/groups/get.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/4189686230ca?raw)