Documentation Grafana Cloud Testing and synthetics Performance testing Reference pages Cloud REST API Labels

Labels REST API

List label keys

GET /cloud/v6/labels

List all label keys (accessible by all authenticated users).

Request parameters

200 response

OK.

Content types: application/json

Response for listing label keys

LabelKeyListResponse properties:

Label key response model

LabelKeyResponse properties:

OK example

{
  "value": [
    {
      "description": "Environment being tested",
      "id": 1,
      "key": "environment"
    },
    {
      "description": "Team responsible for the project",
      "id": 2,
      "key": "team"
    }
  ]
}

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

Create label keys

POST /cloud/v6/labels

Creates one or more label keys for the organization.

This operation is additive: it adds the new labels to the existing ones without replacing them.

Request parameters

Request body

Content types: application/json

Request to create one or more label keys

LabelKeyCreateRequest properties:

Single label key to create

LabelKeyCreateItem properties:

Create example

{
  "value": [
    {
      "description": "Environment being tested",
      "key": "environment"
    },
    {
      "description": "Team responsible for the project",
      "key": "team"
    },
    {
      "key": "cost_center"
    }
  ]
}

201 response

OK.

Content types: application/json

Response for listing label keys

LabelKeyListResponse properties:

Label key response model

LabelKeyResponse properties:

Created example

{
  "value": [
    {
      "description": "Environment being tested",
      "id": 1,
      "key": "environment"
    },
    {
      "description": "Team responsible for the project",
      "id": 2,
      "key": "team"
    },
    {
      "description": null,
      "id": 3,
      "key": "cost_center"
    }
  ]
}

400 response

Duplicate keys in request.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

409 response

Maximum number of label keys (100) exceeded.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

Delete a label key

DELETE /cloud/v6/labels/{id}

Delete a label key (Admin only).

When a label key is deleted, all project labels using this key are cascade deleted.

Request parameters

204 response

OK.

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

404 response

Label key not found.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

Update a label key

PATCH /cloud/v6/labels/{id}

Update a label key (rename or update description) (Admin only).

Request parameters

Request body

Content types: application/json

Request to update a label key

LabelKeyPatchRequest properties:

RenameKey example

{
  "key": "env"
}

UpdateBoth example

{
  "description": "Environment (dev, prod)",
  "key": "env"
}

UpdateDescription example

{
  "description": "Environment (dev, prod)"
}

200 response

OK.

Content types: application/json

Label key response model

LabelKeyResponse properties:

OK example

{
  "description": "Environment (dev, prod)",
  "id": 1,
  "key": "env"
}

400 response

Request validation error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

404 response

Label key not found.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

409 response

Label key with new name already exists.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

List project labels

GET /cloud/v6/projects/{project_id}/labels

List all labels on a project.

Request parameters

200 response

OK.

Content types: application/json

Response for listing project labels

ProjectLabelListResponse properties:

Single project label (key-value pair)

ProjectLabelItem properties:

OK example

{
  "value": [
    {
      "key": "environment",
      "value": "production"
    },
    {
      "key": "team",
      "value": "backend"
    }
  ]
}

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

404 response

Resource not found.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

Replace project labels

PUT /cloud/v6/projects/{project_id}/labels

Replace labels on a project (Admin or Editor).

This is a full replacement operation.

Request parameters

Request body

Content types: application/json

Request to replace project labels.

This is a full replacement of all labels on the project.

ProjectLabelPutRequest properties:

Single project label for PUT request

ProjectLabelPutItem properties:

ReplaceLabelsUsingKey example

{
  "value": [
    {
      "key": "provider",
      "value": "aws"
    }
  ]
}

ReplaceLabelsUsingKeyId example

{
  "value": [
    {
      "key_id": 1,
      "value": "aws"
    }
  ]
}

200 response

OK.

Content types: application/json

Response for PUT project labels

ProjectLabelPutResponse properties:

Single project label in PUT response

ProjectLabelPutResponseItem properties:

OK example

{
  "value": [
    {
      "key": "provider",
      "key_id": 1,
      "value": "aws"
    }
  ]
}

400 response

Invalid label key ID or name, or duplicate keys in request.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

404 response

Project not found.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

409 response

Max labels per project (30) or max unique pairs per organization (500) exceeded.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

Remove a label from project

DELETE /cloud/v6/projects/{project_id}/labels/{key}

Remove a label from a project (Admin or Editor).

Request parameters

204 response

OK.

401 response

Invalid token or authentication scheme.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

403 response

The user does not have permission to perform this action.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

404 response

Label key not found on project.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties:

500 response

Unexpected error.

Content types: application/json

ErrorResponseApiModel properties:

Details of the error.

ErrorApiModel properties: