Trace Export

Export durable tool-call and voice-isolation infra trace spans as OTLP/JSON for external observability collectors.

The trace export endpoint lets you pull your workspace's durable trace spans as OpenTelemetry Protocol (OTLP/HTTP JSON) spans: gen_ai.* tool-call spans and the per-call voice-isolation voice.* infra spans (media server allocation, media attach, and teardown). It is a read-only, paginated pull API for external observability collectors and partner monitoring stacks.

Dark launch. This endpoint is gated behind a feature flag and returns 404 when not enabled for your workspace. Contact your account team to request access.

Endpoint

Export gen_ai.* + voice.* traces as OTLP/JSON

post

Export the workspace's durable trace spans over a time window as OpenTelemetry Protocol (OTLP/HTTP JSON) spans: gen_ai.* tool-call spans and the per-call voice-isolation voice.* infra spans (allocate / media-attach / reap). Read-only; admin/owner role required; dark behind OTEL_TRACE_EXPORT_ENABLED (404 when off). Paginated PULL API — extract .resourceSpans before forwarding to an OTLP collector. Attributes are an allowlist of tool-call + infra metadata; the raw tool-result error text is NOT exported (PHI-safe by construction).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

start_timestring · date-timeRequired

Inclusive lower bound on span effective_at (ISO-8601).

end_timestring · date-timeRequired

Exclusive upper bound on span effective_at (ISO-8601).

limitinteger · max: 1000Optional

Max spans per page (1-1000).

Default: 500

continuation_tokenanyOptional

Opaque page cursor — round-trip the value from the previous response.

Responses

200

Successful Response

application/json

Paginated PULL response — NOT a bare OTLP ExportTraceServiceRequest.

resourceSpans is OTLP/JSON-conformant; to forward to an OTLP collector, extract .resourceSpans and re-wrap as {"resourceSpans": [...]} (a strict protojson push receiver rejects the has_more/continuation_token siblings). Round-trip continuation_token to page.

has_morebooleanRequired

continuation_tokenanyOptional

422

Validation Error

application/json

post/v1/{workspace_id}/traces:export

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/traces:export HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "start_time": "2026-07-10T21:37:33.969Z",
  "end_time": "2026-07-10T21:37:33.969Z",
  "limit": 500,
  "continuation_token": null
}

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "text",
            "value": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "scope": {
            "name": "text",
            "version": "text"
          },
          "spans": [
            {
              "traceId": "text",
              "spanId": "text",
              "name": "text",
              "kind": 1,
              "startTimeUnixNano": "text",
              "endTimeUnixNano": "text",
              "attributes": [
                {
                  "key": "text",
                  "value": {
                    "ANY_ADDITIONAL_PROPERTY": "anything"
                  }
                }
              ],
              "status": {
                "code": 1
              }
            }
          ]
        }
      ]
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Trace spans carry tool-call metadata, so this endpoint requires admin or owner credentials.

Example Request

{
  "start_time": "2026-07-01T00:00:00Z",
  "end_time": "2026-07-02T00:00:00Z",
  "limit": 100
}

Response Body

The response is a paginated pull envelope: a resourceSpans array of OTLP/JSON ResourceSpans (empty when no spans match), a has_more boolean indicating whether additional pages are available, and an opaque continuation_token cursor (null when no more pages). See the endpoint schema above for the full response shape.

Example Response

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "amigo-agent-engine" } },
          { "key": "amigo.workspace.id", "value": { "stringValue": "abc123-..." } }
        ]
      },
      "scopeSpans": [
        {
          "scope": { "name": "amigo.world.trace", "version": "1" },
          "spans": [
            {
              "traceId": "00000000000000000123456789abcdef",
              "spanId": "0123456789abcdef",
              "name": "execute_tool get_schedule",
              "kind": 3,
              "startTimeUnixNano": "1719792000000000000",
              "endTimeUnixNano": "1719792000500000000",
              "attributes": [
                { "key": "gen_ai.operation.name", "value": { "stringValue": "execute_tool" } },
                { "key": "gen_ai.tool.name", "value": { "stringValue": "get_schedule" } },
                { "key": "latency_ms", "value": { "intValue": "500" } },
                { "key": "success", "value": { "boolValue": true } }
              ],
              "status": { "code": 1 }
            }
          ]
        }
      ]
    }
  ],
  "has_more": false,
  "continuation_token": null
}

OTLP/JSON Encoding

The response follows OTLP/HTTP JSON encoding conventions:

• Integer values (timestamps, intValue) are encoded as decimal strings.
• Trace IDs are 32 lowercase hex characters (16 bytes).
• Span IDs are 16 lowercase hex characters (8 bytes).
• AnyValue uses the typed oneof encoding - exactly one of stringValue, intValue, boolValue, or doubleValue is set per value.
• Span kind is 3 (CLIENT) - tool calls are outbound operations.
• Status code: 1 = OK, 2 = ERROR.

Exported Attributes

The endpoint uses a fail-closed allowlist. Only these attributes are exported:

Attribute Key	Type	Description
gen_ai.operation.name	string	The operation type (e.g., execute_tool).
gen_ai.tool.name	string	The tool that was called.
gen_ai.tool.integration	string	The integration the tool belongs to.
gen_ai.tool.endpoint	string	The endpoint within the integration.
gen_ai.tool.protocol	string	The protocol used for the tool call.
latency_ms	integer	Tool call duration in milliseconds.
success	boolean	Whether the tool call succeeded.
call_id	string	Unique identifier for the tool call.
voice.actor.gameserver	string	Identifier of the isolated media server allocated for the call.
voice.actor.node	string	The node hosting the allocated media server.
voice.actor.alloc_latency_ms	number	Time taken to allocate the media server, in milliseconds.
voice.media.leg	string	Which media leg attached to the media server (caller, operator, or agent).
voice.actor.reap_reason	string	Why the media server was released at call end.
voice.actor.lifetime_s	number	How long the media server was held for the call, in seconds.

The voice.* attributes appear on the per-call voice-isolation infra spans, which are exported alongside the gen_ai.* tool-call spans and join to the same call through call_id. All voice-isolation attributes are operational metadata only - they never carry conversation content.

Raw error text and any non-allowlisted fields are excluded. The success field and status.code convey failure without exposing error messages.

Resource Metadata

All spans in a response are grouped under a single resource with:

• service.name: amigo-agent-engine
• amigo.workspace.id: the workspace UUID

Spans are scoped under the amigo.world.trace instrumentation scope (version 1).

Forwarding to an OTLP Collector

The response is a paginated pull envelope, not a bare OTLP ExportTraceServiceRequest. To forward spans to an OTLP collector:

1. Extract the resourceSpans array from the response.
2. Wrap it as {"resourceSpans": [...]} to form a valid OTLP push payload.
3. POST the payload to your collector's OTLP/HTTP endpoint.

The has_more and continuation_token fields are not part of the OTLP spec and should be stripped before forwarding.

Pagination

Use cursor-based pagination to retrieve all spans in a time window:

1. Send the initial request without continuation_token.
2. If has_more is true, send another request with the returned continuation_token.
3. Repeat until has_more is false.

Errors

A few endpoint-specific conditions are worth calling out beyond the schema above:

• 404 - The feature flag is not enabled for the workspace (see the dark-launch note above).
• 403 - The API key role is not admin or owner, or the workspace ID does not match the key.
• 422 - Invalid request body, such as end_time before start_time or an invalid continuation_token.