Label Studio subpackage_dimensions API
The subpackage_dimensions API from Label Studio — 5 operation(s) for subpackage_dimensions.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Reference subpackage_actions subpackage_dimensions API
version: 1.0.0
servers:
- url: http://localhost:8000
tags:
- name: subpackage_dimensions
paths:
/api/dimensions/backfill/:
post:
operationId: trigger-backfill
summary: ✨ Trigger Agreement V2 backfill
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nTrigger 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:\n\n- **project_id**: backfill a single specific project.\n- **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.\n- **all_projects**: full org backfill — cancel all in-flight jobs and queue every remaining non-completed project at once.\n\nRequires administrator or owner role and the Agreement V2 feature flag."
tags:
- subpackage_dimensions
parameters:
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementV2BackfillTriggerResponse'
'400':
description: ''
content:
application/json:
schema:
description: Any type
'403':
description: ''
content:
application/json:
schema:
description: Any type
'404':
description: ''
content:
application/json:
schema:
description: Any type
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementV2BackfillTriggerRequestRequest'
delete:
operationId: cancel-backfill
summary: ✨ Cancel Agreement V2 backfill jobs
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nCancel Agreement V2 backfill jobs for the authenticated user's active organization. Cancel a specific job by job_id, all jobs for a specific project by project_id, or all backfill jobs for the entire organization if neither is provided."
tags:
- subpackage_dimensions
parameters:
- name: job_id
in: query
description: Optional specific job ID to cancel
required: false
schema:
type: integer
- name: project_id
in: query
description: Optional project ID to cancel its active backfill jobs
required: false
schema:
type: integer
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementV2BackfillCancelResponse'
'403':
description: ''
content:
application/json:
schema:
description: Any type
'404':
description: ''
content:
application/json:
schema:
description: Any type
/api/dimensions/backfill/jobs/:
get:
operationId: list-backfills
summary: ✨ List Agreement V2 backfill jobs
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nRetrieve Agreement V2 backfill jobs for the authenticated user's active organization, ordered by most-recently created first. Supports page / page_size query params (default 50 per page, max 500). Requires administrator or owner role and the Agreement V2 feature flag."
tags:
- subpackage_dimensions
parameters:
- name: status
in: query
description: 'Filter by job status: PENDING, QUEUED, RUNNING, COMPLETED, or FAILED.'
required: false
schema:
type: string
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgreementV2BackfillJob'
'400':
description: ''
content:
application/json:
schema:
description: Any type
'403':
description: ''
content:
application/json:
schema:
description: Any type
/api/dimensions/backfill/status/:
get:
operationId: get-backfill-status
summary: ✨ Get Agreement V2 backfill status
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nRetrieve the status of an Agreement V2 backfill job for the authenticated user's active organization. By default returns the aggregated organization status. Specify job_id or project_id to get a specific job status. Requires administrator or owner role and the Agreement V2 feature flag."
tags:
- subpackage_dimensions
parameters:
- name: job_id
in: query
description: Optional job ID to retrieve specific job status
required: false
schema:
type: integer
- name: project_id
in: query
description: Optional project ID to retrieve the latest backfill status for that project. If omitted, returns aggregated organization status.
required: false
schema:
type: integer
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AgreementV2BackfillJob'
'403':
description: ''
content:
application/json:
schema:
description: Any type
'404':
description: ''
content:
application/json:
schema:
description: Any type
/api/projects/{project_pk}/dimensions/:
get:
operationId: list
summary: ✨ List dimensions
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nList all dimensions for a specific project."
tags:
- subpackage_dimensions
parameters:
- name: project_pk
in: path
description: Project ID
required: true
schema:
type: integer
- name: agreement_methodology
in: query
description: 'Agreement methodology to use for computing allowed_metrics_with_params. If not provided, uses the methodology stored in the project settings. Valid values: "pairwise", "consensus". '
required: false
schema:
type: string
- name: is_active
in: query
description: Filter by active status
required: false
schema:
type: boolean
- name: ordering
in: query
description: Which field to use when ordering the results.
required: false
schema:
type: string
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'200':
description: List of dimensions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DimensionList'
/api/projects/{project_pk}/dimensions/{id}/:
get:
operationId: get
summary: ✨ Get dimension
description: "<Card href=\"https://humansignal.com/goenterprise\">\n <img style=\"pointer-events: none; margin-left: 0px; margin-right: 0px;\" src=\"https://docs.humansignal.com/images/badge.svg\" alt=\"Label Studio Enterprise badge\"/>\n <p style=\"margin-top: 10px; font-size: 14px;\">\n This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)\n </p>\n </Card>\nRetrieve a specific dimension by ID."
tags:
- subpackage_dimensions
parameters:
- name: id
in: path
description: Dimension ID
required: true
schema:
type: integer
- name: project_pk
in: path
description: Project ID
required: true
schema:
type: integer
- name: Authorization
in: header
description: '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>'
required: true
schema:
type: string
responses:
'200':
description: Dimension details
content:
application/json:
schema:
$ref: '#/components/schemas/Dimension'
components:
schemas:
DimensionList:
type: object
properties:
allowed_metrics_with_params:
type: string
description: Dictionary mapping metric type names to their parameter schemas.
control_tag:
type:
- string
- 'null'
description: Name of the control tag this dimension is extracted from. Set automatically for system dimensions.
created_at:
type: string
format: date-time
description:
type: string
description: Human-readable description of what this dimension represents
extraction_method:
type: string
description: Method used to extract values from annotation JSON
extraction_method_params:
description: Parameters specific to the extraction method. See metrics.py for available extraction methods and their parameters.
id:
type: integer
is_active:
type: boolean
description: Whether this dimension is used in agreement calculations.
is_user_defined:
type: boolean
description: Whether this dimension was manually created by a user. System-generated dimensions have this set to False.
metric_params:
description: Parameters for the metric. See metrics.py for available metrics and their parameters.
metric_type:
type: string
description: Strategy for comparing dimension values across annotators
name:
type: string
description: Unique identifier for this dimension within the project
order:
type: integer
description: Display order within the project
project:
type: integer
description: Project this dimension belongs to
updated_at:
type: string
format: date-time
required:
- allowed_metrics_with_params
- control_tag
- created_at
- description
- extraction_method
- extraction_method_params
- id
- is_active
- is_user_defined
- metric_params
- metric_type
- name
- order
- project
- updated_at
description: 'Lightweight serializer for listing dimensions.
Excludes detailed parameters for performance in list views.'
title: DimensionList
AgreementV2BackfillJob:
type: object
properties:
completed_at:
type:
- string
- 'null'
format: date-time
created_at:
type: string
format: date-time
error_message:
type: string
description: Error message if job failed
job_id:
type: integer
description: Database ID of the backfill job
progress_data:
description: JSON data tracking job progress (matrices_created, errors, etc.)
project_id:
type:
- integer
- 'null'
description: Optional specific project to backfill (if null, backfills entire organization)
rq_job_id:
type:
- string
- 'null'
description: Redis queue job ID
started_at:
type:
- string
- 'null'
format: date-time
status:
$ref: '#/components/schemas/AgreementV2BackfillJobStatusEnum'
description: 'Current status of the backfill job
* `PENDING` - Pending
* `QUEUED` - Queued
* `RUNNING` - Running
* `COMPLETED` - Completed
* `FAILED` - Failed'
triggered_by:
type: string
description: User who triggered the backfill
required:
- created_at
- job_id
- project_id
- rq_job_id
- triggered_by
description: 'Serializes a DimensionsBackfillJob model instance.
Used by the list endpoint and as the base for the status endpoint.'
title: AgreementV2BackfillJob
AgreementV2BackfillJobStatusEnum:
type: string
enum:
- PENDING
- QUEUED
- RUNNING
- COMPLETED
- FAILED
description: '* `PENDING` - Pending
* `QUEUED` - Queued
* `RUNNING` - Running
* `COMPLETED` - Completed
* `FAILED` - Failed'
title: AgreementV2BackfillJobStatusEnum
AgreementV2BackfillTriggerRequestRequest:
type: object
properties:
all_projects:
type:
- boolean
- 'null'
description: Set to true to trigger a full org backfill (cancels in-flight jobs and queues all remaining projects).
num_projects:
type:
- integer
- 'null'
description: Queue at most this many projects per call (batched mode).
project_id:
type:
- integer
- 'null'
description: Backfill a single specific project.
description: "Request body for POST /api/dimensions/backfill/\n\nExactly one of the three mode fields must be provided:\n\n- project_id: backfill a single specific project.\n- num_projects: batched org backfill — queue the next N not-yet-started projects\n (ascending project ID order), leaving in-flight jobs untouched.\n Check `projects_remaining` in the response and repeat until it reaches 0.\n- all_projects: full org backfill — cancel all in-flight jobs and queue every\n remaining non-completed project at once."
title: AgreementV2BackfillTriggerRequestRequest
AgreementV2BackfillCancelResponse:
type: object
properties:
cancelled_count:
type: integer
description: Number of jobs successfully cancelled
message:
type: string
required:
- cancelled_count
- message
description: Response from DELETE /api/dimensions/backfill/
title: AgreementV2BackfillCancelResponse
Dimension:
type: object
properties:
allowed_metrics_with_params:
type: string
description: Dictionary mapping metric type names to their parameter schemas.
control_tag:
type:
- string
- 'null'
description: Name of the control tag this dimension is extracted from. Set automatically for system dimensions.
created_at:
type: string
format: date-time
created_by:
type:
- integer
- 'null'
description: User who created this dimension
description:
type: string
description: Human-readable description of what this dimension represents
extraction_method:
type: string
description: Method used to extract values from annotation JSON
extraction_method_params:
description: Parameters specific to the extraction method. See metrics.py for available extraction methods and their parameters.
id:
type: integer
is_active:
type: boolean
description: Whether this dimension is used in agreement calculations.
is_user_defined:
type: boolean
description: Whether this dimension was manually created by a user. System-generated dimensions have this set to False.
metric_params:
description: Parameters for the metric. See metrics.py for available metrics and their parameters.
metric_type:
type: string
description: Strategy for comparing dimension values across annotators
name:
type: string
description: Unique identifier for this dimension within the project
order:
type: integer
description: Display order within the project
project:
type: integer
description: Project this dimension belongs to
updated_at:
type: string
format: date-time
required:
- allowed_metrics_with_params
- control_tag
- created_at
- created_by
- id
- name
- project
- updated_at
description: 'Serializer for Dimension model.
Handles serialization and validation for CRUD operations on dimensions.
The project and created_by fields are set automatically from the request context.'
title: Dimension
AgreementV2BackfillTriggerResponse:
type: object
properties:
jobs:
type: array
items:
type: object
additionalProperties:
description: Any type
description: 'Queued jobs: [{job_id, rq_job_id, project_id}]'
jobs_queued:
type: integer
description: Number of jobs queued in this request
message:
type: string
organization_id:
type: integer
projects_remaining:
type: integer
description: Projects not yet started and not currently in-flight. Relevant when num_projects is used — call POST again until this reaches 0.
projects_skipped:
type: integer
description: Projects skipped because they already have a completed backfill
required:
- jobs
- jobs_queued
- message
- organization_id
- projects_remaining
- projects_skipped
description: Response from POST /api/dimensions/backfill/
title: AgreementV2BackfillTriggerResponse
securitySchemes:
Token:
type: apiKey
in: header
name: Authorization
description: '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>'