> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/safety/trace-export.md). # Trace Export The trace export endpoint lets you pull a workspace's durable `gen_ai.*` tool-call spans and supported `voice.*` operational spans as OpenTelemetry Protocol (OTLP/HTTP JSON). It is a read-only, paginated pull API for external observability collectors and partner monitoring stacks. Treat emitter names and voice-runtime attributes as opaque implementation metadata rather than stable topology identifiers. {% hint style="info" %} **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. {% endhint %} ## Endpoint {% openapi src="" path="/v1/{workspace\_id}/traces:export" method="post" %} {% endopenapi %} Trace spans carry tool-call metadata, so this endpoint requires admin or owner credentials. ### Example Request ```json { "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 (abridged) ```json { "resourceSpans": [ { "resource": { "attributes": [ { "key": "amigo.workspace.id", "value": { "stringValue": "abc123-..." } } ] }, "scopeSpans": [ { "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 fixed allowlist. Customer integrations can rely on these tool-call attributes when present: | 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 | Call identifier used to correlate related trace spans. | Supported `voice.*` spans can include additional allowlisted operational attributes. Preserve them when forwarding OTLP, but do not depend on their names or values as a resource inventory, routing signal, or stable service-topology contract. Raw error text and any non-allowlisted fields are excluded. The `success` field and `status.code` convey failure without exposing error messages. ## Resource Metadata Spans include the `amigo.workspace.id` resource attribute plus standard OTLP emitter and instrumentation metadata. Preserve the resource and scope objects when forwarding. Do not branch application behavior on emitter service names or instrumentation-scope identifiers because those values describe the current runtime implementation and can change. ## 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/safety/trace-export.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.