Overview

Learn how annotations enhance trace review, labeling, and evaluation workflows for more reliable AI agent testing.

Intro

With the Annotations API, you can annotate traces with additional information. This is useful if you want to add additional information to a trace, such as a comment or a thumbs up/down reaction.

Authentication

To make a call to the Annotations API, you will need to pass through your LangWatch API key in the header as X-Auth-Token. Your API key can be found on the setup page under settings.

Allowed Methods

• GET /api/v1/annotations - Get a list of annotations
• GET /api/v1/annotations/:id - Get a single annotation
• DELETE /api/v1/annotations/:id - Delete a single annotation
• PATCH /api/v1/annotations/:id - Update a single annotation
• GET /api/v1/annotations/trace/:id - Get the annotations for a single trace
• POST /api/v1/annotations/trace/:id - Create annotations for traces to support domain labeling, evaluation scoring, and agent testing workflows.

Annotation queues

Annotation queues have no REST endpoints yet. To send traces to a queue from code, create an automation with the ADD_TO_ANNOTATION_QUEUE action (Triggers API); to read queues and their items, query the annotation_queues and annotation_queue_items views with LangWatchQL. See Annotation queues.