✨ Trigger Dimension value-counts backfill

POST

http://localhost:8000/api/dimensions/value-counts-backfill/

This endpoint is not available in Label Studio Community Edition. Learn more about Label Studio Enterprise

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, the Agreement V2 feature flag, and the value-counts write feature flag.

<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, the Agreement V2 feature flag, and the value-counts write feature flag.

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example:

curl https://label-studio-host/api/projects -H “Authorization: Token [your-token]”

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example: <br><pre><code class="language-bash">curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"</code></pre>

Request

This endpoint expects an object.

all_projectsboolean or nullOptional

Set to true to trigger a full org backfill (cancels in-flight jobs and queues all remaining projects).

num_projectsinteger or nullOptional>=1

Queue at most this many projects per call (batched mode).

project_idinteger or nullOptional

Backfill a single specific project.

Response

jobslist of maps from strings to any

Queued jobs: [{job_id, rq_job_id, project_id}]

jobs_queuedinteger

Number of jobs queued in this request

messagestring

organization_idinteger

projects_remaininginteger

Projects not yet started and not currently in-flight. Relevant when num_projects is used — call POST again until this reaches 0.

projects_skippedinteger

Projects skipped because they already have a completed backfill

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

$	curl -X POST http://localhost:8000/api/dimensions/value-counts-backfill/ \
>	-H "Authorization: Token <api_key>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"jobs": [
3	{}
4	],
5	"jobs_queued": 1,
6	"message": "string",
7	"organization_id": 1,
8	"projects_remaining": 1,
9	"projects_skipped": 1
10	}