✨ Trigger Agreement V2 backfill | API Reference

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

Trigger an Agreement V2 backfill for the authenticated user’s active organization. Recomputes agreement score matrices for all tasks that are missing them. 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 the Agreement V2 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 an Agreement V2 backfill for the authenticated user's active organization. Recomputes agreement score matrices for all tasks that are missing them. 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 the Agreement V2 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

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

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 the Agreement V2 feature flag.

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

1	{
2	"jobs": [
3	{}
4	],
5	"jobs_queued": 1,
6	"message": "Agreement V2 backfill job queued successfully.",
7	"organization_id": 42,
8	"projects_remaining": 3,
9	"projects_skipped": 2
10	}