Observability API
LLM application observability data plane (compatible with Langfuse semantics): trace / observation / score event ingestion (both batch JSON and OpenTelemetry entry points), trace / session / user / score queries, metrics queries, execution log correlation, and project ingestion status.
Service and resource boundaries
The Observability API (/v1/observability/*) provides full-stack GenAI observability and quality assessment services compatible with the OpenTelemetry (OTLP) and Langfuse data models: covering Trace / Observation (Span / Generation / Tool / Retriever / Guardrail) / Score batch and streaming ingestion, multi-dimensional trace and session retrieval, token and latency aggregate metrics queries, score root cause analysis (Analysis), evaluation prompt version resolution, and knowledge index quality assessment task orchestration.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/observability.Data hierarchy:
session→trace({traceId}) → observation (span/generation events);scoreattach to trace/observation;user({userId}) aggregate by trace attribution.Two ingestion entry points:
POST /observability/ingestion(platform batch JSON) andPOST /observability/otel/v1/traces(OpenTelemetry HTTP JSON / protobuf).
Authentication and Permissions
For authentication and request header conventions, see general conventions. Scopes in this domain are divided by sub-capability: observability.ingest.write (ingestion), observability.traces.read, observability.sessions.read, observability.users.read, observability.scores.read, observability.metrics.read, observability.status.read, traceLogs.read (execution logs).
Endpoint overview
The Observability module provides 23 endpoints in total, divided into five major capability domains: dual-channel event ingestion (/ingestion and /otel/v1/traces), trace and entity retrieval (/traces*, /observations, /sessions*, /users*, /logs), scoring and root cause insights (/scores*, /score-configs), knowledge index and MCP evaluation (/evals/*, /prompts/resolve), and multi-dimensional metrics aggregation and status queries (/metrics, /observability).
Endpoint List
| Method + path | Purpose |
|---|---|
POST /observability/ingestion | Batch ingest trace/observation/score events |
POST /observability/otel/v1/traces | OpenTelemetry traces ingestion |
GET /observability/traces / GET .../traces/{traceId} | Trace list/detail |
GET /observability/sessions / GET .../sessions/{sessionId} | Session list/detail |
GET /observability/users / GET .../users/{userId} | User list/detail |
GET /observability/scores (2.9.0 +scoreId parameters) / GET .../score-configs | Score list/configuration |
GET /observability/observations | Observation list (2.9.0 new: name/type/time/level/traceId/environment filters) |
GET .../scores/{scoreId}/analysis · GET .../scores/{scoreId}/quality-details | Score root cause analysis detail / resolved evaluation per-page per-chunk detail (2.9.0 new); from 2.10.0 onward the kind enum is extended with index (knowledge index quality per-record detail) |
POST .../scores/analysis/summaries · POST .../scores/analysis/trigger | Analysis insight summary / batch trigger (≤100 per batch, new in 2.9.0) |
POST /observability/evals/index-preview · POST /observability/evals/index | Knowledge index quality assessment: preview estimated record counts per assessment type / create assessment task (2.10.0 new, scope observability.evals.read / observability.evals.write) |
GET /observability/prompts/resolve | Resolve evaluation prompt by name + label (default production) or exact version; label and version are mutually exclusive (2.10.0 new, scope observability.prompts.read) |
POST /observability/evals/mcp/tools | Discover read-only MCP tools for evaluation (2.8.0) |
POST /observability/metrics | Metrics query |
GET /observability/logs | Fetch execution output logs by trace/execution |
GET /observability | Project ingestion status |
Endpoint details
W3C Trace Context and ID formats:
/observability/otel/v1/tracesfollows W3C, requiring non-zero, 32-character lowercase hexadecimaltraceIdvalues and non-zero, 16-character lowercase hexadecimalspanIdvalues./observability/ingestionalso recommends this format to carrytraceparentacross services; Events itself supports ordinary non-empty entity IDs and does not restrict them to hexadecimal. An Observation should end at or after its start time.Partial-success multi-status response (
207 Multi-Status): batch ingestion endpoints validate and persist each event independently; if any events in the batch are malformed,207is returned with theidand reasons of successful and failed events listed separately in the response body.
Requests and Responses
Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), call examples (copyable curl) and response examples. Endpoints marked with "generalized schema any" return the JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for specific fields.
Ingestion
POST /v1/observability/ingestion
Batch ingest trace / observation / score events (Langfuse event model): 1–100 events per batch; if all are accepted, 200 is returned; if any event is rejected, 207 is returned with a per-event report.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
batch | body | object[] | Yes | — | Event array (1–100 items). For element structure, see the batch[] subfield rows. The event model follows the Langfuse ingestion contract; the specification exposes it as the generic type object[]. |
metadata | body | object | No | — | Batch-wide ingestion metadata (e.g., sdk, sdkVersion), optional. |
batch[].id | body | string | Yes | — | Event idempotency ID (e.g., UUID); use a new unique value for each create / update event, and reuse the original id on retries to guarantee idempotency. |
batch[].type | body | string | Yes | See notes for enum | Event type: trace-create; span-create / span-update; generation-create / generation-update; score-create; also supports event-create, agent-create, tool-create, chain-create, retriever-create, evaluator-create, embedding-create, guardrail-create (compatibility aliases observation-create / observation-update not recommended for new code). |
batch[].timestamp | body | string | Yes | — | Event time, an ISO 8601 string with timezone. |
batch[].body | body | object | Yes | — | Entity field object; fields depend on the event type, see below. |
batch[].body.id | body | string | Yes | — | Entity ID: prefer non-zero, 32-character lowercase hexadecimal Trace IDs and non-zero, 16-character lowercase hexadecimal Observation IDs for W3C traceparent correlation; keep unchanged when updating the same entity. |
batch[].body.name | body | string | No | — | Entity name (e.g., support-agent.run, llm.answer). |
batch[].body.timestamp | body | string | No | — | Entity occurrence time (ISO 8601). |
batch[].body.traceId | body | string | Required for observation | — | The body.id of the root Trace this belongs to; a child Observation additionally uses parentObservationId to point to its parent Observation. |
batch[].body.userId / sessionId | body | string | No | — | Owning user and session: userId aggregates into the users view, sessionId aggregates into the sessions view. |
batch[].body.environment / release / tags | body | string / string[] | No | — | Deployment context: environment only lowercase letters, digits, -, _ (≤40 characters), release version string, tags array of tags. |
batch[].body.input / output | body | any | No | — | Input / output payload (recommend reporting after desensitization). |
batch[].body.startTime / endTime | body | string | Commonly used for observation | — | Observation start/end times (ISO 8601). |
batch[].body.parentObservationId | body | string | No | — | The body.id of the parent Observation (forms the span tree). |
batch[].body.level / statusMessage | body | string | No | Enum DEBUG, DEFAULT, WARNING, ERROR | Observation level and status message. |
batch[].body.model / modelParameters / completionStartTime | body | string / object | No | — | Generation-specific: model ID, model parameters, and completion start time. |
batch[].body.usage / usageDetails / costDetails | body | object | No | — | Generation-specific: token usage (e.g., {input: 120, output: 48, total: 168, unit: "TOKENS"}) and cost detail. |
batch[].body.value / dataType | body | number / string | Required for score | — | Score-specific: score value and data type (NUMERIC / CATEGORICAL); target specified by one of traceId / observationId / sessionId. |
batch[].metadata | body | object | No | — | Event-level metadata. |
Output: Returns per-event acceptance results: successes[] (accepted events) and errors[] (rejected events); all passed yields 200, any failure yields 207 Multi-Status.
| Field | Type | Description |
|---|---|---|
successes | object[] | Accepted event: id (outer event ID) + status (201) |
errors | object[] | Rejected event: id + status (HTTP semantic code) + message (rejection reason) |
idrefers to the event idempotency ID;body.idrefers to the entity ID: keepbody.idunchanged when updating the same trace / observation / score.Recommended: traces use non-all-zero 32-character lowercase hexadecimal, observations use 16-character lowercase hexadecimal, so the same set of IDs can be reused as a W3C
traceparent.200/207indicate acceptance by the ingestion entry point; readback may 404 before the asynchronous worker finishes persisting—use short polling to wait.Network errors,
429, and recoverable5xxcan be retried with capped exponential backoff while reusing the outerid; do not blindly retry schema / permission4xx.
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/ingestion" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"batch": [
{
"id": "evt-0f3a2b71-create",
"type": "trace-create",
"timestamp": "2026-09-14T02:30:00.000Z",
"body": {
"id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"timestamp": "2026-09-14T02:30:00.000Z",
"name": "support-agent.run",
"userId": "user_42",
"sessionId": "session-20260914-001",
"environment": "production",
"release": "2026.09.14",
"tags": ["agent", "support"],
"input": { "question": "订单 20260914 号何时发货?" }
}
},
{
"id": "evt-0f3a2b72-gen",
"type": "generation-create",
"timestamp": "2026-09-14T02:30:01.200Z",
"body": {
"id": "a1b2c3d4e5f60718",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"name": "llm.answer",
"startTime": "2026-09-14T02:30:01.000Z",
"model": "gpt-4o-mini",
"modelParameters": { "temperature": 0.7 },
"input": { "messages": 3 }
}
},
{
"id": "evt-0f3a2b73-genupd",
"type": "generation-update",
"timestamp": "2026-09-14T02:30:03.900Z",
"body": {
"id": "a1b2c3d4e5f60718",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"endTime": "2026-09-14T02:30:03.800Z",
"output": { "answerChars": 186 },
"usage": { "input": 412, "output": 96, "total": 508, "unit": "TOKENS" }
}
},
{
"id": "evt-0f3a2b74-score",
"type": "score-create",
"timestamp": "2026-09-14T02:30:04.500Z",
"body": {
"id": "score-0001",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"name": "user-feedback",
"value": 0.9,
"dataType": "NUMERIC"
}
}
],
"metadata": { "sdk": "custom-agent", "sdkVersion": "1.0.0" }
}'Response example:
{
"successes": [
{
"id": "evt-0f3a2b71-create",
"status": 201
},
{
"id": "evt-0f3a2b72-gen",
"status": 201
},
{
"id": "evt-0f3a2b73-genupd",
"status": 201
}
],
"errors": [
{
"id": "evt-0f3a2b74-score",
"status": 400,
"message": "Invalid request data"
}
]
}POST /v1/observability/otel/v1/traces
Ingest traces in the OpenTelemetry standard format: accepts OTLP HTTP JSON or protobuf (gzip allowed), mapped to the platform trace / observation model according to gen_ai semantic conventions.
Input: No path/query parameters; the request body is raw ExportTraceServiceRequest JSON or protobuf; JSON uses the resourceSpans → scopeSpans → spans structure without additional Agentbase wrapper fields.
Output: Returns 200; the response is the successes / errors batch result of the converted events. Request constraints: Content-Type: application/json or application/x-protobuf; optional Content-Encoding: gzip; both the raw and decompressed request body must be non-empty and no more than 4,718,592 bytes (4.5 MiB).
When configuring the OTel exporter, use this endpoint directly as the traces-only endpoint (
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) to prevent the exporter from automatically appending/v1/traces.This endpoint is not an OTLP gRPC endpoint; authentication still uses the project dual headers (
X-Appwrite-Project+X-Appwrite-Key).For direct HTTP calls, pass OTLP JSON / protobuf as-is in the body; do not wrap it in another layer of JSON.
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/otel/v1/traces" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
--data-binary @otlp-traces.json
# otlp-traces.json is a standard OTLP ExportTraceServiceRequest JSON document (resourceSpans → scopeSpans → spans)Minimal OTLP JSON (save as otlp-traces.json; the IDs below are examples; real calls should generate their own non-all-zero Trace/Span IDs):
{
"resourceSpans": [{
"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "example-agent"}}]},
"scopeSpans": [{
"scope": {"name": "example-instrumentation"},
"spans": [{
"traceId": "0123456789abcdef0123456789abcdef",
"spanId": "0123456789abcdef",
"name": "agent.run",
"kind": 1,
"startTimeUnixNano": "1788836400000000000",
"endTimeUnixNano": "1788836401000000000",
"status": {"code": 1}
}]
}]
}]
}Response example:
{
"successes": [{"id": "converted-event-id", "status": 201}],
"errors": []
}In this version, OTLP is forwarded via an HTTP action that converts the result internally; the HTTP 200 must also check errors[] and cannot be parsed as a standard partialSuccess response. The Events entry point returns 207 on per-item failure. Acceptance does not mean asynchronous ingestion is complete; verify by querying the same Trace ID with read credentials that have observability.traces.read; do not treat a standard exporter's lack of errors as evidence of full persistence.
POST /v1/observability/evals/mcp/tools(2.8.0)
Discover read-only MCP tools available for evaluation: before an evaluation task attaches MCP tools to the evaluator, use restricted gateway credentials to list the side-effect-free MCP tools on that AI Gateway (added in 2.8.0).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
gatewayId | body | string | Yes | — | The gateway ID of the AI Gateway. |
gatewayKeyId | body | string | Yes | — | The restricted Gateway Key (sub-key) ID: must be an active credential bound to that gateway, explicitly scoped to tools, and without model / Agent permissions. |
Output: Returns 200 + the tool list tools[] (generalized schema any: each tool contains fields such as toolId / revisionId / targetRevisionId / name / inputSchemaHash; refer to the actual response for specifics).
Only read-only server-side tools are returned (side-effect-free, approval mode set to allow, and side-effect level read); when configuring evaluations, select tools from this list.
The scope is
observability.evals.write; no plaintext is returned for credentials corresponding togatewayKeyId.
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/evals/mcp/tools" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"gatewayId": "<GATEWAY_ID>",
"gatewayKeyId": "<GATEWAY_KEY_ID>"
}'Response example: 200: The response is a tool list JSON (generalized schema any; refer to the actual response for specific fields).
Query
GET /v1/observability/traces
Paginated query of the trace list within a project: supports time windows, exact name matching, fuzzy search by ID/name, and tag and user filters.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 25 | Maximum items per page, default 25. |
offset | query | integer | No | Default 0 | Pagination offset, default 0. |
from | query | string | No | Default "" | Start of the time range (ISO 8601 time string). |
to | query | string | No | Default "" | End of the time range. |
name | query | string | No | Default "" | Exact filter by trace name. |
search | query | string | No | Default "" | Fuzzy match on trace ID or name. |
tag | query | string | No | Default "" | Filter by tag. |
userId | query | string | No | Default "" | Exact filter by owning user ID. |
Output: Returns the trace list (generalized schema any). Elements are Langfuse-compatible trace objects: id, timestamp, name, userId, sessionId, environment, release, tags, etc. (consistent with the body fields of the ingestion trace-create).
For deep pagination, it is recommended to use
from/toto narrow the time window rather than continuously increasingoffset.
Call example:
curl "https://<your-endpoint>/v1/observability/traces?limit=2&from=2026-09-14T00:00:00Z&to=2026-09-15T00:00:00Z&userId=user_42" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a trace list JSON (generalized schema; element fields are consistent with the Langfuse trace model):
{
"data": [
{
"id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"timestamp": "2026-09-14T02:30:00.000Z",
"name": "support-agent.run",
"userId": "user_42",
"sessionId": "session-20260914-001",
"environment": "production",
"release": "2026.09.14",
"tags": ["agent", "support"]
}
]
}GET /v1/observability/traces/{traceId}
Read a single trace, its flat observation list, and persisted trajectory to inspect an Agent, RAG, or LLM execution.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
traceId | path | string | Yes | — | Trace ID, up to 128 characters; consistent with body.id at ingestion time. |
Output: top-level { trace, observations, trajectory } (generic schema any). trace is the root entity. observations[] is a flat list with id, traceId, parentObservationId, type, name, startTime, endTime, model, level, and usage; the Console builds the tree from parent references. trajectory contains the persisted ATIF and is null when absent, reporting is incomplete, or asynchronous trajectory processing is not ready.
If 404 when querying immediately after ingestion, poll briefly and wait for the asynchronous worker to finish persisting.
Call example:
curl "https://<your-endpoint>/v1/observability/traces/5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example (trajectory not ready yet):
{
"trace": {
"id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"name": "support-agent.run",
"timestamp": "2026-09-14T02:30:00.000Z"
},
"observations": [
{
"id": "0123456789abcdef",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"parentObservationId": null,
"type": "GENERATION",
"name": "llm.answer",
"startTime": "2026-09-14T02:30:01.000Z",
"endTime": "2026-09-14T02:30:03.800Z",
"model": "gpt-4o-mini",
"level": "DEFAULT",
"usage": { "input": 412, "output": 96, "total": 508 },
"input": {
"messages": [
{
"role": "user",
"content": "订单何时发货?"
}
]
},
"output": {
"role": "assistant",
"content": "请提供订单号。"
}
}
],
"trajectory": null
}GET /v1/observability/sessions
Paginated query of the session list: sessions are aggregated from the trace sessionId and used for observing by conversation turn.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 25 | Maximum items per page, default 25. |
offset | query | integer | No | Default 0 | Pagination offset. |
from | query | string | No | Default "" | Start of the session time range. |
to | query | string | No | Default "" | End of the session time range. |
Output: Returns the session list (generalized schema any: each item contains the session ID, time range, and the number of associated traces; refer to the actual response for fields).
Call example:
curl "https://<your-endpoint>/v1/observability/sessions?limit=25&from=2026-09-14T00:00:00Z&to=2026-09-15T00:00:00Z" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a session list JSON (generalized schema; refer to the actual response for fields).
GET /v1/observability/sessions/{sessionId}
Read a single session and its contained trace list.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
sessionId | path | string | Yes | — | Session ID, up to 128 characters; i.e., the trace body.sessionId at ingestion time. |
Output: Returns the session details + associated traces (generalized schema any; refer to the actual response for fields).
Call example:
curl "https://<your-endpoint>/v1/observability/sessions/session-20260914-001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a session details JSON (generalized schema; refer to the actual response for fields).
GET /v1/observability/users
Paginated query of the user list aggregated by trace ownership: supports fuzzy search by user ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 25 | Maximum items per page, default 25. |
offset | query | integer | No | Default 0 | Pagination offset. |
search | query | string | No | Default "" | Fuzzy search by user ID. |
from | query | string | No | Default "" | Start of the trace time window filter. |
to | query | string | No | Default "" | End of the trace time window filter. |
Output: Returns the user aggregation list (generalized schema any: each item contains the user ID and trace aggregation info; refer to the actual response for fields).
Call example:
curl "https://<your-endpoint>/v1/observability/users?limit=25&search=user_4" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a user list JSON (generalized schema; refer to the actual response for fields).
GET /v1/observability/users/{userId}
Read the trace-derived metrics of a single user (call counts, token usage, and other aggregations).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
userId | path | string | Yes | — | User ID, i.e., the trace body.userId. |
Output: Returns the trace-derived metrics for that user (generalized schema any; refer to the actual response for fields).
Call example:
curl "https://<your-endpoint>/v1/observability/users/user_42" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a user aggregate metrics JSON (generalized schema; refer to the actual response for fields).
GET /v1/observability/scores
Paginated query of score records: supports filters by evaluation task, score band, evaluator, source, data type, and normalized numeric comparison.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 25 | Maximum items per page, default 25. |
offset | query | integer | No | Default 0 | Pagination offset. |
from | query | string | No | Default "" | Start of the score time range. |
to | query | string | No | Default "" | End of the score time range. |
evaluationTasks | query | string[] | No | Default [] | Filter by evaluation task name (array, union taken). |
scoreBands | query | string[] | No | Default [] | Filter by normalized score band (e.g., low / medium / high). |
evaluators | query | string[] | No | Default [] | Filter by evaluator name. |
sources | query | string[] | No | Default [] | Filter by score source. |
dataTypes | query | string[] | No | Default [] | Filter by score data type (NUMERIC / CATEGORICAL, etc.). |
valueFilters | query | object[] | No | Default [] | Array of normalized numeric comparisons; multiple conditions are combined with AND. |
valueFilterExpression | query | object | No | Default {} | Bounded boolean expression object evaluated against normalized numeric scores; used in the choose-one context with valueFilters. |
Output: Returns the score list (generalized schema any; element fields are consistent with the body of the ingestion score-create: id, name, value, dataType, traceId / observationId / sessionId).
Call example:
curl "https://<your-endpoint>/v1/observability/scores?limit=25&dataTypes=NUMERIC" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a score list JSON (generalized schema; fields are consistent with the Langfuse score model):
{
"data": [
{
"id": "score-0001",
"name": "user-feedback",
"value": 0.9,
"dataType": "NUMERIC",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
}
]
}GET /v1/observability/score-configs
List the score configurations in effect within the project (score names, types, and value domain definitions).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | Default 100 | Maximum items per page, default 100. |
offset | query | integer | No | Default 0 | Pagination offset. |
Output: Returns the score configuration list (generalized schema any; refer to the actual response for fields).
Call example:
curl "https://<your-endpoint>/v1/observability/score-configs?limit=100" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a score configuration list JSON (generalized schema; refer to the actual response for fields).
POST /v1/observability/metrics
Query aggregate metrics based on trace / observation / score data (Langfuse metrics query semantics), returning aggregate series.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
query | body | object | Yes | — | Langfuse metrics query object: time window (from/to), metrics (metrics[]: measure + aggregation), dimensions (dimensions[]), and filters[]. Refer to the Langfuse metrics query contract for specific fields. |
Output: Returns an aggregated metrics series (generalized schema any; fields are subject to the actual response). Note: this endpoint targets observability-domain aggregation, not a general-purpose infrastructure metrics database.
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/metrics" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": {
"from": "2026-09-07T00:00:00Z",
"to": "2026-09-14T00:00:00Z",
"metrics": [
{ "measure": "cost", "aggregation": "sum" }
],
"dimensions": [
{ "field": "metricsName" }
]
}
}'Response example: The response is an aggregated metrics JSON (generalized schema; fields are subject to the actual response).
GET /v1/observability/logs
Query business output logs generated by Function / dynamic Site executions by W3C trace or execution ID: correlate observability traces with execution outputs.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
query | query | string | Yes | — | Whitelist key:value selector; keys only support traceId / executionId / siteExecutionId (e.g., traceId:5f0c3a9e...). Invalid keys or value formats return a parameter error. |
from | query | integer | No | Default 0 | Query start point (Unix seconds); defaults to one hour ago. |
to | query | integer | No | Default 0 | Query end point (Unix seconds); defaults to now. |
limit | query | integer | No | Default 25 | Maximum number of entries returned; default 25, upper limit 100. |
offset | query | integer | No | Default 0 | Pagination offset, upper limit 1000. |
Output: Returns traceLogList:
| Field | Type | Description |
|---|---|---|
logs | object[] | Array of log entries; fields are listed below |
logs[].timestamp | string | Log time |
logs[].level | string | Log level |
logs[].message | string | Log content; only limited patterns are masked and content is truncated, so sensitive data may remain |
logs[].source | string | Execution source: function / site |
logs[].function_id | string | Function ID (when source is function) |
logs[].site_id | string | Site ID (when source is site) |
logs[].execution_id | string | Execution ID |
logs[].deployment_id | string | Deployment ID |
logs[].trigger | string | Execution trigger method |
logs[].stream | string | Output stream (stdout / stderr) |
logs[].chunk_index | integer | Output chunk index |
logs[].chunk_count | integer | Total number of output chunks |
logs[].trace_id | string | Associated W3C trace ID |
complete | boolean | Whether the log provider has completed this query |
The scope is
traceLogs.read, independent of theobservability.*scope on the Langfuse data plane.Does not accept SQL-like query statements or log provider configuration parameters; the time range and
limit/offsetare truncated when out of bounds.
Call example:
curl "https://<your-endpoint>/v1/observability/logs?query=traceId:5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f&limit=100" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example:
{
"logs": [
{
"timestamp": "2026-09-14T02:30:01.120Z",
"level": "INFO",
"message": "llm.answer start",
"source": "function",
"function_id": "fn-support-agent",
"execution_id": "exec-01J5Z8W9",
"deployment_id": "dep-63a1",
"trigger": "https",
"stream": "stdout",
"chunk_index": 0,
"chunk_count": 2,
"trace_id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
},
{
"timestamp": "2026-09-14T02:30:03.910Z",
"level": "INFO",
"message": "llm.answer done tokens=508",
"source": "function",
"function_id": "fn-support-agent",
"execution_id": "exec-01J5Z8W9",
"deployment_id": "dep-63a1",
"trigger": "https",
"stream": "stdout",
"chunk_index": 1,
"chunk_count": 2,
"trace_id": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f"
}
],
"complete": true
}GET /v1/observability
Reads the current project's observability status: initialization state, ingestion entry point, and capacity state; use it to probe availability before writing.
Input: no path/query/body parameters.
Output: Returns the project ingestion status (generalized schema any: including enablement status and capacity info such as ingestionEndpoints; fields are subject to the actual response).
The probe scope is
observability.status.read(legacy keys are compatible withprojects.read); a failed status probe does not mean the write key is invalid.
Call example:
curl "https://<your-endpoint>/v1/observability" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a project status JSON (generalized schema; fields are subject to the actual response; includes ingestionEndpoints).
Observation List and Score Analysis (2.9.0)
GET /v1/observability/observations
Query Observations across traces; name, level, traceId, and environment use exact matching.
scope:observability.traces.read;Server SDK:Observability.listObservations。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
limit | query | integer | No | 25 | Maximum records per page, 1–100. |
offset | query | integer | No | 0 | Records skipped for pagination (offset), 0–999900; must be a multiple of limit. |
from | query | string | No | "" | Start of the observation time range. |
to | query | string | No | "" | End of the observation time range. |
type | query | string | No | "" | Comma-separated observation types. |
name | query | string | No | "" | Observation name, exact match. |
level | query | string | No | "" | Observation level, exact match. |
traceId | query | string | No | "" | Parent trace ID, exact match. |
environment | query | string | No | "" | Environment, exact match. |
output: 200, model observabilityObservationList.
| Field | Type | Description |
|---|---|---|
total | integer | Total number of observations under the current filter conditions. |
observations | object[] | Observations on this page; model observabilityObservation. |
Call example:
curl --get "https://<your-endpoint>/v1/observability/observations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/observability/scores/{scoreId}/analysis
Reads the root cause analysis result for the specified score.
scope:observability.scores.read;Server SDK:Observability.getScoreAnalysis。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
scoreId | path | string | Yes | — | Score ID. |
Output: 200, a JSON object (schema any).
Call example:
curl --get "https://<your-endpoint>/v1/observability/scores/<SCORE_ID>/analysis" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"GET /v1/observability/scores/{scoreId}/quality-details
Reads the parsing or chunk quality details for the specified score.
scope:observability.scores.read;Server SDK:Observability.getScoreQualityDetails。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
scoreId | path | string | Yes | — | Score ID. |
kind | query | string | Yes | parsing / chunking | Parsing or chunk detail type. |
limit | query | integer | No | 25 | Maximum number of records to return. |
offset | query | integer | No | 0 | Number of records to skip. |
Output: 200, a JSON object (schema any).
Call example:
curl --get "https://<your-endpoint>/v1/observability/scores/<SCORE_ID>/quality-details" \
--data-urlencode "kind=parsing" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/observability/scores/analysis/summaries
Reads score analysis summaries in batch.
scope:observability.scores.read;Server SDK:Observability.listScoreAnalysisSummaries。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
scoreIds | body | string[] | Yes | — | 1–100 score IDs; duplicate IDs are automatically deduplicated. |
Output: 200, a JSON object (schema any).
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/scores/analysis/summaries" \
-H "Content-Type: application/json" \
-d '{"scoreIds":["<SCORE_ID>"]}' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/observability/scores/analysis/trigger
Schedules score analysis tasks in batch.
scope:observability.scores.read;Server SDK:Observability.triggerScoreAnalyses。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
scoreIds | body | string[] | Yes | — | 1–100 score IDs; duplicate IDs are automatically deduplicated. |
reanalysisId | body | string | No | — | UUID for re-analysis according to current project settings; request retries reuse the same UUID, and in-progress tasks are reused. |
Output: 200, a JSON object (schema any).
Call example:
curl -X POST "https://<your-endpoint>/v1/observability/scores/analysis/trigger" \
-H "Content-Type: application/json" \
-d '{"scoreIds":["<SCORE_ID>"]}' \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Knowledge Index Quality Evaluation and Prompt Resolution (2.10.0)
POST /v1/observability/evals/index-preview
Preview the evaluation scope of the knowledge index quality evaluation: returns the estimated number of evaluation records for each category (GraphRAG entities / relations / community reports, RAPTOR summary nodes, Wiki pages) based on the selected index capabilities, to assess evaluation cost and scale before submission.
scope:observability.evals.read;Server SDK:Observability.previewIndexEvaluation。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | Yes | — | Knowledge base ID. |
versionId | body | string | No | null | Explicit knowledge base version; empty means the existing (legacy) scope. |
capabilities | body | object | Yes | — | Selected index capabilities (GraphRAG / RAPTOR / LLM Wiki). |
Output: 200, a JSON object (schema any) — estimated evaluation record counts grouped by capability.
POST /v1/observability/evals/index
Creates a knowledge index quality evaluation task (GraphRAG / RAPTOR / LLM Wiki evaluated independently, with independent model review; see the "Evaluation and Scoring" section of the product manual).
scope:observability.evals.write;Server SDK:Observability.createIndexEvaluation。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | Yes | — | Knowledge base ID. |
versionId | body | string | No | null | Explicit knowledge base version; empty means the existing (legacy) scope. |
scoreName | body | string | Yes | — | Score display name (≤128 characters). |
idempotencyKey | body | string | Yes | — | Idempotency task key; retries reuse the same key. |
members | body | object | Yes | — | Capability-independent evaluation member configuration (including sampling). |
locale | body | string | No | en-us | Evaluation language: en-us / zh-cn / ja-jp. |
Output: 200, a JSON object (schema any) — the evaluation task.
GET /v1/observability/prompts/resolve
Resolves the evaluation Prompt by name + label (default production) or exact version number; label and version are mutually exclusive. Allows the evaluation execution pipeline to fetch the Prompt deterministically.
scope:observability.prompts.read;Server SDK:Observability.resolvePrompt。
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | query | string | Yes | — | Prompt name. |
label | query | string | No | production | Prompt label; mutually exclusive with version. |
version | query | integer | No | — | Exact version number; mutually exclusive with label. |
Output: 200, a JSON object (schema any) — the matched Prompt version.
Call example:
curl --get "https://<your-endpoint>/v1/observability/prompts/resolve" \
--data-urlencode "name=rag-faithfulness" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Message and tool association formats
This section complements the endpoint field tables with message shapes, parent-child references, tool call IDs, usage, and error handling for reporting and verifying Agent trajectories (ATIF v1.8) through POST /v1/observability/ingestion and GET /v1/observability/traces/{traceId}.
1. Event identity, entity identity, and parent references
| Field | Meaning | Format and validation boundary | Retry and update behavior |
|---|---|---|---|
batch[].id | Event idempotency ID | A unique, non-empty string; UUID is recommended. | Retry the same event with its original batch[].id. Generate a new batch[].id for a new update event, such as generation-update. Do not regenerate IDs on retry. |
batch[].body.id | Entity ID | Prefer non-zero, 32-character lowercase hex Trace IDs and non-zero, 16-character lowercase hex Observation IDs for W3C traceparent compatibility. | Keep body.id when creating and updating the same entity. This hexadecimal format is recommended for cross-service correlation. Events ingestion does not enforce hexadecimal IDs; the /observability/logs traceId selector requires W3C hexadecimal format. |
batch[].body.traceId | Root Trace reference | Required for an Observation or a Score bound to a Trace; references the root trace-create body.id. | All Observations in a trace reference the same root traceId. |
batch[].body.parentObservationId | Parent reference | Optional. A child Observation references its direct parent's body.id. | Omit the field or use null for a top-level Observation. Preserve the actual nesting of calls. |
Observation trees and trajectories: ordinary
SPANnodes such as HTTP requests or context preparation,RETRIEVER, andEMBEDDINGnodes support the tree and timeline. They do not necessarily produce conversation steps. The platform derives and persistsATIF v1.8from valid conversation and tool evidence.
2. Model messages and context across calls
In the body of generation-create / generation-update, report input and output as follows:
Input (
body.input): prefer{ "messages": [...] }, or a direct array of message objects, each withroleandcontent. Preserve the actualsystem,user,assistant, andtoolroles and turn order. To record available tool definitions, include thetoolsfunction-definition array alongside messages inbody.input.Output (
body.output): report only that call's realassistantreply andtool_calls, such as{ "role": "assistant", "content": "...", "tool_calls": [...] }. Do not copy the Prompt or earlier messages intooutputas model-generated content.Multimodal content: message
contentand tool results can contain strings or structuredtext,image, andaudioparts. Preserve fields such astype,media_type,path, andduration_sec.Overlapping context: when a Trace contains multiple model calls, each
GENERATIONrecords the complete context actually passed to that call. Set the root Trace'sbody.inputto the current user input, such as{ "content": "<用户问题>" }or its correspondingusermessage. The platform uses the root Traceinputto identify the current turn, exclude older turns from merged session history, and extract new messages using prefix overlap. Do not remove real turns because their text is identical.OpenCode and ordinary external Agents: OpenCode uses additional rules for a unique, acyclic authoritative Context Snapshot, identity verification, and completeness. General external Agents use ChatML messages. Do not forge a
sourcelabel or internal signature to select a special parsing path.
3. Tool call IDs across three locations
When a model requests a tool and consumes its result in a later call, keep the following IDs consistent:
| Location | Observation and field | Structure and compatible aliases | ATIF v1.8 mapping |
|---|---|---|---|
| 1. Model tool request | The preceding GENERATION body.output.tool_calls[] | Each entry includes a non-empty call ID (id or tool_call_id) and function name (function.name or name / function_name). Put arguments in function.arguments or arguments. | Normalizes to an ATIF Agent step's tool_calls[]: { "tool_call_id": "<id>", "function_name": "<name>", "arguments": {...} }. A missing ID or function name causes a projection error. |
| 2. Tool execution | The TOOL Observation's body.metadata and body.output | Set metadata.toolCallId to the same ID; compatible aliases include tool_call_id, callId, call_id, or OTLP attributes gen_ai.tool.call_id / gen_ai.tool.call.id. Record the result in body.output. | Matches the preceding step by call ID and attaches observation.results[]: { "source_call_id": "<id>", "content": ... }. |
| 3. Later model input | A subsequent GENERATION body.input.messages[] | Include a "role": "tool" message with the same "tool_call_id": "<id>" and result "content". | Preserves the context consumed by the model and its history overlap. ATIF directly associates results using the tool Observation's call ID and output. Later tool input alone does not replace a separate tool execution record. |
Association example:
{
"firstGenerationOutput": {
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "call_9f8e7d6c5b4a",
"type": "function",
"function": {
"name": "get_order_status",
"arguments": { "orderId": "ORD-20261022-889" }
}
}
]
},
"toolObservationBody": {
"id": "fedcba9876543210",
"traceId": "5f0c3a9e2b7d4c1e8a6f0d3b2c1e4a7f",
"parentObservationId": "0123456789abcdef",
"name": "get_order_status",
"metadata": {
"toolCallId": "call_9f8e7d6c5b4a"
},
"output": { "orderId": "ORD-20261022-889", "status": "SHIPPED" }
},
"secondGenerationInputMessage": {
"role": "tool",
"tool_call_id": "call_9f8e7d6c5b4a",
"content": "{\"orderId\":\"ORD-20261022-889\",\"status\":\"SHIPPED\"}"
}
}4. Usage, cost, and timestamps
Per-call usage: each model call reports
usageon its ownGENERATION, for example{ "input": 120, "output": 48, "total": 168, "unit": "TOKENS" }. Optional fields includeusageDetailswith disjointcached/reasoningcomponents andcostDetails.Avoid double counting: do not write a sum of child
GENERATIONTokens as another model call on a parentAGENT. Canonical Generation usage excludes parent Agent aggregates and evaluator usage. Other consumers should also avoid parent-child double counting. Missing, duplicate, or unassigned Generations limit the relevant rule evaluations.Unknown values stay absent: when a model does not return Token usage, cache details, or cost, leave those fields absent. Do not invent
0as evidence of zero consumption.Timestamps and ordering: outer
timestamp, Tracetimestamp, and ObservationstartTime,completionStartTime, andendTimeuse ISO 8601 strings with timezones, such as2026-09-14T02:30:01.000Z. End time should be at or after start time.
5. Ingestion, retries, and readback
| Endpoint or stage | Status or response | Meaning | Client behavior |
|---|---|---|---|
POST /v1/observability/ingestion | HTTP 200, errors: [], and successes[] covering all original event IDs | All 1–100 events passed validation and entered the asynchronous queue. | Acceptance alone does not prove persistence or ATIF readiness. |
POST /v1/observability/ingestion | HTTP 207 Multi-Status | Some events were accepted (successes[]) and others rejected (errors[]). | Inspect errors[], investigate rejected entries, and do not report complete acceptance. |
POST /v1/observability/otel/v1/traces | HTTP 200 with { successes, errors } | Accepts OTLP/HTTP JSON (resourceSpans → scopeSpans → spans) or protobuf, optionally gzip; gRPC is unsupported. Returns the platform's converted result. | Inspect errors[] even on HTTP 200; do not assume the standard OTLP partialSuccess response. |
| Events / OTLP ingestion | Network timeout, 429, 500 / 502 / 503 / 504 | Temporary rate limiting or recoverable server errors. | Use bounded exponential backoff. Events retries reuse the original outer batch[].id. |
| Events / OTLP ingestion | 400 / 401 / 403 / 413 | Invalid format, identity or permission, or an exceeded request-body limit. Apply each endpoint's limits separately: Events accepts 1–100 events per batch; OTLP limits both raw and decompressed bodies to 4.5 MiB. | Correct the request or provide a valid project API Key before retrying. |
GET /v1/observability/traces/{traceId} | HTTP 404 or missing Observations | Asynchronous processing may still be in progress, or ingestion may not have reached the selected project. | Poll within a fixed bound using a separate read Key with observability.traces.read. If unconfirmed at the limit, report acceptance without confirmed persistence. |
GET /v1/observability/traces/{traceId} | HTTP 200 with top-level { trace, observations, trajectory } | Returns the stored trace, observations[], and current persisted trajectory. It is null when absent, reporting is incomplete, or asynchronous trajectory processing is not ready. Check non-null objects for version and steps. | Inspect trace, observations, and trajectory individually. Readback confirms only the current returned data; ATIF readiness and the selected evaluator's result require separate verification. |
Errors and boundaries
Partial ingestion failure is expressed with
207: no full rollback; check error entries in the response event by event, then re-submit.Log query keys outside the whitelist (anything other than
traceId/executionId/siteExecutionId): parameter error; the time range andlimit/offsetare truncated when exceeding upper bounds.The event model is Langfuse-compatible: trace/observation/score field names align with the Langfuse SDK, and the OTel entry point maps via standard semantic conventions (the gen_ai family).
Query endpoints use
limit/offsetfor pagination (not cursors); narrow the time window for deep pagination.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
Observability.createIngestion / createOtelTraces | POST /observability/ingestion、POST /observability/otel/v1/traces |
Observability.listTraces / getTrace / listSessions / getSession / listUsers / getUser | trace / session / user queries |
Observability.listScores / listScoreConfigs / queryMetrics | GET .../scores、.../score-configs、POST .../metrics |
Observability.listLogs | GET /observability/logs |
Observability.getStatus | GET /observability |
Observability.discoverEvalMcpTools | POST /observability/evals/mcp/tools(2.8.0) |
Observability.listObservations | GET /observability/observations(2.9.0) |
Observability.getScoreAnalysis / getScoreQualityDetails / listScoreAnalysisSummaries / triggerScoreAnalyses | .../scores/{scoreId}/analysis and other analytics surfaces (2.9.0) |
Observability.previewIndexEvaluation / createIndexEvaluation | POST /observability/evals/index-preview、POST /observability/evals/index(2.10.0) |
Observability.resolvePrompt | GET /observability/prompts/resolve(2.10.0) |
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| HTTP | Scope | SDK |
|---|---|---|
POST /observability/reports/agents | observability.metrics.read | observability.getReportAgents |
POST /observability/reports/overview | observability.metrics.read | observability.getReportOverview |
POST /observability/reports/quality | observability.metrics.read | observability.getReportQuality |
GET /observability/trace-analyses | observability.scores.read | observability.listTraceAnalyses |
POST /observability/trace-analyses | observability.scores.read | observability.createTraceAnalysis |
GET /observability/trace-analyses/{analysisId} | observability.scores.read | observability.getTraceAnalysis |
POST /observability/traces/analysis | observability.scores.read | observability.analyzeTraceCollection |
GET /observability/traces/{traceId} | observability.traces.read | observability.getTrace |
POST /observability/reports/agents
Read the observability Agents report. Requires observability.metrics.read, observability.traces.read, observability.users.read and observability.sessions.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
range | body | no | string | enum=24h, 7d, 30d; default="7d" | Report time window preset. Ignored when from and to are both set. |
from | body | no | string | default="" | Custom window start (ISO-8601). Must be paired with to; max span 30 days. |
to | body | no | string | default="" | Custom window end (ISO-8601). Must be paired with from; max span 30 days. |
Success response: HTTP 200 — any.
POST /observability/reports/overview
Read the observability Overview report
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
range | body | no | string | enum=24h, 7d, 30d; default="7d" | Report time window preset. Ignored when from and to are both set. |
from | body | no | string | default="" | Custom window start (ISO-8601). Must be paired with to; max span 30 days. |
to | body | no | string | default="" | Custom window end (ISO-8601). Must be paired with from; max span 30 days. |
Success response: HTTP 200 — any.
POST /observability/reports/quality
Read the observability Quality report. Requires observability.metrics.read, observability.traces.read and observability.scores.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
range | body | no | string | enum=24h, 7d, 30d; default="7d" | Report time window preset. Ignored when from and to are both set. |
from | body | no | string | default="" | Custom window start (ISO-8601). Must be paired with to; max span 30 days. |
to | body | no | string | default="" | Custom window end (ISO-8601). Must be paired with from; max span 30 days. |
Success response: HTTP 200 — any.
GET /observability/trace-analyses
List model-based collection analysis history with bounded cursor pagination. Requires observability.scores.read and observability.traces.read; dataset analyses also require observability.datasets.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
limit | query | no | integer | format=int32; default=20 | Maximum history entries, between 1 and 20. |
cursor | query | no | string | default="" | Opaque nextCursor from the preceding page. |
datasetId | query | no | string | default="" | Dataset whose analysis history is listed. |
Success response: HTTP 200 — any.
POST /observability/trace-analyses
Create a model-based root cause analysis for 2 to 100 Traces from the same application. Requires observability.scores.read and observability.traces.read; dataset analyses also require observability.datasets.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
traceIds | body | no | array[string] | default=[] | Trace IDs. Between 2 and 100 IDs; duplicates are ignored. Ignored when datasetId is supplied. |
requestId | body | yes | string | — | Idempotent UUID. Reuse for retries; use a new UUID to analyze again. |
name | body | no | string | — | Collection name, up to 120 characters. |
datasetId | body | no | string | default="" | Dataset owning the analysis. When supplied, source Traces are resolved from its active items. |
datasetRunId | body | no | string | default="" | Dataset run whose Traces should be analyzed. Requires datasetId. |
Success response: HTTP 202 — any.
GET /observability/trace-analyses/{analysisId}
Get a model-based collection analysis and its saved result without scheduling new work. Requires observability.scores.read and observability.traces.read; dataset analyses also require observability.datasets.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
analysisId | path | yes | string | — | Collection analysis ID returned by create or list. |
Success response: HTTP 200 — any.
POST /observability/traces/analysis
Aggregate existing analysis for 2 to 100 Traces from the same application without scheduling new work. Requires observability.scores.read and observability.traces.read; dataset analyses also require observability.datasets.read.
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
traceIds | body | no | array[string] | default=[] | Trace IDs to analyze. Between 2 and 100 IDs; duplicates are ignored. Ignored when datasetId is supplied. |
datasetId | body | no | string | default="" | Dataset owning the analysis. When supplied, source Traces are resolved from its active items. |
datasetRunId | body | no | string | default="" | Dataset run whose Traces should be analyzed. Requires datasetId. |
Success response: HTTP 200 — any.
GET /observability/traces/{traceId}
Get an observability trace
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
traceId | path | yes | string | — | Trace ID. Max length: 128 chars. |
compact | query | no | boolean | default=false | Return a bounded trace view with explicit omission coverage. |
Success response: HTTP 200 — any.
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.