Docs
Contents

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

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 + pathPurpose
POST /observability/ingestionBatch ingest trace/observation/score events
POST /observability/otel/v1/tracesOpenTelemetry 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-configsScore list/configuration
GET /observability/observationsObservation list (2.9.0 new: name/type/time/level/traceId/environment filters)
GET .../scores/{scoreId}/analysis · GET .../scores/{scoreId}/quality-detailsScore 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/triggerAnalysis insight summary / batch trigger (≤100 per batch, new in 2.9.0)
POST /observability/evals/index-preview · POST /observability/evals/indexKnowledge 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/resolveResolve 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/toolsDiscover read-only MCP tools for evaluation (2.8.0)
POST /observability/metricsMetrics query
GET /observability/logsFetch execution output logs by trace/execution
GET /observabilityProject ingestion status

Endpoint details

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:

ParameterLocationTypeRequiredDefault/enumDescription
batchbodyobject[]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[].
metadatabodyobjectNo—Batch-wide ingestion metadata (e.g., sdk, sdkVersion), optional.
batch[].idbodystringYes—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[].typebodystringYesSee notes for enumEvent 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[].timestampbodystringYes—Event time, an ISO 8601 string with timezone.
batch[].bodybodyobjectYes—Entity field object; fields depend on the event type, see below.
batch[].body.idbodystringYes—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.namebodystringNo—Entity name (e.g., support-agent.run, llm.answer).
batch[].body.timestampbodystringNo—Entity occurrence time (ISO 8601).
batch[].body.traceIdbodystringRequired 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 / sessionIdbodystringNo—Owning user and session: userId aggregates into the users view, sessionId aggregates into the sessions view.
batch[].body.environment / release / tagsbodystring / string[]No—Deployment context: environment only lowercase letters, digits, -, _ (≤40 characters), release version string, tags array of tags.
batch[].body.input / outputbodyanyNo—Input / output payload (recommend reporting after desensitization).
batch[].body.startTime / endTimebodystringCommonly used for observation—Observation start/end times (ISO 8601).
batch[].body.parentObservationIdbodystringNo—The body.id of the parent Observation (forms the span tree).
batch[].body.level / statusMessagebodystringNoEnum DEBUG, DEFAULT, WARNING, ERRORObservation level and status message.
batch[].body.model / modelParameters / completionStartTimebodystring / objectNo—Generation-specific: model ID, model parameters, and completion start time.
batch[].body.usage / usageDetails / costDetailsbodyobjectNo—Generation-specific: token usage (e.g., {input: 120, output: 48, total: 168, unit: "TOKENS"}) and cost detail.
batch[].body.value / dataTypebodynumber / stringRequired for score—Score-specific: score value and data type (NUMERIC / CATEGORICAL); target specified by one of traceId / observationId / sessionId.
batch[].metadatabodyobjectNo—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.

FieldTypeDescription
successesobject[]Accepted event: id (outer event ID) + status (201)
errorsobject[]Rejected event: id + status (HTTP semantic code) + message (rejection reason)

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

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:

ParameterLocationTypeRequiredDefault/enumDescription
gatewayIdbodystringYes—The gateway ID of the AI Gateway.
gatewayKeyIdbodystringYes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNoDefault 25Maximum items per page, default 25.
offsetqueryintegerNoDefault 0Pagination offset, default 0.
fromquerystringNoDefault ""Start of the time range (ISO 8601 time string).
toquerystringNoDefault ""End of the time range.
namequerystringNoDefault ""Exact filter by trace name.
searchquerystringNoDefault ""Fuzzy match on trace ID or name.
tagquerystringNoDefault ""Filter by tag.
userIdquerystringNoDefault ""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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
traceIdpathstringYes—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.

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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNoDefault 25Maximum items per page, default 25.
offsetqueryintegerNoDefault 0Pagination offset.
fromquerystringNoDefault ""Start of the session time range.
toquerystringNoDefault ""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:

ParameterLocationTypeRequiredDefault/enumDescription
sessionIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNoDefault 25Maximum items per page, default 25.
offsetqueryintegerNoDefault 0Pagination offset.
searchquerystringNoDefault ""Fuzzy search by user ID.
fromquerystringNoDefault ""Start of the trace time window filter.
toquerystringNoDefault ""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:

ParameterLocationTypeRequiredDefault/enumDescription
userIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNoDefault 25Maximum items per page, default 25.
offsetqueryintegerNoDefault 0Pagination offset.
fromquerystringNoDefault ""Start of the score time range.
toquerystringNoDefault ""End of the score time range.
evaluationTasksquerystring[]NoDefault []Filter by evaluation task name (array, union taken).
scoreBandsquerystring[]NoDefault []Filter by normalized score band (e.g., low / medium / high).
evaluatorsquerystring[]NoDefault []Filter by evaluator name.
sourcesquerystring[]NoDefault []Filter by score source.
dataTypesquerystring[]NoDefault []Filter by score data type (NUMERIC / CATEGORICAL, etc.).
valueFiltersqueryobject[]NoDefault []Array of normalized numeric comparisons; multiple conditions are combined with AND.
valueFilterExpressionqueryobjectNoDefault {}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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNoDefault 100Maximum items per page, default 100.
offsetqueryintegerNoDefault 0Pagination 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:

ParameterLocationTypeRequiredDefault/enumDescription
querybodyobjectYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
queryquerystringYes—Whitelist key:value selector; keys only support traceId / executionId / siteExecutionId (e.g., traceId:5f0c3a9e...). Invalid keys or value formats return a parameter error.
fromqueryintegerNoDefault 0Query start point (Unix seconds); defaults to one hour ago.
toqueryintegerNoDefault 0Query end point (Unix seconds); defaults to now.
limitqueryintegerNoDefault 25Maximum number of entries returned; default 25, upper limit 100.
offsetqueryintegerNoDefault 0Pagination offset, upper limit 1000.

Output: Returns traceLogList:

FieldTypeDescription
logsobject[]Array of log entries; fields are listed below
logs[].timestampstringLog time
logs[].levelstringLog level
logs[].messagestringLog content; only limited patterns are masked and content is truncated, so sensitive data may remain
logs[].sourcestringExecution source: function / site
logs[].function_idstringFunction ID (when source is function)
logs[].site_idstringSite ID (when source is site)
logs[].execution_idstringExecution ID
logs[].deployment_idstringDeployment ID
logs[].triggerstringExecution trigger method
logs[].streamstringOutput stream (stdout / stderr)
logs[].chunk_indexintegerOutput chunk index
logs[].chunk_countintegerTotal number of output chunks
logs[].trace_idstringAssociated W3C trace ID
completebooleanWhether the log provider has completed this query

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

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:

ParameterLocationTypeRequiredDefault/enumDescription
limitqueryintegerNo25Maximum records per page, 1–100.
offsetqueryintegerNo0Records skipped for pagination (offset), 0–999900; must be a multiple of limit.
fromquerystringNo""Start of the observation time range.
toquerystringNo""End of the observation time range.
typequerystringNo""Comma-separated observation types.
namequerystringNo""Observation name, exact match.
levelquerystringNo""Observation level, exact match.
traceIdquerystringNo""Parent trace ID, exact match.
environmentquerystringNo""Environment, exact match.

output: 200, model observabilityObservationList.

FieldTypeDescription
totalintegerTotal number of observations under the current filter conditions.
observationsobject[]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:

ParameterLocationTypeRequiredDefault/enumDescription
scoreIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
scoreIdpathstringYes—Score ID.
kindquerystringYesparsing / chunkingParsing or chunk detail type.
limitqueryintegerNo25Maximum number of records to return.
offsetqueryintegerNo0Number 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:

ParameterLocationTypeRequiredDefault/enumDescription
scoreIdsbodystring[]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:

ParameterLocationTypeRequiredDefault/enumDescription
scoreIdsbodystring[]Yes—1–100 score IDs; duplicate IDs are automatically deduplicated.
reanalysisIdbodystringNo—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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdbodystringYes—Knowledge base ID.
versionIdbodystringNonullExplicit knowledge base version; empty means the existing (legacy) scope.
capabilitiesbodyobjectYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
knowledgeBaseIdbodystringYes—Knowledge base ID.
versionIdbodystringNonullExplicit knowledge base version; empty means the existing (legacy) scope.
scoreNamebodystringYes—Score display name (≤128 characters).
idempotencyKeybodystringYes—Idempotency task key; retries reuse the same key.
membersbodyobjectYes—Capability-independent evaluation member configuration (including sampling).
localebodystringNoen-usEvaluation 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:

ParameterLocationTypeRequiredDefault/enumDescription
namequerystringYes—Prompt name.
labelquerystringNoproductionPrompt label; mutually exclusive with version.
versionqueryintegerNo—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

FieldMeaningFormat and validation boundaryRetry and update behavior
batch[].idEvent idempotency IDA 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.idEntity IDPrefer 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.traceIdRoot Trace referenceRequired 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.parentObservationIdParent referenceOptional. 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.

2. Model messages and context across calls

In the body of generation-create / generation-update, report input and output as follows:

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:

LocationObservation and fieldStructure and compatible aliasesATIF v1.8 mapping
1. Model tool requestThe 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 executionThe TOOL Observation's body.metadata and body.outputSet 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 inputA 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

5. Ingestion, retries, and readback

Endpoint or stageStatus or responseMeaningClient behavior
POST /v1/observability/ingestionHTTP 200, errors: [], and successes[] covering all original event IDsAll 1–100 events passed validation and entered the asynchronous queue.Acceptance alone does not prove persistence or ATIF readiness.
POST /v1/observability/ingestionHTTP 207 Multi-StatusSome events were accepted (successes[]) and others rejected (errors[]).Inspect errors[], investigate rejected entries, and do not report complete acceptance.
POST /v1/observability/otel/v1/tracesHTTP 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 ingestionNetwork timeout, 429, 500 / 502 / 503 / 504Temporary rate limiting or recoverable server errors.Use bounded exponential backoff. Events retries reuse the original outer batch[].id.
Events / OTLP ingestion400 / 401 / 403 / 413Invalid 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 ObservationsAsynchronous 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

Correspondence with the Server SDK

service.methodEndpoint
Observability.createIngestion / createOtelTracesPOST /observability/ingestion、POST /observability/otel/v1/traces
Observability.listTraces / getTrace / listSessions / getSession / listUsers / getUsertrace / session / user queries
Observability.listScores / listScoreConfigs / queryMetricsGET .../scores、.../score-configs、POST .../metrics
Observability.listLogsGET /observability/logs
Observability.getStatusGET /observability
Observability.discoverEvalMcpToolsPOST /observability/evals/mcp/tools(2.8.0)
Observability.listObservationsGET /observability/observations(2.9.0)
Observability.getScoreAnalysis / getScoreQualityDetails / listScoreAnalysisSummaries / triggerScoreAnalyses.../scores/{scoreId}/analysis and other analytics surfaces (2.9.0)
Observability.previewIndexEvaluation / createIndexEvaluationPOST /observability/evals/index-preview、POST /observability/evals/index(2.10.0)
Observability.resolvePromptGET /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.

HTTPScopeSDK
POST /observability/reports/agentsobservability.metrics.readobservability.getReportAgents
POST /observability/reports/overviewobservability.metrics.readobservability.getReportOverview
POST /observability/reports/qualityobservability.metrics.readobservability.getReportQuality
GET /observability/trace-analysesobservability.scores.readobservability.listTraceAnalyses
POST /observability/trace-analysesobservability.scores.readobservability.createTraceAnalysis
GET /observability/trace-analyses/{analysisId}observability.scores.readobservability.getTraceAnalysis
POST /observability/traces/analysisobservability.scores.readobservability.analyzeTraceCollection
GET /observability/traces/{traceId}observability.traces.readobservability.getTrace

POST /observability/reports/agents

Read the observability Agents report. Requires observability.metrics.read, observability.traces.read, observability.users.read and observability.sessions.read.

ParameterLocationRequiredTypeConstraints / defaultMeaning
rangebodynostringenum=24h, 7d, 30d; default="7d"Report time window preset. Ignored when from and to are both set.
frombodynostringdefault=""Custom window start (ISO-8601). Must be paired with to; max span 30 days.
tobodynostringdefault=""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

ParameterLocationRequiredTypeConstraints / defaultMeaning
rangebodynostringenum=24h, 7d, 30d; default="7d"Report time window preset. Ignored when from and to are both set.
frombodynostringdefault=""Custom window start (ISO-8601). Must be paired with to; max span 30 days.
tobodynostringdefault=""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.

ParameterLocationRequiredTypeConstraints / defaultMeaning
rangebodynostringenum=24h, 7d, 30d; default="7d"Report time window preset. Ignored when from and to are both set.
frombodynostringdefault=""Custom window start (ISO-8601). Must be paired with to; max span 30 days.
tobodynostringdefault=""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.

ParameterLocationRequiredTypeConstraints / defaultMeaning
limitquerynointegerformat=int32; default=20Maximum history entries, between 1 and 20.
cursorquerynostringdefault=""Opaque nextCursor from the preceding page.
datasetIdquerynostringdefault=""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.

ParameterLocationRequiredTypeConstraints / defaultMeaning
traceIdsbodynoarray[string]default=[]Trace IDs. Between 2 and 100 IDs; duplicates are ignored. Ignored when datasetId is supplied.
requestIdbodyyesstring—Idempotent UUID. Reuse for retries; use a new UUID to analyze again.
namebodynostring—Collection name, up to 120 characters.
datasetIdbodynostringdefault=""Dataset owning the analysis. When supplied, source Traces are resolved from its active items.
datasetRunIdbodynostringdefault=""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.

ParameterLocationRequiredTypeConstraints / defaultMeaning
analysisIdpathyesstring—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.

ParameterLocationRequiredTypeConstraints / defaultMeaning
traceIdsbodynoarray[string]default=[]Trace IDs to analyze. Between 2 and 100 IDs; duplicates are ignored. Ignored when datasetId is supplied.
datasetIdbodynostringdefault=""Dataset owning the analysis. When supplied, source Traces are resolved from its active items.
datasetRunIdbodynostringdefault=""Dataset run whose Traces should be analyzed. Requires datasetId.

Success response: HTTP 200 — any.

GET /observability/traces/{traceId}

Get an observability trace

ParameterLocationRequiredTypeConstraints / defaultMeaning
traceIdpathyesstring—Trace ID. Max length: 128 chars.
compactquerynobooleandefault=falseReturn 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.