Amigo is now Concurrence
Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Trace Export

Export durable tool-call and supported voice operational spans as OTLP/JSON for external observability collectors.

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.

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; Audit:View permission 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
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
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
post/v1/{workspace_id}/traces:export
POST /v1/{workspace_id}/traces:export HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "start_time": "2026-01-01T00:00:00.000Z",
  "end_time": "2026-01-01T00:00:00.000Z",
  "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

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)

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.

PreviousPrompt Logs
NextPlatform SDK

Last updated

Was this helpful?