Ingest spans
Sends an OTLP export to Egma. Use this endpoint as theOTEL_EXPORTER_OTLP_TRACES_ENDPOINT (or equivalent) in your agent’s OpenTelemetry configuration.
POST /v1/traces
Authentication
Send a Bearer API key in theAuthorization header. Use a key scoped to the project you want telemetry to appear under.
Content types
Send one of the two standard OTLP/HTTP content types:
Gzip compression is supported. Add
Content-Encoding: gzip when sending compressed bodies.
Request limits
- Maximum body size: 20 MiB (matches the OpenTelemetry Collector default)
- Maximum spans per request: 10,000
- Maximum normalized row bytes per request: 64 MiB
Response
Egma returns a standardExportTraceServiceResponse. If any spans were rejected, the partialSuccess field contains a count and a reason. A 200 response with an empty body means all spans were accepted.
Send spans (protobuf)
Send spans (JSON)
Use your Egma instance’s API port for telemetry ingest — port 3100 by default — not the web UI port (3101). These may differ in self-hosted deployments. Check your
EGMA_API_URL environment variable or ask your administrator if you are unsure which port is which.When setting the endpoint URL in environment variables or SDK configuration, encode spaces as
%20, not as literal spaces. Many OpenTelemetry SDKs pass headers verbatim, and a literal space in an Authorization header value is not valid HTTP.Telemetry sent with a project-scoped API key appears in the dashboard under that project. An organization-scoped key groups traces at the organization level. For traces to appear under a specific project, mint a key scoped to that project via
POST /api/keys with project_id set.List traces
Returns a paginated list of trace summaries within a time window, ordered newest first.GET /v1/traces
string
required
Start of the query window as an RFC 3339 timestamp, e.g.
2026-08-02T00:00:00Z. Microsecond precision is supported (six fractional digits); finer precision is rejected.string
required
End of the query window as an RFC 3339 timestamp. The bound is exclusive — a trace that ended exactly at
to is not included. You can paste a trace’s own ended_at value directly as to without losing it.string
Filter to a specific project. Omit to read across your whole organization. If your API key is already scoped to a project, this parameter must either match that project or be omitted.
number
Maximum traces per page. Clamped to the server maximum if higher. Must be a positive integer.
string
Pagination cursor from a previous response’s
next_cursor. Omit to start at the newest trace in the window.array
Array of trace summary objects.
string | null
Cursor for the next page.
null when you have reached the last page.object
The time window as Egma read it, formatted to microsecond precision. Use these values to paginate accurately.
List traces in a time window
Filter by project
Both
from and to are required. There is no default window — a query without a time bound would scan the entire store, and Egma rejects it with a descriptive error asking you to supply both parameters.Trace summary fields
string
The 32-character lowercase hex trace ID.
string
ISO 8601 timestamp of when the root span opened.
string
ISO 8601 timestamp of when the root span closed.
string
Total conversation duration in nanoseconds, as a decimal string. Sent as a string because nanosecond counts exceed the precision of a JSON number.
number
Total number of spans in this trace.
object
{ human, agent } — number of turns attributed to each party.string
"simulation" for runs Egma conducted, "production" for live traffic from your agent.number
Number of tool-call spans in this trace.
number
Number of spans that completed with an error status.
string
The SDK or runtime that emitted this trace.
string
The deployment environment reported by the emitter, e.g.
"production".string
The connection type used by the agent for this conversation.
string
The provider-assigned call identifier, if the emitter included one.
string
The run this trace belongs to, if it came from a simulation.
string
The agent identifier, if the emitter included one.
string
A short excerpt from the conversation for display purposes.
Get a trace
Returns the full transcript and judgment results for a single trace.GET /v1/traces/:traceId
string
required
The 32-character lowercase hex trace ID.
string
required
Start of the search window. Use the trace’s own
started_at value, or a window that contains it.string
required
End of the search window. Use the trace’s own
ended_at value, or a window that contains it.string
Project filter. Follow the same rules as the list endpoint.
object
Full trace metadata. Same fields as the trace summary, without
preview.array
Conversation turns in chronological order. Each turn has
span_id, name, kind, started_at, duration_ns, text, and audio_url (a pre-signed URL to the audio segment, if a recording is available).array
All spans in the trace, nested under their parents. Each span includes
span_id, parent_span_id, name, kind, status, started_at, duration_ns, text, audio_url, tool_name, tool_arguments, tool_result, and child spans.boolean
true when the trace exceeded the store’s span limit and only the first spans are returned. Measures computed from a truncated trace are partial.array
Computed metrics for this conversation, such as turn response latency. Each entry has
measure, unit, samples, worst, and partial.string | null
The Egma simulation ID for this trace, if it was conducted by Egma’s simulator.
null for production traces.array
Grader verdicts for this trace. Each verdict includes the grader ID, the result, and any assertion details.
object | null
The aggregate pass/fail result from required graders.
object | null
The aggregate result from diagnostic-only (non-required) graders.
Get a trace
The
from and to window is required for the detail endpoint too. The trace store is partitioned by time, and a lookup without a window must scan every partition. Pass the same window you used in the list query that found this trace — you already have those values in the list response.