Dataset and annotation mutations

Tag datasets and experiments, edit examples, and manage annotation queues. For task-oriented walkthroughs of these operations, see the Dataset and annotation guide. Every mutation below is sent as a POST to https://app.arize.com/graphql with an x-api-key header; see Forming calls.

Mutations in this page

addTagsToDataset: Add tags to dataset.
removeTagsFromDataset: Remove tags from dataset.
addTagsToExperiment: Add tags to experiment.
removeTagsFromExperiment: Remove tags from experiment.
updateDatasetVersionExamples: Update the examples of a dataset version
createAnnotationConfig: Create an annotation config
createAnnotationQueue: Create an annotation queue
updateAnnotations: Update the annotations of a dataset
batchUpdateAnnotations: Batch update the annotations of a dataset.

Reference

addTagsToDataset

addTagsToDataset(input: AddTagsToDatasetInput!): AddTagsToDatasetPayload

Arguments

AddTagsToDatasetInput!

required

Show AddTagsToDatasetInput fields

ID!

required

[ID!]!

required

String

Returns

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 page shows how to look IDs up.

mutation AddTagsToDataset($input: AddTagsToDatasetInput!) {
  addTagsToDataset(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "datasetId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}

removeTagsFromDataset

removeTagsFromDataset(input: RemoveTagsFromDatasetInput!): RemoveTagsFromDatasetPayload

Arguments

RemoveTagsFromDatasetInput!

required

Show RemoveTagsFromDatasetInput fields

ID!

required

[ID!]!

required

String

Returns

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 page shows how to look IDs up.

mutation RemoveTagsFromDataset($input: RemoveTagsFromDatasetInput!) {
  removeTagsFromDataset(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "datasetId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}

addTagsToExperiment

addTagsToExperiment(input: AddTagsToExperimentInput!): AddTagsToExperimentPayload

Arguments

AddTagsToExperimentInput!

required

Show AddTagsToExperimentInput fields

ID!

required

[ID!]!

required

String

Returns

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 page shows how to look IDs up.

mutation AddTagsToExperiment($input: AddTagsToExperimentInput!) {
  addTagsToExperiment(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "experimentId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}

removeTagsFromExperiment

removeTagsFromExperiment(input: RemoveTagsFromExperimentInput!): RemoveTagsFromExperimentPayload

Arguments

RemoveTagsFromExperimentInput!

required

Show RemoveTagsFromExperimentInput fields

ID!

required

[ID!]!

required

String

Returns

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 page shows how to look IDs up.

mutation RemoveTagsFromExperiment($input: RemoveTagsFromExperimentInput!) {
  removeTagsFromExperiment(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "experimentId": "<ID>",
    "tagIds": [
      "<ID>"
    ]
  }
}

updateDatasetVersionExamples

Update the examples of a dataset version updateDatasetVersionExamples(input: UpdateDatasetVersionExamplesInput!): UpdateDatasetVersionExamplesPayload

Arguments

UpdateDatasetVersionExamplesInput!

required

Show UpdateDatasetVersionExamplesInput fields

ID!

required

The id of the dataset version to update

[ExampleUpdate!]

The updates to apply to the examples

Show ExampleUpdate fields

ID!

required

The id of the example

[ExamplePatch!]!

required

The patches to apply to the example

Show ExamplePatch fields

String!

required

The name of the column to patch

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.

String!

required

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

[NewExampleSet!]

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

Show NewExampleSet fields

ID!

required

The id of the model or project the examples came from

ModelEnvironmentName!

required

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

DateTime!

required

The start date of the interval where the examples exist

DateTime!

required

The end date of the interval where the examples exist

[FilterItemInput]

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

Show FilterItemInput fields

FilterRowType!

required

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

ComparisonOperator!

required

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

DimensionInput

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

[DimensionValueInput!]

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

[String!]

The binary values of the prediction.

[Float!]

The numeric values of the prediction.

[String!]

The categorical values of the prediction.

String

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

RecordSelectionInput

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

Show RecordSelectionInput fields

[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.

SessionSelectionInput

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

Show SessionSelectionInput fields

[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.

[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

[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)

Show CopyExamplesFromDatasetVersionInput fields

ID!

required

The id of the dataset version to copy the examples from

[String!]!

required

The ids of the examples to copy from the source

[String!]

The ids of the examples to delete from the dataset version

String

Returns

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 page shows how to look IDs up.

mutation UpdateDatasetVersionExamples($input: UpdateDatasetVersionExamplesInput!) {
  updateDatasetVersionExamples(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "datasetVersionId": "<ID>"
  }
}

createAnnotationConfig

Create an annotation config createAnnotationConfig(input: CreateAnnotationConfigInput!): CreateAnnotationConfigPayload

Arguments

CreateAnnotationConfigInput!

required

Show CreateAnnotationConfigInput fields

ID!

required

The id of the space to create the annotation config in

String!

required

The name of the annotation config

AnnotationConfigArgs!

required

Show AnnotationConfigArgs fields

AnnotationConfigType!

required

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

CategoricalConfigInput

The configuration for a categorical annotation config

Show CategoricalConfigInput fields

[LabelOptionInput!]!

required

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

OptimizationDirection!

required

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

ContinuousConfigInput

The configuration for a continuous annotation config

Show ContinuousConfigInput fields

Float!

required

The minimum value

Float!

required

The maximum value

OptimizationDirection!

required

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

String

Returns

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 page shows how to look IDs up.

mutation CreateAnnotationConfig($input: CreateAnnotationConfigInput!) {
  createAnnotationConfig(input: $input) {
    annotationConfigOrError { __typename }
  }
}

{
  "input": {
    "spaceId": "<ID>",
    "annotationName": "<string>",
    "annotationConfigArgs": {
      "annotationConfigType": "categorical"
    }
  }
}

createAnnotationQueue

Create an annotation queue createAnnotationQueue(input: CreateAnnotationQueueInput!): CreateAnnotationQueuePayload

Arguments

CreateAnnotationQueueInput!

required

Show CreateAnnotationQueueInput fields

ID!

required

The id of the space to create the queue in.

String!

required

The name of the queue.

[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.

[AnnotationConfigInput!]

New annotation configs to create and associate with the queue.

Show AnnotationConfigInput fields

String!

required

The name of the annotation config.

AnnotationConfigType!

required

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

CategoricalConfigInput

The configuration for a categorical annotation config

Show CategoricalConfigInput fields

[LabelOptionInput!]!

required

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

OptimizationDirection!

required

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

ContinuousConfigInput

The configuration for a continuous annotation config

Show ContinuousConfigInput fields

Float!

required

The minimum value

Float!

required

The maximum value

OptimizationDirection!

required

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

[ID!]

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

AnnotatorAssignment!

required

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

Show AnnotatorAssignment fields

[ID!]!

required

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

AnnotationQueueAssignmentMethod!

required

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

[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.

String

The instructions for the queue.

[AnnotationQueueRecordSpecificationInput!]

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

Show AnnotationQueueRecordSpecificationInput fields

RecordSourceType!

required

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

[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.

DateTime

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

DateTime

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

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

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

Int

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

[String!]

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

String

Returns

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 page shows how to look IDs up.

mutation CreateAnnotationQueue($input: CreateAnnotationQueueInput!) {
  createAnnotationQueue(input: $input) {
    annotationQueueOrError { __typename }
  }
}

{
  "input": {
    "spaceId": "<ID>",
    "name": "<string>",
    "annotatorAssignment": {
      "userIds": [
        "<ID>"
      ]
    },
    "assignmentMethod": "all"
  }
}

updateAnnotations

Update the annotations of a dataset updateAnnotations(input: UpdateAnnotationsInput!): UpdateAnnotationsPayload

Arguments

UpdateAnnotationsInput!

required

Show UpdateAnnotationsInput fields

[AnnotationWithConfigIdInput!]!

required

The annotations to update

Show AnnotationWithConfigIdInput fields

ID!

required

The ID of the annotation config

AnnotationInput!

required

The annotation to update

Show AnnotationInput fields

String!

required

The name of the annotation

String

Who is updating the annotation

String

The label of the annotation

Float

The score of the annotation

String

The freeform text of the annotation

AnnotationType!

required

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

NoteInput

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

Show NoteInput fields

String!

required

The text of the note

ModelRecordContextInput

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

Show ModelRecordContextInput fields

ID!

required

The id of the model to update the annotations on.

ModelEnvironmentName!

required

One of: production, validation, training, tracing.

String!

required

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

DateTime!

required

RecordGranularity

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

ExperimentRunContextInput

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

Show ExperimentRunContextInput fields

ID!

required

The id of the experiment

String!

required

The id of the experiment run

DatasetRecordContextInput

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

Show DatasetRecordContextInput fields

ID!

required

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

String!

required

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

String

Returns

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 page shows how to look IDs up.

mutation UpdateAnnotations($input: UpdateAnnotationsInput!) {
  updateAnnotations(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "annotationUpdates": [
      {
        "annotationConfigId": "<ID>",
        "annotation": {
          "name": "<string>",
          "annotationType": "Label"
        }
      }
    ]
  }
}

batchUpdateAnnotations

Batch update the annotations of a dataset. batchUpdateAnnotations(input: BatchUpdateAnnotationsInput!): BatchUpdateAnnotationsPayload

Arguments

BatchUpdateAnnotationsInput!

required

Show BatchUpdateAnnotationsInput fields

ID!

required

The id of the model to update the annotations on.

[RecordAnnotationUpdateInput!]!

required

The records to update with their annotations.

Show RecordAnnotationUpdateInput fields

String!

required

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

DateTime!

required

The timestamp of the record.

[AnnotationWithConfigIdInput!]!

required

The annotation updates for this record.

Show AnnotationWithConfigIdInput fields

ID!

required

The ID of the annotation config

AnnotationInput!

required

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

NoteInput

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

Show NoteInput fields

String!

required

The text of the note

RecordGranularity

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

String

Returns

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 page shows how to look IDs up.

mutation BatchUpdateAnnotations($input: BatchUpdateAnnotationsInput!) {
  batchUpdateAnnotations(input: $input) {
    result { __typename }
  }
}

{
  "input": {
    "modelId": "<ID>",
    "recordAnnotationUpdates": [
      {
        "recordId": "<string>",
        "startTime": "2026-01-01T00:00:00Z",
        "annotationUpdates": [
          {
            "annotationConfigId": "<ID>",
            "annotation": {
              "name": "<string>",
              "annotationType": "Label"
            }
          }
        ]
      }
    ]
  }
}

​Mutations in this page

​Reference

​addTagsToDataset

​Arguments

​Returns

​Example

​removeTagsFromDataset

​Arguments

​Returns

​Example

​addTagsToExperiment

​Arguments

​Returns

​Example

​removeTagsFromExperiment

​Arguments

​Returns

​Example

​updateDatasetVersionExamples

​Arguments

​Returns

​Example

​createAnnotationConfig

​Arguments

​Returns

​Example

​createAnnotationQueue

​Arguments

​Returns

​Example

​updateAnnotations

​Arguments

​Returns

​Example

​batchUpdateAnnotations

​Arguments

​Returns

​Example

Mutations in this page

Reference

addTagsToDataset

Arguments

Returns

Example

removeTagsFromDataset

Arguments

Returns

Example

addTagsToExperiment

Arguments

Returns

Example

removeTagsFromExperiment

Arguments

Returns

Example

updateDatasetVersionExamples

Arguments

Returns

Example

createAnnotationConfig

Arguments

Returns

Example

createAnnotationQueue

Arguments

Returns

Example

updateAnnotations

Arguments

Returns

Example

batchUpdateAnnotations

Arguments

Returns

Example