> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset and annotation mutations

> Tag datasets and experiments, edit examples, and manage annotation queues. Arguments, return types and a validated example for each of the 9 mutations.

Tag datasets and experiments, edit examples, and manage annotation queues.

For task-oriented walkthroughs of these operations, see the [Dataset and annotation guide](/docs/ax/graphql-reference/guides/datasets-and-annotations.md). Every mutation below is sent as a `POST` to `https://app.arize.com/graphql` with an `x-api-key` header; see [Forming calls](/docs/ax/graphql-reference/overview/how-to-use-graphql/forming-calls.md).

## Mutations in this page

* [`addTagsToDataset`](#addtagstodataset): Add tags to dataset.
* [`removeTagsFromDataset`](#removetagsfromdataset): Remove tags from dataset.
* [`addTagsToExperiment`](#addtagstoexperiment): Add tags to experiment.
* [`removeTagsFromExperiment`](#removetagsfromexperiment): Remove tags from experiment.
* [`updateDatasetVersionExamples`](#updatedatasetversionexamples): Update the examples of a dataset version
* [`createAnnotationConfig`](#createannotationconfig): Create an annotation config
* [`createAnnotationQueue`](#createannotationqueue): Create an annotation queue
* [`updateAnnotations`](#updateannotations): Update the annotations of a dataset
* [`batchUpdateAnnotations`](#batchupdateannotations): Batch update the annotations of a dataset.

## Reference

### addTagsToDataset

`addTagsToDataset(input: AddTagsToDatasetInput!): AddTagsToDatasetPayload`

#### Arguments

**input** `AddTagsToDatasetInput!` *required*

**AddTagsToDatasetInput fields**

**datasetId** `ID!` *required*

**tagIds** `[ID!]!` *required*

**clientMutationId** `String`

#### Returns

**result** `AddTagsToDatasetResult!`

Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation AddTagsToDataset($input: AddTagsToDatasetInput!) {
  addTagsToDataset(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "datasetId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}
```

### removeTagsFromDataset

`removeTagsFromDataset(input: RemoveTagsFromDatasetInput!): RemoveTagsFromDatasetPayload`

#### Arguments

**input** `RemoveTagsFromDatasetInput!` *required*

**RemoveTagsFromDatasetInput fields**

**datasetId** `ID!` *required*

**tagIds** `[ID!]!` *required*

**clientMutationId** `String`

#### Returns

**result** `RemoveTagsFromDatasetResult!`

Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation RemoveTagsFromDataset($input: RemoveTagsFromDatasetInput!) {
  removeTagsFromDataset(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "datasetId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}
```

### addTagsToExperiment

`addTagsToExperiment(input: AddTagsToExperimentInput!): AddTagsToExperimentPayload`

#### Arguments

**input** `AddTagsToExperimentInput!` *required*

**AddTagsToExperimentInput fields**

**experimentId** `ID!` *required*

**tagIds** `[ID!]!` *required*

**clientMutationId** `String`

#### Returns

**result** `AddTagsToExperimentResult!`

Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation AddTagsToExperiment($input: AddTagsToExperimentInput!) {
  addTagsToExperiment(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "experimentId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}
```

### removeTagsFromExperiment

`removeTagsFromExperiment(input: RemoveTagsFromExperimentInput!): RemoveTagsFromExperimentPayload`

#### Arguments

**input** `RemoveTagsFromExperimentInput!` *required*

**RemoveTagsFromExperimentInput fields**

**experimentId** `ID!` *required*

**tagIds** `[ID!]!` *required*

**clientMutationId** `String`

#### Returns

**result** `RemoveTagsFromExperimentResult!`

Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation RemoveTagsFromExperiment($input: RemoveTagsFromExperimentInput!) {
  removeTagsFromExperiment(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "experimentId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}
```

### updateDatasetVersionExamples

Update the examples of a dataset version

`updateDatasetVersionExamples(input: UpdateDatasetVersionExamplesInput!): UpdateDatasetVersionExamplesPayload`

#### Arguments

**input** `UpdateDatasetVersionExamplesInput!` *required*

**UpdateDatasetVersionExamplesInput fields**

**datasetVersionId** `ID!` *required*

The id of the dataset version to update

**updates** `[ExampleUpdate!]`

The updates to apply to the examples

**ExampleUpdate fields**

**id** `ID!` *required*

The id of the example

**patches** `[ExamplePatch!]!` *required*

The patches to apply to the example

**ExamplePatch fields**

**columnName** `String!` *required*

The name of the column to patch

**dataType** `DimensionDataType!` *required*

The data type of the column to patch, used to parse the value One of: `STRING`, `LONG`, `FLOAT`, `DOUBLE`, `EMBEDDING`, `STRING_LIST`, `DICTIONARY`.

**value** `String!` *required*

The stringified updated value, the data type is used to parse it

**modelExamples** `[NewExampleSet!]`

The new examples to add to the dataset version, copied from a previous model or project. Each set selects records or whole sessions.

**NewExampleSet fields**

**modelId** `ID!` *required*

The id of the model or project the examples came from

**modelEnvironment** `ModelEnvironmentName!` *required*

The environment where the examples came from One of: `production`, `validation`, `training`, `tracing`.

**startDate** `DateTime!` *required*

The start date of the interval where the examples exist

**endDate** `DateTime!` *required*

The end date of the interval where the examples exist

**filters** `[FilterItemInput]`

Filters to apply to the interval where the examples exist to narrow down the selection (e.g., by model version or batch id)

**FilterItemInput fields**

**filterType** `FilterRowType!` *required*

The type of filter. One of: `featureLabel`, `tagLabel`, `predictionValue`, `actuals`, `modelVersion`, `batchId`, `predictionClass`, `predictionScore`, `actualClass`, `actualScore`, `topKPercentile`, `spanProperty`, `llmEval`, `annotation`, `userAnnotation`.

**operator** `ComparisonOperator!` *required*

The operator of the filter. One of: `greaterThan`, `lessThan`, `equals`, `notEquals`, `greaterThanOrEqual`, `lessThanOrEqual`, `topN`, `contains`, `containsString`, `similarTo`.

**dimension** `DimensionInput`

The model dimension to filter, e.g. Age. Nested `DimensionInput` (same shape as above).

**dimensionValues** `[DimensionValueInput!]`

The dimension values of the filter. Nested `DimensionValueInput` (same shape as above).

**binaryValues** `[String!]`

The binary values of the prediction.

**numericValues** `[Float!]`

The numeric values of the prediction.

**categoricalValues** `[String!]`

The categorical values of the prediction.

**queryFilter** `String`

Filters to apply to the dataset. Compatible with existing filters, joined with AND.

**records** `RecordSelectionInput`

Copy individual records (spans/predictions) by id. Mutually exclusive with `sessions` and the legacy `recordIds`.

**RecordSelectionInput fields**

**recordIds** `[String!]!` *required*

predictionID for inference records or span id for tracing records. An empty list selects every record matching the set's interval and filters.

**sessions** `SessionSelectionInput`

Copy whole sessions; every span of each selected session becomes an example. Mutually exclusive with `records` and the legacy `recordIds`.

**SessionSelectionInput fields**

**sessionIds** `[String!]!` *required*

The ids of the sessions to copy. An empty list selects every session the Sessions page shows for the set's interval and filters.

**recordIds** `[String!]`

Superseded by `records`. The original ids of the records in the project or model to add to the dataset version. **Deprecated:** Superseded by the records field

**copyFromDatasetVersions** `[CopyExamplesFromDatasetVersionInput!]`

New examples to add to the dataset version, copied by id from one or more source dataset versions entirely server-side (no display truncation)

**CopyExamplesFromDatasetVersionInput fields**

**sourceDatasetVersionId** `ID!` *required*

The id of the dataset version to copy the examples from

**exampleIds** `[String!]!` *required*

The ids of the examples to copy from the source

**deletedRecordIds** `[String!]`

The ids of the examples to delete from the dataset version

**clientMutationId** `String`

#### Returns

**result** `UpdateDatasetVersionExamplesResponse!`

The updated dataset version (with any sampling metadata) or an error Union of `UpdateDatasetVersionExamplesError`, `DatasetVersionWithSampling`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation UpdateDatasetVersionExamples($input: UpdateDatasetVersionExamplesInput!) {
  updateDatasetVersionExamples(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "datasetVersionId": "<ID>"
  }
}
```

### createAnnotationConfig

Create an annotation config

`createAnnotationConfig(input: CreateAnnotationConfigInput!): CreateAnnotationConfigPayload`

#### Arguments

**input** `CreateAnnotationConfigInput!` *required*

**CreateAnnotationConfigInput fields**

**spaceId** `ID!` *required*

The id of the space to create the annotation config in

**annotationName** `String!` *required*

The name of the annotation config

**annotationConfigArgs** `AnnotationConfigArgs!` *required*

**AnnotationConfigArgs fields**

**annotationConfigType** `AnnotationConfigType!` *required*

The type of the annotation config One of: `categorical`, `continuous`, `freeform`.

**categoricalConfig** `CategoricalConfigInput`

The configuration for a categorical annotation config

**CategoricalConfigInput fields**

**labelOptions** `[LabelOptionInput!]!` *required*

A list of label options Nested `LabelOptionInput` (same shape as above).

**optimizationDirection** `OptimizationDirection!` *required*

The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.

**continuousConfig** `ContinuousConfigInput`

The configuration for a continuous annotation config

**ContinuousConfigInput fields**

**minValue** `Float!` *required*

The minimum value

**maxValue** `Float!` *required*

The maximum value

**optimizationDirection** `OptimizationDirection!` *required*

The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.

**clientMutationId** `String`

#### Returns

**annotationConfigOrError** `AnnotationConfigOrError!`

The created annotation config or error Union of `AnnotationConfig`, `CreateAnnotationConfigError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation CreateAnnotationConfig($input: CreateAnnotationConfigInput!) {
  createAnnotationConfig(input: $input) {
    annotationConfigOrError { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "annotationName": "<string>",
    "annotationConfigArgs": {
      "annotationConfigType": "categorical"
    }
  }
}
```

### createAnnotationQueue

Create an annotation queue

`createAnnotationQueue(input: CreateAnnotationQueueInput!): CreateAnnotationQueuePayload`

#### Arguments

**input** `CreateAnnotationQueueInput!` *required*

**CreateAnnotationQueueInput fields**

**spaceId** `ID!` *required*

The id of the space to create the queue in.

**name** `String!` *required*

The name of the queue.

**datasetVersionId** `ID`

\[DEPRECATED] The id of the dataset version from which examples will be added to the queue. If not provided, the queue will be empty. **Deprecated:** Use recordSpecifications for more flexible record selection.

**annotationConfigs** `[AnnotationConfigInput!]`

New annotation configs to create and associate with the queue.

**AnnotationConfigInput fields**

**annotationName** `String!` *required*

The name of the annotation config.

**annotationConfigType** `AnnotationConfigType!` *required*

The type of the annotation config One of: `categorical`, `continuous`, `freeform`.

**categoricalConfig** `CategoricalConfigInput`

The configuration for a categorical annotation config

**CategoricalConfigInput fields**

**labelOptions** `[LabelOptionInput!]!` *required*

A list of label options Nested `LabelOptionInput` (same shape as above).

**optimizationDirection** `OptimizationDirection!` *required*

The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.

**continuousConfig** `ContinuousConfigInput`

The configuration for a continuous annotation config

**ContinuousConfigInput fields**

**minValue** `Float!` *required*

The minimum value

**maxValue** `Float!` *required*

The maximum value

**optimizationDirection** `OptimizationDirection!` *required*

The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.

**annotationConfigIds** `[ID!]`

The ids of existing annotation configs to associate with the queue.

**annotatorAssignment** `AnnotatorAssignment!` *required*

The annotators assigned to the queue. Either a specific list of user ids or all annotators in the space.

**AnnotatorAssignment fields**

**userIds** `[ID!]!` *required*

The ids of the users in the space assigned to annotate the queue.

**assignmentMethod** `AnnotationQueueAssignmentMethod!` *required*

The method used to assign records in the queue to annotators. One of: `all`, `random`.

**recordIds** `[String!]`

\[DEPRECATED] The ids of the records to create the queue with. If provided, the queue will be populated with the corresponding records from the dataset version. **Deprecated:** Use recordSpecifications for more flexible record selection.

**instructions** `String`

The instructions for the queue.

**recordSpecifications** `[AnnotationQueueRecordSpecificationInput!]`

The specifications for the records to be added to the queue.

**AnnotationQueueRecordSpecificationInput fields**

**sourceType** `RecordSourceType!` *required*

The source type of the records to add to the queue. One of: `spans`, `dataset`.

**recordIds** `[String!]`

The ids of the records to add to the annotation queue. If no records are provided, then all records that match the other criteria will be added.

**startDate** `DateTime`

The start date of the interval where the records exist. Required if the source type is spans.

**endDate** `DateTime`

The end date of the interval where the records exist. Required if the source type is spans.

**datasetVersionId** `ID`

The dataset version id. Required if the source type is dataset.

**modelId** `ID`

The model id. Required if the source type is spans.

**maxRecords** `Int`

The maximum number of records that can be in the queue. Must be between 1 and 5000.

**columnAllowlist** `[String!]`

The record column names annotators are allowed to see in the queue. If omitted or empty, annotators see all columns.

**clientMutationId** `String`

#### Returns

**annotationQueueOrError** `AnnotationQueueOrError!`

returns the created annotation queue or error Union of `AnnotationQueue`, `AnnotationQueueError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation CreateAnnotationQueue($input: CreateAnnotationQueueInput!) {
  createAnnotationQueue(input: $input) {
    annotationQueueOrError { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "name": "<string>",
    "annotatorAssignment": {
      "userIds": [
        "<ID>"
      ]
    },
    "assignmentMethod": "all"
  }
}
```

### updateAnnotations

Update the annotations of a dataset

`updateAnnotations(input: UpdateAnnotationsInput!): UpdateAnnotationsPayload`

#### Arguments

**input** `UpdateAnnotationsInput!` *required*

**UpdateAnnotationsInput fields**

**annotationUpdates** `[AnnotationWithConfigIdInput!]!` *required*

The annotations to update

**AnnotationWithConfigIdInput fields**

**annotationConfigId** `ID!` *required*

The ID of the annotation config

**annotation** `AnnotationInput!` *required*

The annotation to update

**AnnotationInput fields**

**name** `String!` *required*

The name of the annotation

**updatedBy** `String`

Who is updating the annotation

**label** `String`

The label of the annotation

**score** `Float`

The score of the annotation

**text** `String`

The freeform text of the annotation

**annotationType** `AnnotationType!` *required*

The type of the annotation One of: `Label`, `Score`, `Text`.

**note** `NoteInput`

\[DEPRECATED] The note to update the annotation with. **Deprecated:** Use freeform text annotations instead.

**NoteInput fields**

**text** `String!` *required*

The text of the note

**modelRecordContext** `ModelRecordContextInput`

The model record context. If provided, the annotation updates will be written on the record.

**ModelRecordContextInput fields**

**modelId** `ID!` *required*

The id of the model to update the annotations on.

**modelEnvironment** `ModelEnvironmentName!` *required*

One of: `production`, `validation`, `training`, `tracing`.

**recordId** `String!` *required*

The record id of the span/trace to update the annotations on.

**startTime** `DateTime!` *required*

**recordGranularity** `RecordGranularity`

Whether the record is a span or a trace. One of: `span`, `trace`, `session`.

**experimentRunContext** `ExperimentRunContextInput`

The experiment run context. If provided, the annotation updates will be written on the experiment run.

**ExperimentRunContextInput fields**

**experimentId** `ID!` *required*

The id of the experiment

**runId** `String!` *required*

The id of the experiment run

**datasetRecordContext** `DatasetRecordContextInput`

The dataset record context. If provided, the annotation updates will be written to the dataset record.

**DatasetRecordContextInput fields**

**datasetVersionId** `ID!` *required*

The id of the dataset version to update the annotations on.

**recordId** `String!` *required*

The record id of the dataset record to update the annotations on

**clientMutationId** `String`

#### Returns

**result** `UpdateAnnotationResultType!`

The updated result Union of `UpdateAnnotationSuccess`, `UpdateAnnotationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation UpdateAnnotations($input: UpdateAnnotationsInput!) {
  updateAnnotations(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "annotationUpdates": [
      {
        "annotationConfigId": "<ID>",
        "annotation": {
          "name": "<string>",
          "annotationType": "Label"
        }
      }
    ]
  }
}
```

### batchUpdateAnnotations

Batch update the annotations of a dataset.

`batchUpdateAnnotations(input: BatchUpdateAnnotationsInput!): BatchUpdateAnnotationsPayload`

#### Arguments

**input** `BatchUpdateAnnotationsInput!` *required*

**BatchUpdateAnnotationsInput fields**

**modelId** `ID!` *required*

The id of the model to update the annotations on.

**recordAnnotationUpdates** `[RecordAnnotationUpdateInput!]!` *required*

The records to update with their annotations.

**RecordAnnotationUpdateInput fields**

**recordId** `String!` *required*

The record id of the span/trace to update the annotations on.

**startTime** `DateTime!` *required*

The timestamp of the record.

**annotationUpdates** `[AnnotationWithConfigIdInput!]!` *required*

The annotation updates for this record.

**AnnotationWithConfigIdInput fields**

**annotationConfigId** `ID!` *required*

The ID of the annotation config

**annotation** `AnnotationInput!` *required*

The annotation to update Nested `AnnotationInput` (same shape as above).

**note** `NoteInput`

\[DEPRECATED] Optional note to add to this record. **Deprecated:** Use freeform text annotations instead.

**NoteInput fields**

**text** `String!` *required*

The text of the note

**recordGranularity** `RecordGranularity`

Whether the batch contains spans or traces. One of: `span`, `trace`, `session`.

**clientMutationId** `String`

#### Returns

**result** `BatchUpdateAnnotationsResultType!`

The update result Union of `BatchUpdateAnnotationSuccess`, `BatchUpdateAnnotationError`. Use inline fragments (`... on TypeName`).

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph.md) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation BatchUpdateAnnotations($input: BatchUpdateAnnotationsInput!) {
  batchUpdateAnnotations(input: $input) {
    result { __typename }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "modelId": "<ID>",
    "recordAnnotationUpdates": [
      {
        "recordId": "<string>",
        "startTime": "2026-01-01T00:00:00Z",
        "annotationUpdates": [
          {
            "annotationConfigId": "<ID>",
            "annotation": {
              "name": "<string>",
              "annotationType": "Label"
            }
          }
        ]
      }
    ]
  }
}
```