> ## 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). 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).

## 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

<ParamField body="input" type="AddTagsToDatasetInput!" required>
  <Expandable title="AddTagsToDatasetInput fields">
    <ParamField body="datasetId" type="ID!" required />

    <ParamField body="tagIds" type="[ID!]!" required />

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="AddTagsToDatasetResult!">
  Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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>"
      ]
    }
  }
  ```
</CodeGroup>

### removeTagsFromDataset

`removeTagsFromDataset(input: RemoveTagsFromDatasetInput!): RemoveTagsFromDatasetPayload`

#### Arguments

<ParamField body="input" type="RemoveTagsFromDatasetInput!" required>
  <Expandable title="RemoveTagsFromDatasetInput fields">
    <ParamField body="datasetId" type="ID!" required />

    <ParamField body="tagIds" type="[ID!]!" required />

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="RemoveTagsFromDatasetResult!">
  Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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>"
      ]
    }
  }
  ```
</CodeGroup>

### addTagsToExperiment

`addTagsToExperiment(input: AddTagsToExperimentInput!): AddTagsToExperimentPayload`

#### Arguments

<ParamField body="input" type="AddTagsToExperimentInput!" required>
  <Expandable title="AddTagsToExperimentInput fields">
    <ParamField body="experimentId" type="ID!" required />

    <ParamField body="tagIds" type="[ID!]!" required />

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="AddTagsToExperimentResult!">
  Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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>"
      ]
    }
  }
  ```
</CodeGroup>

### removeTagsFromExperiment

`removeTagsFromExperiment(input: RemoveTagsFromExperimentInput!): RemoveTagsFromExperimentPayload`

#### Arguments

<ParamField body="input" type="RemoveTagsFromExperimentInput!" required>
  <Expandable title="RemoveTagsFromExperimentInput fields">
    <ParamField body="experimentId" type="ID!" required />

    <ParamField body="tagIds" type="[ID!]!" required />

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="RemoveTagsFromExperimentResult!">
  Union of `TagAssociationSuccess`, `TagAssociationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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>"
      ]
    }
  }
  ```
</CodeGroup>

### updateDatasetVersionExamples

Update the examples of a dataset version

`updateDatasetVersionExamples(input: UpdateDatasetVersionExamplesInput!): UpdateDatasetVersionExamplesPayload`

#### Arguments

<ParamField body="input" type="UpdateDatasetVersionExamplesInput!" required>
  <Expandable title="UpdateDatasetVersionExamplesInput fields">
    <ParamField body="datasetVersionId" type="ID!" required>
      The id of the dataset version to update
    </ParamField>

    <ParamField body="updates" type="[ExampleUpdate!]">
      The updates to apply to the examples

      <Expandable title="ExampleUpdate fields">
        <ParamField body="id" type="ID!" required>
          The id of the example
        </ParamField>

        <ParamField body="patches" type="[ExamplePatch!]!" required>
          The patches to apply to the example

          <Expandable title="ExamplePatch fields">
            <ParamField body="columnName" type="String!" required>
              The name of the column to patch
            </ParamField>

            <ParamField body="dataType" type="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`.
            </ParamField>

            <ParamField body="value" type="String!" required>
              The stringified updated value, the data type is used to parse it
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="modelExamples" type="[NewExampleSet!]">
      The new examples to add to the dataset version, copied from a previous model or project. Each set selects records or whole sessions.

      <Expandable title="NewExampleSet fields">
        <ParamField body="modelId" type="ID!" required>
          The id of the model or project the examples came from
        </ParamField>

        <ParamField body="modelEnvironment" type="ModelEnvironmentName!" required>
          The environment where the examples came from One of: `production`, `validation`, `training`, `tracing`.
        </ParamField>

        <ParamField body="startDate" type="DateTime!" required>
          The start date of the interval where the examples exist
        </ParamField>

        <ParamField body="endDate" type="DateTime!" required>
          The end date of the interval where the examples exist
        </ParamField>

        <ParamField body="filters" type="[FilterItemInput]">
          Filters to apply to the interval where the examples exist to narrow down the selection (e.g., by model version or batch id)

          <Expandable title="FilterItemInput fields">
            <ParamField body="filterType" type="FilterRowType!" required>
              The type of filter. One of: `featureLabel`, `tagLabel`, `predictionValue`, `actuals`, `modelVersion`, `batchId`, `predictionClass`, `predictionScore`, `actualClass`, `actualScore`, `topKPercentile`, `spanProperty`, `llmEval`, `annotation`, `userAnnotation`.
            </ParamField>

            <ParamField body="operator" type="ComparisonOperator!" required>
              The operator of the filter. One of: `greaterThan`, `lessThan`, `equals`, `notEquals`, `greaterThanOrEqual`, `lessThanOrEqual`, `topN`, `contains`, `containsString`, `similarTo`.
            </ParamField>

            <ParamField body="dimension" type="DimensionInput">
              The model dimension to filter, e.g. Age. Nested `DimensionInput` (same shape as above).
            </ParamField>

            <ParamField body="dimensionValues" type="[DimensionValueInput!]">
              The dimension values of the filter. Nested `DimensionValueInput` (same shape as above).
            </ParamField>

            <ParamField body="binaryValues" type="[String!]">
              The binary values of the prediction.
            </ParamField>

            <ParamField body="numericValues" type="[Float!]">
              The numeric values of the prediction.
            </ParamField>

            <ParamField body="categoricalValues" type="[String!]">
              The categorical values of the prediction.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="queryFilter" type="String">
          Filters to apply to the dataset. Compatible with existing filters, joined with AND.
        </ParamField>

        <ParamField body="records" type="RecordSelectionInput">
          Copy individual records (spans/predictions) by id. Mutually exclusive with `sessions` and the legacy `recordIds`.

          <Expandable title="RecordSelectionInput fields">
            <ParamField body="recordIds" type="[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.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="sessions" type="SessionSelectionInput">
          Copy whole sessions; every span of each selected session becomes an example. Mutually exclusive with `records` and the legacy `recordIds`.

          <Expandable title="SessionSelectionInput fields">
            <ParamField body="sessionIds" type="[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.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="recordIds" type="[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
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="copyFromDatasetVersions" type="[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)

      <Expandable title="CopyExamplesFromDatasetVersionInput fields">
        <ParamField body="sourceDatasetVersionId" type="ID!" required>
          The id of the dataset version to copy the examples from
        </ParamField>

        <ParamField body="exampleIds" type="[String!]!" required>
          The ids of the examples to copy from the source
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="deletedRecordIds" type="[String!]">
      The ids of the examples to delete from the dataset version
    </ParamField>

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="UpdateDatasetVersionExamplesResponse!">
  The updated dataset version (with any sampling metadata) or an error Union of `UpdateDatasetVersionExamplesError`, `DatasetVersionWithSampling`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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>"
    }
  }
  ```
</CodeGroup>

### createAnnotationConfig

Create an annotation config

`createAnnotationConfig(input: CreateAnnotationConfigInput!): CreateAnnotationConfigPayload`

#### Arguments

<ParamField body="input" type="CreateAnnotationConfigInput!" required>
  <Expandable title="CreateAnnotationConfigInput fields">
    <ParamField body="spaceId" type="ID!" required>
      The id of the space to create the annotation config in
    </ParamField>

    <ParamField body="annotationName" type="String!" required>
      The name of the annotation config
    </ParamField>

    <ParamField body="annotationConfigArgs" type="AnnotationConfigArgs!" required>
      <Expandable title="AnnotationConfigArgs fields">
        <ParamField body="annotationConfigType" type="AnnotationConfigType!" required>
          The type of the annotation config One of: `categorical`, `continuous`, `freeform`.
        </ParamField>

        <ParamField body="categoricalConfig" type="CategoricalConfigInput">
          The configuration for a categorical annotation config

          <Expandable title="CategoricalConfigInput fields">
            <ParamField body="labelOptions" type="[LabelOptionInput!]!" required>
              A list of label options Nested `LabelOptionInput` (same shape as above).
            </ParamField>

            <ParamField body="optimizationDirection" type="OptimizationDirection!" required>
              The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="continuousConfig" type="ContinuousConfigInput">
          The configuration for a continuous annotation config

          <Expandable title="ContinuousConfigInput fields">
            <ParamField body="minValue" type="Float!" required>
              The minimum value
            </ParamField>

            <ParamField body="maxValue" type="Float!" required>
              The maximum value
            </ParamField>

            <ParamField body="optimizationDirection" type="OptimizationDirection!" required>
              The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="annotationConfigOrError" type="AnnotationConfigOrError!">
  The created annotation config or error Union of `AnnotationConfig`, `CreateAnnotationConfigError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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"
      }
    }
  }
  ```
</CodeGroup>

### createAnnotationQueue

Create an annotation queue

`createAnnotationQueue(input: CreateAnnotationQueueInput!): CreateAnnotationQueuePayload`

#### Arguments

<ParamField body="input" type="CreateAnnotationQueueInput!" required>
  <Expandable title="CreateAnnotationQueueInput fields">
    <ParamField body="spaceId" type="ID!" required>
      The id of the space to create the queue in.
    </ParamField>

    <ParamField body="name" type="String!" required>
      The name of the queue.
    </ParamField>

    <ParamField body="datasetVersionId" type="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.
    </ParamField>

    <ParamField body="annotationConfigs" type="[AnnotationConfigInput!]">
      New annotation configs to create and associate with the queue.

      <Expandable title="AnnotationConfigInput fields">
        <ParamField body="annotationName" type="String!" required>
          The name of the annotation config.
        </ParamField>

        <ParamField body="annotationConfigType" type="AnnotationConfigType!" required>
          The type of the annotation config One of: `categorical`, `continuous`, `freeform`.
        </ParamField>

        <ParamField body="categoricalConfig" type="CategoricalConfigInput">
          The configuration for a categorical annotation config

          <Expandable title="CategoricalConfigInput fields">
            <ParamField body="labelOptions" type="[LabelOptionInput!]!" required>
              A list of label options Nested `LabelOptionInput` (same shape as above).
            </ParamField>

            <ParamField body="optimizationDirection" type="OptimizationDirection!" required>
              The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="continuousConfig" type="ContinuousConfigInput">
          The configuration for a continuous annotation config

          <Expandable title="ContinuousConfigInput fields">
            <ParamField body="minValue" type="Float!" required>
              The minimum value
            </ParamField>

            <ParamField body="maxValue" type="Float!" required>
              The maximum value
            </ParamField>

            <ParamField body="optimizationDirection" type="OptimizationDirection!" required>
              The optimization direction for the annotation config One of: `minimize`, `maximize`, `none`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="annotationConfigIds" type="[ID!]">
      The ids of existing annotation configs to associate with the queue.
    </ParamField>

    <ParamField body="annotatorAssignment" type="AnnotatorAssignment!" required>
      The annotators assigned to the queue. Either a specific list of user ids or all annotators in the space.

      <Expandable title="AnnotatorAssignment fields">
        <ParamField body="userIds" type="[ID!]!" required>
          The ids of the users in the space assigned to annotate the queue.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="assignmentMethod" type="AnnotationQueueAssignmentMethod!" required>
      The method used to assign records in the queue to annotators. One of: `all`, `random`.
    </ParamField>

    <ParamField body="recordIds" type="[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.
    </ParamField>

    <ParamField body="instructions" type="String">
      The instructions for the queue.
    </ParamField>

    <ParamField body="recordSpecifications" type="[AnnotationQueueRecordSpecificationInput!]">
      The specifications for the records to be added to the queue.

      <Expandable title="AnnotationQueueRecordSpecificationInput fields">
        <ParamField body="sourceType" type="RecordSourceType!" required>
          The source type of the records to add to the queue. One of: `spans`, `dataset`.
        </ParamField>

        <ParamField body="recordIds" type="[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.
        </ParamField>

        <ParamField body="startDate" type="DateTime">
          The start date of the interval where the records exist. Required if the source type is spans.
        </ParamField>

        <ParamField body="endDate" type="DateTime">
          The end date of the interval where the records exist. Required if the source type is spans.
        </ParamField>

        <ParamField body="datasetVersionId" type="ID">
          The dataset version id. Required if the source type is dataset.
        </ParamField>

        <ParamField body="modelId" type="ID">
          The model id. Required if the source type is spans.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="maxRecords" type="Int">
      The maximum number of records that can be in the queue. Must be between 1 and 5000.
    </ParamField>

    <ParamField body="columnAllowlist" type="[String!]">
      The record column names annotators are allowed to see in the queue. If omitted or empty, annotators see all columns.
    </ParamField>

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="annotationQueueOrError" type="AnnotationQueueOrError!">
  returns the created annotation queue or error Union of `AnnotationQueue`, `AnnotationQueueError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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"
    }
  }
  ```
</CodeGroup>

### updateAnnotations

Update the annotations of a dataset

`updateAnnotations(input: UpdateAnnotationsInput!): UpdateAnnotationsPayload`

#### Arguments

<ParamField body="input" type="UpdateAnnotationsInput!" required>
  <Expandable title="UpdateAnnotationsInput fields">
    <ParamField body="annotationUpdates" type="[AnnotationWithConfigIdInput!]!" required>
      The annotations to update

      <Expandable title="AnnotationWithConfigIdInput fields">
        <ParamField body="annotationConfigId" type="ID!" required>
          The ID of the annotation config
        </ParamField>

        <ParamField body="annotation" type="AnnotationInput!" required>
          The annotation to update

          <Expandable title="AnnotationInput fields">
            <ParamField body="name" type="String!" required>
              The name of the annotation
            </ParamField>

            <ParamField body="updatedBy" type="String">
              Who is updating the annotation
            </ParamField>

            <ParamField body="label" type="String">
              The label of the annotation
            </ParamField>

            <ParamField body="score" type="Float">
              The score of the annotation
            </ParamField>

            <ParamField body="text" type="String">
              The freeform text of the annotation
            </ParamField>

            <ParamField body="annotationType" type="AnnotationType!" required>
              The type of the annotation One of: `Label`, `Score`, `Text`.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="note" type="NoteInput">
      \[DEPRECATED] The note to update the annotation with. **Deprecated:** Use freeform text annotations instead.

      <Expandable title="NoteInput fields">
        <ParamField body="text" type="String!" required>
          The text of the note
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="modelRecordContext" type="ModelRecordContextInput">
      The model record context. If provided, the annotation updates will be written on the record.

      <Expandable title="ModelRecordContextInput fields">
        <ParamField body="modelId" type="ID!" required>
          The id of the model to update the annotations on.
        </ParamField>

        <ParamField body="modelEnvironment" type="ModelEnvironmentName!" required>
          One of: `production`, `validation`, `training`, `tracing`.
        </ParamField>

        <ParamField body="recordId" type="String!" required>
          The record id of the span/trace to update the annotations on.
        </ParamField>

        <ParamField body="startTime" type="DateTime!" required />

        <ParamField body="recordGranularity" type="RecordGranularity">
          Whether the record is a span or a trace. One of: `span`, `trace`, `session`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="experimentRunContext" type="ExperimentRunContextInput">
      The experiment run context. If provided, the annotation updates will be written on the experiment run.

      <Expandable title="ExperimentRunContextInput fields">
        <ParamField body="experimentId" type="ID!" required>
          The id of the experiment
        </ParamField>

        <ParamField body="runId" type="String!" required>
          The id of the experiment run
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="datasetRecordContext" type="DatasetRecordContextInput">
      The dataset record context. If provided, the annotation updates will be written to the dataset record.

      <Expandable title="DatasetRecordContextInput fields">
        <ParamField body="datasetVersionId" type="ID!" required>
          The id of the dataset version to update the annotations on.
        </ParamField>

        <ParamField body="recordId" type="String!" required>
          The record id of the dataset record to update the annotations on
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="UpdateAnnotationResultType!">
  The updated result Union of `UpdateAnnotationSuccess`, `UpdateAnnotationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

### batchUpdateAnnotations

Batch update the annotations of a dataset.

`batchUpdateAnnotations(input: BatchUpdateAnnotationsInput!): BatchUpdateAnnotationsPayload`

#### Arguments

<ParamField body="input" type="BatchUpdateAnnotationsInput!" required>
  <Expandable title="BatchUpdateAnnotationsInput fields">
    <ParamField body="modelId" type="ID!" required>
      The id of the model to update the annotations on.
    </ParamField>

    <ParamField body="recordAnnotationUpdates" type="[RecordAnnotationUpdateInput!]!" required>
      The records to update with their annotations.

      <Expandable title="RecordAnnotationUpdateInput fields">
        <ParamField body="recordId" type="String!" required>
          The record id of the span/trace to update the annotations on.
        </ParamField>

        <ParamField body="startTime" type="DateTime!" required>
          The timestamp of the record.
        </ParamField>

        <ParamField body="annotationUpdates" type="[AnnotationWithConfigIdInput!]!" required>
          The annotation updates for this record.

          <Expandable title="AnnotationWithConfigIdInput fields">
            <ParamField body="annotationConfigId" type="ID!" required>
              The ID of the annotation config
            </ParamField>

            <ParamField body="annotation" type="AnnotationInput!" required>
              The annotation to update Nested `AnnotationInput` (same shape as above).
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="note" type="NoteInput">
          \[DEPRECATED] Optional note to add to this record. **Deprecated:** Use freeform text annotations instead.

          <Expandable title="NoteInput fields">
            <ParamField body="text" type="String!" required>
              The text of the note
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="recordGranularity" type="RecordGranularity">
      Whether the batch contains spans or traces. One of: `span`, `trace`, `session`.
    </ParamField>

    <ParamField body="clientMutationId" type="String" />
  </Expandable>
</ParamField>

#### Returns

<ResponseField name="result" type="BatchUpdateAnnotationsResultType!">
  The update result Union of `BatchUpdateAnnotationSuccess`, `BatchUpdateAnnotationError`. Use inline fragments (`... on TypeName`).
</ResponseField>

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

<CodeGroup>
  ```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"
              }
            }
          ]
        }
      ]
    }
  }
  ```
</CodeGroup>