---
title: "Annotate a span, trace, or session"
method: POST
path: "/api/{org_id}/annotations"
tags: ["Annotations"]
---

# Annotate a span, trace, or session

`POST /api/{org_id}/annotations`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/annotations`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/annotations/post.ts> (a function with typed inputs; its response is checked against the schema)

Validates values against immutable Score Config versions and writes one annotation-source event per Score to the _llm_scores stream.

## Path parameters

- `org_id` string, required

## Request body

- object
  - `metadata` unknown
  - `refTimestamp` integer, required: Original evaluated object's timestamp in microseconds.
  - `scope` string, required: Evaluated target scope: span, trace, or session.
  - `scores` AnnotationScoreRequestBody[], required
    - `metadata` unknown
    - `reasoning` string, nullable
    - `scoreConfigRowId` string, required: Physical row ID of the immutable Score Config version selected by the user.
    - `value` unknown, required
  - `sessionId` string, nullable: Optional parent context for span/trace annotations.
  - `sourceStream` string, required: Trace stream containing the evaluated target.
  - `targetId` string, required: Span ID, trace ID, or session ID according to `scope`.
  - `targetMetadata` AnnotationTargetMetadataRequestBody
    - `agentEnv` string, nullable
    - `agentId` string, nullable
    - `agentName` string, nullable
    - `agentVersion` string, nullable
  - `traceId` string, nullable: Required for span annotations; optional context for trace annotations.

## Response `200`

- object
  - `annotatedAt` integer, required
  - `annotationId` string, required
  - `scoreIds` string[], required

## Other responses

- `400`: Invalid target, Score Config, or Score value
- `403`: A selected Score Config is not visible

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)