---
title: "Create or update annotations"
method: POST
path: "/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotations"
tags: ["LLM Observability"]
---

# Create or update annotations

`POST /api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotations`

Create or update annotations on interactions in a queue. Each annotation is matched
by `interaction_id` and the requesting user's identity.
Results and errors in the response are linked to request items by `interaction_id`.
Errors for individual items are returned in the `errors` field without blocking the rest of the batch.

## Path parameters

- `queue_id` string, required

## Request body

- LLMObsAnnotationsRequest — Request to create or update annotations on interactions in an annotation queue.
  - `data` LLMObsAnnotationsDataRequest, required — Data object for creating or updating annotations.
    - `attributes` LLMObsAnnotationsDataAttributesRequest, required — Attributes for creating or updating annotations.
      - `annotations` LLMObsUpsertAnnotationItem[], required — List of annotations to create or update. Must contain at least one item.
        - `interaction_id` string, required — ID of the interaction to annotate.
        - `label_values` LLMObsAnnotationLabelValue[], required — Label values for this annotation. Each entry references a label schema by ID and provides the corresponding value validated against the schema type constraints.
          - `assessment` 'pass' | 'fail' — Assessment result for a label value.
          - `label_schema_id` string, required — ID of the label schema this value corresponds to.
          - `reasoning` string — Free text reasoning for this label value.
          - `value` union, required — The value for this label. Must comply with the label schema type constraints.
            - number, double — A scalar numeric value.
            - string — A scalar string value.
            - string[] — For categorical-type labels allowing multiple selections.
            - boolean — A scalar boolean value.
    - `type` 'annotations', required — Resource type for LLM Observability annotations.

## Response `200`

OK — annotations created or updated. Per-item errors are listed in `errors`.

- LLMObsAnnotationsResponse — Response containing the created or updated annotations.
  - `data` LLMObsAnnotationsDataResponse, required — Data object for the annotations response.
    - `attributes` LLMObsAnnotationsDataAttributesResponse, required — Attributes of the annotations response.
      - `annotations` LLMObsAnnotationItemResponse[], required — Successfully created or updated annotations.
        - `created_at` string, date-time, required — Timestamp when the annotation was created.
        - `created_by` string, required — Identifier of the user who created the annotation.
        - `id` string, required — Unique identifier of the annotation.
        - `interaction_id` string, required — Identifier of the interaction this annotation belongs to.
        - `label_values` LLMObsAnnotationLabelValueResponse[], required — Label values for this annotation. Each entry references a label schema by ID and provides the corresponding value.
          - `assessment` 'pass' | 'fail' — Assessment result for a label value.
          - `label_schema_id` string, required — ID of the label schema this value corresponds to.
          - `name_when_saved` string — Name of the label schema at the time the annotation was created.
          - `reasoning` string — Free text reasoning for this label value.
          - `type` 'score' | 'categorical' | 'boolean' | 'text' — Type of a label in an annotation queue label schema.
          - `value` union, required — The value for this label. Must comply with the label schema type constraints.
            - number, double — A scalar numeric value.
            - string — A scalar string value.
            - string[] — For categorical-type labels allowing multiple selections.
            - boolean — A scalar boolean value.
        - `modified_at` string, date-time, required — Timestamp when the annotation was last modified.
        - `modified_by` string, required — Identifier of the user who last modified the annotation.
      - `errors` LLMObsAnnotationError[] — Partial errors for annotations that could not be processed.
        - `annotation_id` string — ID of the annotation that failed, if applicable.
        - `error` string, required — Error message.
        - `interaction_id` string, required — ID of the interaction that failed.
    - `id` string, required — The annotation queue ID.
    - `type` 'annotations', required — Resource type for LLM Observability annotations.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found — the queue does not exist.
- `429` — Too many requests

---

[API](https://skmtc.dev/datadog/apis/api-v2.md) · [All operations](https://skmtc.dev/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)