openapi: 3.2.0 info: title: Latitude Traces API version: v1 description: Open-source AI agent monitoring platform. Full observability into what's failing in production. Discover underlying issues, get alerts when something breaks and verify your fix worked. servers: - url: https://api.latitude.so description: Production servers: - url: https://api.latitude.so tags: - name: Traces paths: /v1/projects/{projectSlug}/traces/list: post: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: list summary: List project traces description: Returns a cursor-paginated page of traces in the project. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Trace list rows exclude per-message LLM content — use `getTrace` for the full conversation view. security: - ApiKeyAuth: [] operationId: listTraces parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ListTracesBody' responses: '200': description: Page of traces content: application/json: schema: $ref: '#/components/schemas/PaginatedTraces' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/analytics: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: analytics summary: Get project trace analytics description: 'Returns trace analytics for the project: a total (or median) per metric over the requested range, plus a per-bucket series for each metric. Buckets are 12-hour UTC-aligned. The range defaults to the trailing 7 days.' security: - ApiKeyAuth: [] operationId: getTraceAnalytics parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string format: date-time description: Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`. required: false description: Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`. name: fromIso in: query - schema: type: string format: date-time description: Upper bound (inclusive) of the time range. Defaults to now. required: false description: Upper bound (inclusive) of the time range. Defaults to now. name: toIso in: query responses: '200': description: Trace analytics content: application/json: schema: $ref: '#/components/schemas/TraceAnalyticsResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: get summary: Get project trace description: 'Returns a single trace by id, including its `conversation`: the system instructions and the messages of the trace''s last LLM-completion span, in OpenTelemetry GenAI format.' security: - ApiKeyAuth: [] operationId: getTrace parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path responses: '200': description: Trace detail content: application/json: schema: $ref: '#/components/schemas/TraceDetail' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/spans: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: listSpans summary: List trace spans description: Returns every span belonging to the trace, ordered by `startTime` ascending. Spans carry the OpenTelemetry envelope (kind, status, attributes, resource) plus Latitude's GenAI enrichment (tokens, cost, operation, provider, model). Per-message LLM content is excluded for size; use a span point-lookup for the conversation payload. security: - ApiKeyAuth: [] operationId: listTraceSpans parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path responses: '200': description: Spans of the trace content: application/json: schema: $ref: '#/components/schemas/TraceSpans' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/spans/{spanId}: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: getSpan summary: Get trace span description: Returns one span by id, including the LLM conversation (system instructions, input messages, output messages), tool data (definitions, call id, input, output), and the full OpenTelemetry payload (attributes, resource, events, links) that's excluded from the lighter list shape. security: - ApiKeyAuth: [] operationId: getTraceSpan parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path - schema: type: string minLength: 16 maxLength: 16 description: 16-character span identifier. required: true description: 16-character span identifier. name: spanId in: path responses: '200': description: Span detail content: application/json: schema: $ref: '#/components/schemas/SpanDetail' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/annotations: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: listAnnotations summary: List trace annotations description: Returns a cursor-paginated page of annotations pinned to the trace, including both published annotations and drafts. security: - ApiKeyAuth: [] operationId: listTraceAnnotations parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path - schema: type: string description: Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page. required: false description: Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page. name: cursor in: query - schema: type: integer minimum: 1 maximum: 200 default: 50 description: Page size. Defaults to 50; max 200. required: false description: Page size. Defaults to 50; max 200. name: limit in: query responses: '200': description: Annotations of the trace content: application/json: schema: $ref: '#/components/schemas/PaginatedTraceAnnotations' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/annotations/{annotationId}: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: getAnnotation summary: Get trace annotation description: Returns one annotation by id pinned to the trace. security: - ApiKeyAuth: [] operationId: getTraceAnnotation parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path - schema: type: string minLength: 24 maxLength: 24 description: Stable annotation identifier. required: true description: Stable annotation identifier. name: annotationId in: path responses: '200': description: Annotation content: application/json: schema: $ref: '#/components/schemas/Annotation' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/memory: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: getMemory summary: Get trace memory footprint description: 'Returns the trace''s memory footprint: per-record read, added, and removed token metrics plus totals, scoped to this trace.' security: - ApiKeyAuth: [] operationId: getTraceMemory parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path responses: '200': description: Trace memory footprint content: application/json: schema: $ref: '#/components/schemas/SessionMemorySummary' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/{traceId}/memory/changes: get: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: getMemoryChanges summary: Get trace memory changes description: Returns the memory writes the trace made as per-record before/after diffs, scoped to this trace. security: - ApiKeyAuth: [] operationId: getTraceMemoryChanges parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path - schema: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. required: true description: 32-character trace identifier. name: traceId in: path responses: '200': description: Trace memory changes content: application/json: schema: $ref: '#/components/schemas/SessionMemoryChanges' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' /v1/projects/{projectSlug}/traces/export: post: tags: - Traces x-fern-sdk-group-name: traces x-fern-sdk-method-name: export summary: Export project traces (async) description: Enqueues a CSV export of the traces matched by `traces`. The export runs asynchronously; a download link is emailed to `recipient` when the file is ready. The response returns immediately with `status = "queued"`. The recipient must already be a member of the requesting organization. security: - ApiKeyAuth: [] operationId: exportTraces parameters: - schema: type: string description: Project slug (human-readable identifier) required: true description: Project slug (human-readable identifier) name: projectSlug in: path requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExportTracesBody' responses: '202': description: Export enqueued content: application/json: schema: $ref: '#/components/schemas/ExportTracesResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Export rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TraceAnalyticsTraces: type: object properties: total: type: number description: Number of traces in the range. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Number of traces per bucket. required: - total - buckets TraceAnalyticsDuration: type: object properties: median: type: number description: Median trace duration in seconds. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Median trace duration per bucket in seconds. required: - median - buckets Error: type: object properties: error: type: string required: - error TraceAnalyticsSpans: type: object properties: total: type: number description: Total number of spans. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Number of spans per bucket. required: - total - buckets SessionMemorySummary: type: object properties: records: type: array items: $ref: '#/components/schemas/MemoryRecordSummary' description: Per-record read/write token footprint for the session (or a single trace). total: type: object properties: readTokens: type: integer minimum: 0 description: Total tokens read across the session. tokensAdded: type: integer minimum: 0 description: Total tokens added across the session. tokensRemoved: type: integer minimum: 0 description: Total tokens removed across the session. writeRecords: type: integer minimum: 0 description: Number of records the session wrote, including zero-delta writes. required: - readTokens - tokensAdded - tokensRemoved - writeRecords description: Session-wide totals. required: - records - total ExportTracesResponse: type: object properties: status: type: string enum: - queued description: Always `"queued"`. The CSV is built asynchronously and emailed to `recipient` when ready. required: - status TraceAnalyticsBucket: type: object properties: bucket: type: string description: ISO-8601 UTC timestamp of the bucket's start. value: type: number description: Metric value for this bucket. required: - bucket - value FilterSet: type: object additionalProperties: type: array items: $ref: '#/components/schemas/FilterCondition' description: Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set. TraceAnalyticsTimeToFirstToken: type: object properties: median: type: number description: Median time-to-first-token across LLM spans, in seconds. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Median time-to-first-token per bucket, in seconds. required: - median - buckets GenAISpanSystem: type: array items: type: object additionalProperties: nullable: true description: System instructions in OpenTelemetry GenAI format — an array of part objects. TraceAnalyticsTokens: type: object properties: total: type: number description: Total tokens across all LLM spans. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Tokens per bucket across all LLM spans. required: - total - buckets TraceFilterSet: type: object additionalProperties: type: array items: $ref: '#/components/schemas/FilterCondition' description: 'Filter set keyed by trace field. Each entry holds an array of conditions ANDed together for that field; field-level groups are ANDed across the set. Valid fields: status, name, traceId, sessionId, simulationId, userId, tags, models, providers, serviceNames, tools, definedTools, duration, ttft, cost, spanCount, errorCount, tokensInput, tokensOutput, cacheHitRate, startTime, endTime; score-derived keys (score.passed, score.errored, score.value, score.source, score.sourceId, score.annotatorId, score.signalId, score.simulationId); and arbitrary metadata via `metadata.`. `startTime`/`endTime` take ISO-8601 values (a trace''s first span start / last span end). `gtePercentile` is only supported on duration/ttft/cost — not on time fields. Unknown fields are rejected rather than ignored.' GenAISpanMessage: type: object additionalProperties: nullable: true description: Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls). TracesRef: oneOf: - type: object properties: by: type: string enum: - ids description: Match an explicit list of traces by their identifiers. Pair with `ids`. ids: type: array items: type: string minLength: 32 maxLength: 32 description: 32-character trace identifier. minItems: 1 description: Non-empty list of trace identifiers. required: - by - ids - type: object properties: by: type: string enum: - filters description: Match every trace produced by a filter set. Pair with `filters`; result count is not bounded. filters: $ref: '#/components/schemas/FilterSet' required: - by - filters description: Which traces to include in the export — either explicit ids or a filter set. PaginatedTraceAnnotations: type: object properties: items: type: array items: $ref: '#/components/schemas/Annotation' description: Page of items, in the requested sort order. nextCursor: type: string nullable: true description: Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue. hasMore: type: boolean description: '`true` when there is at least one more page after this one.' required: - items - nextCursor - hasMore TraceAnalyticsCost: type: object properties: total: type: number description: Total trace cost in USD. buckets: type: array items: $ref: '#/components/schemas/TraceAnalyticsBucket' description: Trace cost per bucket in USD. required: - total - buckets SessionMemoryChange: type: object properties: storeId: type: string description: Store the changed record belongs to. recordId: type: string description: Record that changed. kind: type: string enum: - added - updated - removed description: How the session changed the record. beforeBody: type: string nullable: true description: The record's body before the session's writes. `null` when added or when the prior body was not captured. afterBody: type: string nullable: true description: The record's body after the session's writes. `null` when removed or when the body was not captured. tokensAdded: type: integer minimum: 0 description: Tokens added by the session's writes. tokensRemoved: type: integer minimum: 0 description: Tokens removed by the session's writes. degraded: type: boolean description: '`true` when a side''s body was unavailable, so the diff is incomplete.' lastChangeSpanId: type: string nullable: true description: Span of the session's last write to this record. `null` when unknown. required: - storeId - recordId - kind - beforeBody - afterBody - tokensAdded - tokensRemoved - degraded - lastChangeSpanId TraceSpans: type: object properties: items: type: array items: $ref: '#/components/schemas/Span' description: All spans belonging to the trace, ordered by `startTime` ascending. required: - items SpanDetail: type: object properties: organizationId: type: string description: Organization that owns this span. projectId: type: string description: Project this span belongs to. traceId: type: string description: Identifier of the trace this span belongs to. spanId: type: string description: Stable span identifier within the trace. parentSpanId: type: string nullable: true description: Identifier of the parent span. `null` for root spans. sessionId: type: string nullable: true description: Conversation/session identifier set by the SDK. `null` when absent. userId: type: string nullable: true description: End-user identifier set by the SDK. `null` when absent. simulationId: type: string nullable: true description: CUID of the simulation that produced this span. `null` when not a simulation. apiKeyId: type: string nullable: true description: Latitude API key used to ingest the span. `null` when ingested without an API key. startTime: type: string description: ISO-8601 timestamp at which the span started. endTime: type: string description: ISO-8601 timestamp at which the span ended. name: type: string description: Span name (e.g. the entry-point function or route). serviceName: type: string description: OpenTelemetry `service.name` of the emitting service. kind: type: string enum: - unspecified - internal - server - client - producer - consumer description: OpenTelemetry span kind. statusCode: type: string enum: - unset - ok - error description: OpenTelemetry span status code. statusMessage: type: string description: OpenTelemetry status message. Empty when not set. traceFlags: type: number description: OpenTelemetry trace flags bitfield. traceState: type: string description: OpenTelemetry trace state (vendor-specific propagation). Empty when not set. errorType: type: string nullable: true description: Error class/type label when the span errored. `null` for successful spans. tags: type: array items: type: string description: Free-form tags attached at ingest time. operation: type: string description: GenAI operation category (e.g. `"chat"`, `"embeddings"`, `"execute_tool"`, `"invoke_agent"`) or a custom string for non-GenAI spans. provider: type: string nullable: true description: LLM provider id. `null` for non-LLM spans. model: type: string nullable: true description: Model id as requested. `null` for non-LLM spans. responseModel: type: string nullable: true description: Model id reported by the provider's response. `null` for non-LLM spans. tokensInput: type: number description: Input tokens consumed by this span. tokensOutput: type: number description: Output tokens produced by this span. tokensCacheRead: type: number description: Tokens served from the provider's prompt cache. tokensCacheCreate: type: number description: Tokens written to the provider's prompt cache. tokensReasoning: type: number description: Reasoning tokens reported by the model. costInputMicrocents: type: number description: Cost of input tokens in microcents (100,000,000 per USD). costOutputMicrocents: type: number description: Cost of output tokens in microcents (100,000,000 per USD). costTotalMicrocents: type: number description: Total cost in microcents (100,000,000 per USD). costIsEstimated: type: boolean description: '`true` when the cost was derived from public pricing tables instead of the provider''s bill.' costSource: type: string enum: - provider_reported - user_reported - estimated - unpriced - no_tokens - unknown description: 'Where the cost came from. `provider_reported`: the instrumentation sent it. `user_reported`: you sent it with `latitude.cost.source` set to `user`. `estimated`: priced from public model pricing. `unpriced`: tokens were reported but no pricing matched, so the cost is 0 but not free. `no_tokens`: nothing to price. `unknown`: ingested before cost sources were tracked, so a 0 cannot be read as free.' timeToFirstTokenNs: type: number description: Nanoseconds from the start of the span to its first emitted token. `0` if not measured. isStreaming: type: boolean description: '`true` when the span was produced by a streaming LLM call.' responseId: type: string nullable: true description: Response identifier returned by the LLM. `null` when the provider didn't return one. finishReasons: type: array items: type: string description: Per-choice finish reasons reported by the LLM provider. scopeName: type: string description: OpenTelemetry instrumentation scope name. Empty when not set. scopeVersion: type: string description: OpenTelemetry instrumentation scope version. Empty when not set. retentionDays: type: integer minimum: 0 exclusiveMinimum: true description: Per-span retention override in days. Omitted when the project default applies. ingestedAt: type: string description: ISO-8601 timestamp at which Latitude received this span. metadata: type: object additionalProperties: type: string description: Free-form metadata attached at ingest time. systemInstructions: $ref: '#/components/schemas/GenAISpanSystem' inputMessages: type: array items: $ref: '#/components/schemas/GenAISpanMessage' description: Input messages sent into this LLM span, in OpenTelemetry GenAI format. outputMessages: type: array items: $ref: '#/components/schemas/GenAISpanMessage' description: Output messages returned by this LLM span, in OpenTelemetry GenAI format. toolDefinitions: type: array items: $ref: '#/components/schemas/ToolDefinition' description: Tool/function definitions made available to the LLM for this span. toolCallId: type: string description: Tool-call id this span answers. Empty when the span isn't an `execute_tool` span. toolName: type: string description: Name of the executed tool. Empty when the span isn't an `execute_tool` span. toolInput: type: string description: Stringified arguments passed to the tool. Empty when the span isn't an `execute_tool` span. toolOutput: type: string description: Stringified tool output. Empty when the span isn't an `execute_tool` span. attrString: type: object additionalProperties: type: string description: OpenTelemetry attributes with string values. attrInt: type: object additionalProperties: type: number description: OpenTelemetry attributes with integer values. attrFloat: type: object additionalProperties: type: number description: OpenTelemetry attributes with floating-point values. attrBool: type: object additionalProperties: type: boolean description: OpenTelemetry attributes with boolean values. resourceString: type: object additionalProperties: type: string description: OpenTelemetry resource attributes captured at ingest. eventsJson: type: string description: JSON-encoded OpenTelemetry events array. Empty when the span has no events. linksJson: type: string description: JSON-encoded OpenTelemetry span-links array. Empty when the span has no links. required: - organizationId - projectId - traceId - spanId - parentSpanId - sessionId - userId - simulationId - apiKeyId - startTime - endTime - name - serviceName - kind - statusCode - statusMessage - traceFlags - traceState - errorType - tags - operation - provider - model - responseModel - tokensInput - tokensOutput - tokensCacheRead - tokensCacheCreate - tokensReasoning - costInputMicrocents - costOutputMicrocents - costTotalMicrocents - costIsEstimated - costSource - timeToFirstTokenNs - isStreaming - responseId - finishReasons - scopeName - scopeVersion - ingestedAt - metadata - systemInstructions - inputMessages - outputMessages - toolDefinitions - toolCallId - toolName - toolInput - toolOutput - attrString - attrInt - attrFloat - attrBool - resourceString - eventsJson - linksJson AnnotationMetadata: type: object properties: rawFeedback: type: string description: Original feedback text as written by the annotator, before any server-side enrichment. messageIndex: type: integer minimum: 0 description: 0-based message index inside the conversation. Omit for conversation-level annotations. partIndex: type: integer minimum: 0 description: 0-based index into the target message's `parts[]`. Requires `messageIndex`. startOffset: type: integer minimum: 0 description: Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`. endOffset: type: integer minimum: 0 description: Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`. textFormat: type: string enum: - pretty-json description: UI-side text transform applied before the offsets were captured (e.g. `"pretty-json"`). Resolvers must apply the same transform before slicing. required: - rawFeedback description: 'Annotation-specific metadata: `rawFeedback` plus a snapshot of the anchor at write time.' ListTracesBody: type: object properties: cursor: type: string description: Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page. limit: type: integer minimum: 1 maximum: 200 default: 50 description: Page size. Defaults to 50; max 200. sortBy: type: string enum: - relevance - startTime - endTime - durationNs - tokensTotal - costTotalMicrocents default: startTime description: Field to sort by. Defaults to `startTime`. Pass `relevance` together with `query` to rank by semantic match (best match first, then most recent). sortDirection: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to `desc` (most recent first). query: type: string maxLength: 500 description: Free-text semantic search across the trace's input and output messages. Combined with `filters` via AND. filters: $ref: '#/components/schemas/TraceFilterSet' Annotation: type: object properties: id: type: string minLength: 24 maxLength: 24 description: Stable annotation identifier. organizationId: type: string minLength: 24 maxLength: 24 description: Organization that owns this annotation. projectId: type: string minLength: 24 maxLength: 24 description: Project this annotation lives in. sessionId: type: string nullable: true maxLength: 128 description: Session id lifted from the annotated trace. `null` when the trace has no session. traceId: type: string nullable: true minLength: 32 maxLength: 32 description: Identifier of the annotated trace. spanId: type: string nullable: true minLength: 16 maxLength: 16 description: Span the annotation pins to. Defaults to the trace's last LLM-completion span. simulationId: type: string nullable: true minLength: 24 maxLength: 24 description: Simulation reference, if any. signalId: type: string nullable: true minLength: 24 maxLength: 24 description: Signal this annotation contributes to, if any. value: type: number minimum: 0 maximum: 1 description: Normalized score value in [0, 1]. Higher = better. passed: type: boolean description: Whether the annotation marks the output as passing. feedback: type: string description: Free-text feedback explaining the score. error: type: string nullable: true minLength: 1 description: Generation error text, when the annotation itself errored. `null` for successful annotations. errored: type: boolean description: '`true` when the annotation could not be generated successfully.' duration: type: integer minimum: 0 description: Generation duration in nanoseconds. `0` for human annotations. tokens: type: integer minimum: 0 description: Total LLM tokens consumed generating the score. `0` for human annotations. cost: type: integer minimum: 0 description: Total LLM cost in microcents (100,000,000 per USD). `0` for human annotations. draftedAt: type: string nullable: true format: date-time description: ISO-8601 timestamp at which the annotation was drafted. `null` for published annotations. annotatorId: type: string nullable: true minLength: 24 maxLength: 24 description: User who authored the annotation. `null` when not attributed to a user. createdAt: type: string format: date-time description: ISO-8601 timestamp at which the annotation was created. updatedAt: type: string format: date-time description: ISO-8601 timestamp of the last metadata update. source: type: string enum: - annotation description: Always `"annotation"` for this shape. sourceId: anyOf: - type: string enum: - UI - API - SYSTEM - type: string minLength: 24 maxLength: 24 description: Origin marker. Sentinel `"UI"` / `"API"` / `"SYSTEM"` for drafts and automation, or a CUID for authored rows. metadata: $ref: '#/components/schemas/AnnotationMetadata' required: - id - organizationId - projectId - sessionId - traceId - spanId - simulationId - signalId - value - passed - feedback - error - errored - duration - tokens - cost - draftedAt - annotatorId - createdAt - updatedAt - source - sourceId - metadata SessionMemoryChanges: type: object properties: records: type: array items: $ref: '#/components/schemas/SessionMemoryChange' description: Per-record before/after diffs for what the session changed. required: - records Trace: type: object properties: organizationId: type: string description: Organization that owns this trace. projectId: type: string description: Project this trace belongs to. traceId: type: string description: 32-character trace identifier. spanCount: type: integer minimum: 0 description: Total number of spans in the trace. errorCount: type: integer minimum: 0 description: Number of spans flagged with an error status. startTime: type: string description: ISO-8601 timestamp of the trace's earliest span. endTime: type: string description: ISO-8601 timestamp of the trace's latest span. durationNs: type: number description: Wall-clock duration of the trace in nanoseconds. timeToFirstTokenNs: type: number description: Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured. tokensInput: type: number description: Total input tokens across LLM spans. tokensOutput: type: number description: Total output tokens across LLM spans. tokensCacheRead: type: number description: Total tokens served from the provider's prompt cache. tokensCacheCreate: type: number description: Total tokens written to the provider's prompt cache. tokensReasoning: type: number description: Total reasoning tokens reported by the model. tokensTotal: type: number description: Sum of all token counters. costInputMicrocents: type: number description: Cost of input tokens in microcents (100,000,000 per USD). costOutputMicrocents: type: number description: Cost of output tokens in microcents (100,000,000 per USD). costTotalMicrocents: type: number description: Total cost in microcents (100,000,000 per USD). sessionId: type: string nullable: true description: Conversation/session identifier set by the SDK. `null` when absent. userId: type: string nullable: true description: End-user identifier set by the SDK. `null` when absent. simulationId: type: string nullable: true description: CUID of the simulation that produced this trace. `null` when not a simulation. tags: type: array items: type: string description: Free-form tags attached at ingest time. models: type: array items: type: string description: Model identifiers seen across the trace's LLM spans. providers: type: array items: type: string description: LLM-provider identifiers seen across the trace's spans. serviceNames: type: array items: type: string description: OpenTelemetry `service.name` values seen in the trace. rootSpanId: type: string nullable: true description: Identifier of the trace's root span. `null` when no root span has been ingested. rootSpanName: type: string nullable: true description: '`name` attribute of the root span. `null` when no root span has been ingested.' positiveAnnotationCount: type: integer minimum: 0 description: Number of `passed = true` annotations attached to this trace. negativeAnnotationCount: type: integer minimum: 0 description: Number of `passed = false` annotations attached to this trace. required: - organizationId - projectId - traceId - spanCount - errorCount - startTime - endTime - durationNs - timeToFirstTokenNs - tokensInput - tokensOutput - tokensCacheRead - tokensCacheCreate - tokensReasoning - tokensTotal - costInputMicrocents - costOutputMicrocents - costTotalMicrocents - sessionId - userId - simulationId - tags - models - providers - serviceNames - rootSpanId - rootSpanName - positiveAnnotationCount - negativeAnnotationCount MemoryRecordSummary: type: object properties: storeId: type: string description: Store the record belongs to. recordId: type: string description: Record the metrics are for. readTokens: type: integer minimum: 0 description: Tokens read from this record across the session's retrievals. tokensAdded: type: integer minimum: 0 description: Tokens the session added to this record (endpoint diff). tokensRemoved: type: integer minimum: 0 description: Tokens the session removed from this record (endpoint diff). required: - storeId - recordId - readTokens - tokensAdded - tokensRemoved ExportTracesBody: type: object properties: traces: $ref: '#/components/schemas/TracesRef' recipient: type: string format: email description: Email address the export download link is sent to. Must belong to a member of the requesting organization — otherwise the request is rejected with 400. required: - traces - recipient FilterCondition: type: object properties: op: type: string enum: - eq - neq - gt - gte - lt - lte - in - notIn - contains - notContains - gtePercentile description: Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference. value: anyOf: - type: string - type: number - type: boolean - type: array items: anyOf: - type: string - type: number description: Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators. required: - op - value TraceAnalyticsResponse: type: object properties: traces: $ref: '#/components/schemas/TraceAnalyticsTraces' cost: $ref: '#/components/schemas/TraceAnalyticsCost' duration: $ref: '#/components/schemas/TraceAnalyticsDuration' tokens: $ref: '#/components/schemas/TraceAnalyticsTokens' timeToFirstToken: $ref: '#/components/schemas/TraceAnalyticsTimeToFirstToken' spans: $ref: '#/components/schemas/TraceAnalyticsSpans' required: - traces - cost - duration - tokens - timeToFirstToken - spans ToolDefinition: type: object properties: name: type: string description: Tool name as exposed to the LLM. description: type: string description: Tool description as exposed to the LLM. parameters: nullable: true description: JSON Schema for the tool's parameters, as provided by the caller. required: - name - description TraceDetail: type: object properties: organizationId: type: string description: Organization that owns this trace. projectId: type: string description: Project this trace belongs to. traceId: type: string description: 32-character trace identifier. spanCount: type: integer minimum: 0 description: Total number of spans in the trace. errorCount: type: integer minimum: 0 description: Number of spans flagged with an error status. startTime: type: string description: ISO-8601 timestamp of the trace's earliest span. endTime: type: string description: ISO-8601 timestamp of the trace's latest span. durationNs: type: number description: Wall-clock duration of the trace in nanoseconds. timeToFirstTokenNs: type: number description: Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured. tokensInput: type: number description: Total input tokens across LLM spans. tokensOutput: type: number description: Total output tokens across LLM spans. tokensCacheRead: type: number description: Total tokens served from the provider's prompt cache. tokensCacheCreate: type: number description: Total tokens written to the provider's prompt cache. tokensReasoning: type: number description: Total reasoning tokens reported by the model. tokensTotal: type: number description: Sum of all token counters. costInputMicrocents: type: number description: Cost of input tokens in microcents (100,000,000 per USD). costOutputMicrocents: type: number description: Cost of output tokens in microcents (100,000,000 per USD). costTotalMicrocents: type: number description: Total cost in microcents (100,000,000 per USD). sessionId: type: string nullable: true description: Conversation/session identifier set by the SDK. `null` when absent. userId: type: string nullable: true description: End-user identifier set by the SDK. `null` when absent. simulationId: type: string nullable: true description: CUID of the simulation that produced this trace. `null` when not a simulation. tags: type: array items: type: string description: Free-form tags attached at ingest time. models: type: array items: type: string description: Model identifiers seen across the trace's LLM spans. providers: type: array items: type: string description: LLM-provider identifiers seen across the trace's spans. serviceNames: type: array items: type: string description: OpenTelemetry `service.name` values seen in the trace. rootSpanId: type: string nullable: true description: Identifier of the trace's root span. `null` when no root span has been ingested. rootSpanName: type: string nullable: true description: '`name` attribute of the root span. `null` when no root span has been ingested.' positiveAnnotationCount: type: integer minimum: 0 description: Number of `passed = true` annotations attached to this trace. negativeAnnotationCount: type: integer minimum: 0 description: Number of `passed = false` annotations attached to this trace. metadata: type: object additionalProperties: type: string description: Free-form metadata attached at ingest time. conversation: type: array items: $ref: '#/components/schemas/GenAIMessage' description: 'Full conversation for the trace, in OpenTelemetry GenAI format: the system instructions, then the messages sent into the trace''s last LLM-completion span (the running history at that point), followed by that span''s generated output.' required: - organizationId - projectId - traceId - spanCount - errorCount - startTime - endTime - durationNs - timeToFirstTokenNs - tokensInput - tokensOutput - tokensCacheRead - tokensCacheCreate - tokensReasoning - tokensTotal - costInputMicrocents - costOutputMicrocents - costTotalMicrocents - sessionId - userId - simulationId - tags - models - providers - serviceNames - rootSpanId - rootSpanName - positiveAnnotationCount - negativeAnnotationCount - metadata - conversation GenAIMessage: type: object additionalProperties: nullable: true description: Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls). PaginatedTraces: type: object properties: items: type: array items: $ref: '#/components/schemas/Trace' description: Page of items, in the requested sort order. nextCursor: type: string nullable: true description: Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue. hasMore: type: boolean description: '`true` when there is at least one more page after this one.' required: - items - nextCursor - hasMore Span: type: object properties: organizationId: type: string description: Organization that owns this span. projectId: type: string description: Project this span belongs to. traceId: type: string description: Identifier of the trace this span belongs to. spanId: type: string description: Stable span identifier within the trace. parentSpanId: type: string nullable: true description: Identifier of the parent span. `null` for root spans. sessionId: type: string nullable: true description: Conversation/session identifier set by the SDK. `null` when absent. userId: type: string nullable: true description: End-user identifier set by the SDK. `null` when absent. simulationId: type: string nullable: true description: CUID of the simulation that produced this span. `null` when not a simulation. apiKeyId: type: string nullable: true description: Latitude API key used to ingest the span. `null` when ingested without an API key. startTime: type: string description: ISO-8601 timestamp at which the span started. endTime: type: string description: ISO-8601 timestamp at which the span ended. name: type: string description: Span name (e.g. the entry-point function or route). serviceName: type: string description: OpenTelemetry `service.name` of the emitting service. kind: type: string enum: - unspecified - internal - server - client - producer - consumer description: OpenTelemetry span kind. statusCode: type: string enum: - unset - ok - error description: OpenTelemetry span status code. statusMessage: type: string description: OpenTelemetry status message. Empty when not set. traceFlags: type: number description: OpenTelemetry trace flags bitfield. traceState: type: string description: OpenTelemetry trace state (vendor-specific propagation). Empty when not set. errorType: type: string nullable: true description: Error class/type label when the span errored. `null` for successful spans. tags: type: array items: type: string description: Free-form tags attached at ingest time. operation: type: string description: GenAI operation category (e.g. `"chat"`, `"embeddings"`, `"execute_tool"`, `"invoke_agent"`) or a custom string for non-GenAI spans. provider: type: string nullable: true description: LLM provider id. `null` for non-LLM spans. model: type: string nullable: true description: Model id as requested. `null` for non-LLM spans. responseModel: type: string nullable: true description: Model id reported by the provider's response. `null` for non-LLM spans. tokensInput: type: number description: Input tokens consumed by this span. tokensOutput: type: number description: Output tokens produced by this span. tokensCacheRead: type: number description: Tokens served from the provider's prompt cache. tokensCacheCreate: type: number description: Tokens written to the provider's prompt cache. tokensReasoning: type: number description: Reasoning tokens reported by the model. costInputMicrocents: type: number description: Cost of input tokens in microcents (100,000,000 per USD). costOutputMicrocents: type: number description: Cost of output tokens in microcents (100,000,000 per USD). costTotalMicrocents: type: number description: Total cost in microcents (100,000,000 per USD). costIsEstimated: type: boolean description: '`true` when the cost was derived from public pricing tables instead of the provider''s bill.' costSource: type: string enum: - provider_reported - user_reported - estimated - unpriced - no_tokens - unknown description: 'Where the cost came from. `provider_reported`: the instrumentation sent it. `user_reported`: you sent it with `latitude.cost.source` set to `user`. `estimated`: priced from public model pricing. `unpriced`: tokens were reported but no pricing matched, so the cost is 0 but not free. `no_tokens`: nothing to price. `unknown`: ingested before cost sources were tracked, so a 0 cannot be read as free.' timeToFirstTokenNs: type: number description: Nanoseconds from the start of the span to its first emitted token. `0` if not measured. isStreaming: type: boolean description: '`true` when the span was produced by a streaming LLM call.' responseId: type: string nullable: true description: Response identifier returned by the LLM. `null` when the provider didn't return one. finishReasons: type: array items: type: string description: Per-choice finish reasons reported by the LLM provider. scopeName: type: string description: OpenTelemetry instrumentation scope name. Empty when not set. scopeVersion: type: string description: OpenTelemetry instrumentation scope version. Empty when not set. retentionDays: type: integer minimum: 0 exclusiveMinimum: true description: Per-span retention override in days. Omitted when the project default applies. ingestedAt: type: string description: ISO-8601 timestamp at which Latitude received this span. required: - organizationId - projectId - traceId - spanId - parentSpanId - sessionId - userId - simulationId - apiKeyId - startTime - endTime - name - serviceName - kind - statusCode - statusMessage - traceFlags - traceState - errorType - tags - operation - provider - model - responseModel - tokensInput - tokensOutput - tokensCacheRead - tokensCacheCreate - tokensReasoning - costInputMicrocents - costOutputMicrocents - costTotalMicrocents - costIsEstimated - costSource - timeToFirstTokenNs - isStreaming - responseId - finishReasons - scopeName - scopeVersion - ingestedAt securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API key description: 'Organization-scoped API key, sent as `Authorization: Bearer `.' x-fern-bearer: name: apiKey env: LATITUDE_API_KEY