---
title: "✨ Trigger Dimension value-counts backfill"
method: POST
path: "/api/dimensions/value-counts-backfill/"
tags: ["Dimensions"]
---

# ✨ Trigger Dimension value-counts backfill

`POST /api/dimensions/value-counts-backfill/`

<Card href="https://humansignal.com/goenterprise">
        <img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
        <p style="margin-top: 10px; font-size: 14px;">
            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
        </p>
    </Card>
Trigger a Dimension label-distribution value-counts backfill for the authenticated user's active organization. Populates MatrixAnnotatorEntry.value_counts and rebuilds the ProjectSummary.dimension_value_counts cache for all tasks, without recomputing agreement scores. Exactly one of three body fields must be provided:

- **project_id**: backfill a single specific project.
- **num_projects**: batched org backfill — queue the next N not-yet-started projects (in ascending project ID order), leaving any currently in-flight jobs untouched. Repeat calls until `projects_remaining` in the response reaches 0.
- **all_projects**: full org backfill — cancel all in-flight jobs and queue every remaining non-completed project at once.

Requires administrator or owner role and access to Agreement V2 value counts.

## Request body

- AgreementV2BackfillTriggerRequestRequest — Request body for POST /api/dimensions/backfill/ Exactly one of the three mode fields must be provided: - project_id: backfill a single specific project. - num_projects: batched org backfill — queue the next N not-yet-started projects (ascending project ID order), leaving in-flight jobs untouched. Check `projects_remaining` in the response and repeat until it reaches 0. - all_projects: full org backfill — cancel all in-flight jobs and queue every remaining non-completed project at once.
  - `all_projects` boolean, nullable — Set to true to trigger a full org backfill (cancels in-flight jobs and queues all remaining projects).
  - `num_projects` integer, nullable — Queue at most this many projects per call (batched mode).
  - `project_id` integer, nullable — Backfill a single specific project.

## Response `201`

- AgreementV2BackfillTriggerResponse — Response from POST /api/dimensions/backfill/
  - `jobs` object[], required — Queued jobs: [{job_id, rq_job_id, project_id}]
  - `jobs_queued` integer, required — Number of jobs queued in this request
  - `message` string, required
  - `organization_id` integer, required
  - `projects_remaining` integer, required — Projects not yet started and not currently in-flight. Relevant when num_projects is used — call POST again until this reaches 0.
  - `projects_skipped` integer, required — Projects skipped because they already have a completed backfill

## Other responses

- `400`
- `403`
- `404`

---

[API](https://skmtc.net/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.net/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/revisions/8ab207b03dd5/schema)