OTEL Worklogs API

Exports AI Employee workflow-execution data as OpenTelemetry (OTLP) traces and logs. The response is standard OTLP TracesData and LogsData serialized to JSON, so it can be ingested by any OTLP-compatible observability backend -- Datadog, Grafana Tempo, Arize, New Relic, Honeycomb, Jaeger, and others.

• Fetch a single workflow run by ID, or query many runs for one AI Employee over a time range.
• Returns OTLP traces, plus correlated logs for callers with debug access.
• Cursor-based pagination for time-range queries.
• Permission-based filtering: debug-access callers receive full spans and logs; standard viewers receive action and step names, timing, and status only.
• Exports terminal workflow runs (COMPLETED, FAILED). Within an exported run, individual action spans may carry a paused status when an action awaited human input.
• Pull-based -- for fetching data after a run reaches a terminal state. It does not stream in real time.

Endpoint

Headers

Request

The endpoint supports two query modes. If workflow_run_id is present, the request is treated as a single-run lookup. Otherwise it is treated as a time-range query, and persona_id, start_time, and end_time are all required.

Query Mode: Single Run

curl -H "Authorization: Bearer <access_token>" \
  "https://your-instance.ema.co/api/v1/observability/worklogs?workflow_run_id=<RUN_ID>"

Query Mode: Time Range

curl -H "Authorization: Bearer <access_token>" \
  "https://your-instance.ema.co/api/v1/observability/worklogs?persona_id=<PERSONA_ID>&start_time=2026-03-10T00:00:00Z&end_time=2026-03-11T00:00:00Z&limit=100"

Query Constraints

• The time-range window must not exceed 7 days per request, and start_time must be before end_time. For longer ranges, issue multiple requests with consecutive windows.
• limit must be between 1 and 500 (default 100). Use page_token to iterate larger result sets.
• Only runs in a terminal state (COMPLETED, FAILED) can be exported. A single-run request for a run that is not yet terminal returns 409 Conflict.

Response

A JSON object. traces is always present; logs is present only for callers with debug access and only when log records exist; next_page_token is present only when more pages remain.

Example Response

{
  "traces": {
    "resourceSpans": [
      {
        "resource": {
          "attributes": [
            { "key": "ema.tenant.id", "value": { "stringValue": "abc12345-0000-0000-0000-000000000000" } },
            { "key": "ema.persona.id", "value": { "stringValue": "2f6c12a8-7d2b-4f1a-9c0e-1234567890ab" } }
          ]
        },
        "scopeSpans": [
          {
            "scope": { "name": "ema.otel.export", "version": "1.0.0" },
            "spans": [
              {
                "name": "Action: Search Knowledge Base",
                "kind": "SPAN_KIND_INTERNAL",
                "status": { "code": "STATUS_CODE_OK" },
                "attributes": [
                  { "key": "ema.action.title", "value": { "stringValue": "Search Knowledge Base" } },
                  { "key": "ema.action.status", "value": { "stringValue": "ACTION_RUN_STATUS_SUCCESS" } },
                  { "key": "ema.action.llm_call_count", "value": { "intValue": "1" } }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

An action that paused for human input during the run is represented by an action span carrying a paused span event, with span status UNSET (see Span Status Mapping). Trace IDs are deterministic for a given run, so re-exporting the same workflow_run_id returns the same trace.

Pagination

For time-range queries returning more results than the page limit, use cursor-based pagination. When more results remain, the response includes a next_page_token and a Link header with rel="next". Pass the token back as page_token and repeat until it is no longer returned.

# First page
curl -H "Authorization: Bearer <access_token>" \
  "https://your-instance.ema.co/api/v1/observability/worklogs?persona_id=<PERSONA_ID>&start_time=2026-03-01T00:00:00Z&end_time=2026-03-08T00:00:00Z&limit=100"

# Response includes: "next_page_token": "<LAST_RUN_ID>"

# Next page
curl -H "Authorization: Bearer <access_token>" \
  "https://your-instance.ema.co/api/v1/observability/worklogs?persona_id=<PERSONA_ID>&start_time=2026-03-01T00:00:00Z&end_time=2026-03-08T00:00:00Z&limit=100&page_token=<LAST_RUN_ID>"

Permission Tiers

The data returned depends on the permission tier of the authenticated caller:

• To receive useful observability data, use an API token with debug access. A standard-viewer token returns only structural information (action and step names, timing, and run status) without LLM metrics or logs.
• Contact your Ema administrator to configure the appropriate access for your integration account.

Data Exclusions

• LLM costs (per-call and aggregate) are not included in the export.
• Prompt content (system prompts, user prompts, model responses) is not included.
• The export does include metrics such as token counts, latency, and model names -- but not the actual text sent to or received from models.

Trace & Log Attributes

Root Span Attributes

Action Span Attributes

LLM Call Span Attributes

LLM call spans follow the OpenTelemetry GenAI semantic conventions where applicable:

Log Record Attributes

Included in logs for debug-access callers only. Each record also carries standard OTLP traceId, spanId, severity, and body fields linking it to its parent span.

Span Status Mapping

Error Responses

Related

• Debug Worklogs API -- gRPC-Web debug log access, including the underlying ShowWorkLog data model.
• Workflow Overview -- workflow execution concepts.
• EmaFusion™ -- model routing referenced by ema.llm.fusion_used.