openapi: 3.2.0 info: description: 'Use the Application Performance Monitoring Trace Explorer API to query traces and associated spans in Trace Explorer. For more information, see [Application Performance Monitoring](https://docs.oracle.com/iaas/application-performance-monitoring/index.html). ' license: name: Oracle Corporation title: Application Performance Monitoring Explorer Trace API version: '20200630' x-provenance: method: harvested first_party: true publisher: Oracle source: https://docs.oracle.com/en-us/iaas/api/specs/d1cc8021a03784e751fe54c779074681c153f47a8bd2975f098d6c8988748126.yaml harvested: '2026-08-04' note: Published by Oracle as the contract for the Application Performance Monitoring Trace Explorer API OCI service and stored verbatim; API Evangelist added only this provenance block. x-evidence: - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json what: Oracle's own index of every OCI service specification - url: https://docs.oracle.com/en-us/iaas/api/specs/d1cc8021a03784e751fe54c779074681c153f47a8bd2975f098d6c8988748126.yaml what: the harvested document for Application Performance Monitoring Trace Explorer API servers: - url: http://apm-trace.{region}.oci.{secondLevelDomain}/20200630 - url: https://apm-trace.{region}.oci.{secondLevelDomain}/20200630 tags: - description: '"Everything about your trace, related spans, and tags" ' externalDocs: description: '"Find out more" ' url: https://confluence.oci.oraclecorp.com/display/APM/TraceInstance+Model name: trace paths: /spans/{traceKey}/{spanKey}: get: description: 'Gets the span details identified by spanId. ' operationId: GetSpan parameters: - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/ApmDomainIdQueryParam' - $ref: '#/components/parameters/SpanIdentifierPathParam' - $ref: '#/components/parameters/TraceIdentifierPathParam' - $ref: '#/components/parameters/SpanStartTimeGreaterThanOrEqualToNotRequiredParam' - $ref: '#/components/parameters/SpanStartTimeLessThanNotRequiredParam' - $ref: '#/components/parameters/SpanNamespaceParam' responses: 200: description: 'A span with all associated details is returned. ' headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Span' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/DefaultError' summary: Span details for a given span id. tags: - trace x-related-resource: '#/definitions/Span' /traces/{traceKey}: get: description: 'Gets the trace details identified by traceId. ' operationId: GetTrace parameters: - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/ApmDomainIdQueryParam' - $ref: '#/components/parameters/TraceIdentifierPathParam' - $ref: '#/components/parameters/TraceStartTimeGreaterThanOrEqualToParam' - $ref: '#/components/parameters/TraceStartTimeLessThanParam' - $ref: '#/components/parameters/TraceNamespaceParam' responses: 200: description: 'A trace with all the associated span objects is returned. ' headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Trace' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/DefaultError' summary: Trace details for a given traceId. tags: - trace x-related-resource: '#/definitions/Trace' /traces/{traceKey}/aggregatedSnapshotData: get: description: 'Gets the aggregated snapshot identified by trace ID. ' operationId: GetAggregatedSnapshot parameters: - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/ApmDomainIdQueryParam' - $ref: '#/components/parameters/TraceIdentifierPathParam' responses: 200: description: 'An aggregated snapshot object is returned. ' headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/AggregatedSnapshot' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/DefaultError' summary: Aggregated snapshot for a given trace ID. tags: - trace x-related-resource: '#/definitions/AggregatedSnapshot' /traces/{traceKey}/snapshotData: get: description: 'Gets the trace snapshots data identified by trace ID. ' operationId: GetTraceSnapshot parameters: - $ref: '#/components/parameters/RequestIdHeader' - $ref: '#/components/parameters/ApmDomainIdQueryParam' - $ref: '#/components/parameters/TraceIdentifierPathParam' - $ref: '#/components/parameters/IsSummaryQueryParam' - $ref: '#/components/parameters/ThreadIdQueryParam' - $ref: '#/components/parameters/SnapshotTimeQueryParam' responses: 200: description: 'All trace snapshots are returned. ' headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/TraceSnapshot' 400: $ref: '#/components/responses/400' 401: $ref: '#/components/responses/401' 404: $ref: '#/components/responses/404' 412: $ref: '#/components/responses/412' 429: $ref: '#/components/responses/429' 500: $ref: '#/components/responses/500' default: $ref: '#/components/responses/DefaultError' summary: Trace snapshots data for a given trace ID. tags: - trace x-related-resource: '#/definitions/TraceSnapshot' components: parameters: TraceStartTimeGreaterThanOrEqualToParam: description: 'Include traces that have a minTraceStartTime equal to or greater than this value. ' in: query name: timeTraceStartedGreaterThanOrEqualTo required: false x-default-description: 'null' schema: type: string format: date-time TraceNamespaceParam: description: 'Name space from which the trace details need to be retrieved. ' in: query name: traceNamespace required: false x-default-description: 'null' schema: type: string enum: - TRACES - SYNTHETIC ThreadIdQueryParam: description: 'Thread ID for which snapshots need to be retrieved. This identifier of a thread is a long positive number generated when a thread is created. ' in: query name: threadId required: false x-default-description: 'null' schema: type: string TraceStartTimeLessThanParam: description: 'Include traces that have a minTraceStartTime less than this value. ' in: query name: timeTraceStartedLessThan required: false x-default-description: 'null' schema: type: string format: date-time ApmDomainIdQueryParam: description: 'The APM Domain ID for the intended request. ' in: query name: apmDomainId required: true schema: type: string SpanStartTimeLessThanNotRequiredParam: description: 'Include spans that have a `spanStartTime`less than this value. ' in: query name: timeSpanStartedLessThan required: false x-default-description: 'null' schema: type: string format: date-time SpanNamespaceParam: description: 'Name space from which the span details need to be retrieved. ' in: query name: spanNamespace required: false x-default-description: 'null' schema: type: string enum: - TRACES - SYNTHETIC SnapshotTimeQueryParam: description: 'Epoch time of snapshot. ' in: query name: snapshotTime required: false x-default-description: 'null' schema: type: string IsSummaryQueryParam: description: 'If enabled, only span level details are sent. ' in: query name: isSummarized required: false x-default-description: 'null' schema: type: boolean SpanIdentifierPathParam: description: 'Unique Application Performance Monitoring span identifier (spanId). ' in: path name: spanKey required: true schema: type: string SpanStartTimeGreaterThanOrEqualToNotRequiredParam: description: 'Include spans that have a `spanStartTime` equal to or greater than this value. ' in: query name: timeSpanStartedGreaterThanOrEqualTo required: false x-default-description: 'null' schema: type: string format: date-time TraceIdentifierPathParam: description: 'Unique Application Performance Monitoring trace identifier (traceId). ' in: path name: traceKey required: true schema: type: string RequestIdHeader: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' in: header name: opc-request-id schema: type: string schemas: TraceServiceSummary: description: 'Summary of the spans in a trace by service. ' properties: errorSpans: description: 'Number of spans with errors for serviceName in the trace. ' format: int64 type: integer spanServiceName: description: 'Name associated with the service. ' type: string totalSpans: description: 'Number of spans for serviceName in the trace. ' format: int64 type: integer required: - spanServiceName - totalSpans - errorSpans type: object Error: description: 'Details of an error that occurred. ' properties: code: description: 'A short error code that defines the error, meant for programmatic parsing. ' type: string message: description: 'A human-readable error string. ' type: string required: - code - message type: object ThreadSnapshot: description: 'Thread snapshot. ' properties: stackTrace: description: 'Stack trace. ' items: $ref: '#/components/schemas/StackTraceElement' type: array threadSnapshotDetails: description: 'Snapshot details. ' items: $ref: '#/components/schemas/SnapshotDetail' type: array timeStamp: description: 'Snapshot time. ' format: date-time type: string type: object SnapshotDetail: description: 'A generic key value pair object, which contains information such as the thread ID, thread name, and thread state. ' properties: key: description: 'Name of the property. ' type: string value: description: 'Value of the property. ' type: object type: object StackTraceElement: description: 'Stack trace element. ' properties: className: description: 'Name of the class containing the execution point. ' type: string fileName: description: 'Name of the source file containing the execution point. ' type: string lineNumber: description: 'Line number of the source line containing the execution point. ' type: integer methodName: description: 'Name of the method containing the execution point. ' type: string weightage: description: 'The weight distribution that denotes the percentage occurrence of a method in the captured snapshots. ' format: float type: number type: object TraceSpanSummary: description: 'Summary of the information pertaining to the spans in the trace window that is being queried. ' properties: errorSpanCount: description: "The number of spans with errors that have been processed by the system for the trace.\nNote that the number of spans with errors will be less than or equal to the total number of spans in the trace. \n" format: int32 maximum: 604800 minimum: 0 type: integer isFault: description: 'Boolean flag that indicates whether the trace has an error. ' type: boolean key: description: 'Unique identifier (traceId) for the trace that represents the span set. Note that this field is defined as traceKey in the API and it maps to the traceId in the trace data in Application Performance Monitoring. ' type: string rootSpanDurationInMs: description: 'Time taken for the root span operation to complete in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer rootSpanOperationName: description: 'Root span name associated with the trace. This is the flow start operation name. Null is displayed if the root span is not yet completed. ' type: string rootSpanServiceName: description: 'Service associated with the trace. ' type: string serviceSummaries: description: 'A summary of the spans by service. ' items: $ref: '#/components/schemas/TraceServiceSummary' type: array spanCount: description: 'The number of spans that have been processed by the system for the trace. Note that there could be additional spans that have not been processed or reported yet if the trace is still in progress. ' format: int32 maximum: 604800 minimum: 0 type: integer timeEarliestSpanStarted: description: 'Start time of the earliest span in the span collection. ' format: date-time type: string timeLatestSpanEnded: description: 'End time of the span that most recently ended in the span collection. ' format: date-time type: string timeRootSpanEnded: description: 'End time of the root span for the span collection. ' format: date-time type: string timeRootSpanStarted: description: 'Start time of the root span for the span collection. ' format: date-time type: string traceDurationInMs: description: 'Time between the start of the earliest span and the end of the most recent span in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer traceErrorCode: description: 'Error code of the trace. ' type: string traceErrorType: description: 'Error type of the trace. ' type: string traceStatus: description: 'The status of the trace. The trace statuses are defined as follows: complete - a root span has been recorded, but there is no information on the errors. success - a complete root span is recorded there is a successful error type and error code - HTTP 200. incomplete - the root span has not yet been received. error - the root span returned with an error. There may or may not be an associated error code or error type. ' type: string required: - key - timeEarliestSpanStarted - timeLatestSpanEnded - spanCount - errorSpanCount - traceDurationInMs - isFault - traceStatus - traceErrorCode - traceErrorType type: object AggregatedStackTrace: description: 'A branching tree with aggregated stack trace. ' properties: children: description: 'List of child aggregated stack trace to represent branches. ' items: $ref: '#/components/schemas/AggregatedStackTrace' type: array stackTraceElement: $ref: '#/components/schemas/StackTraceElement' type: object SpanLog: description: 'Definition of a log which is a key-value pair of log data. ' properties: logKey: description: 'Key that specifies the log name. ' type: string logValue: description: 'Value associated with the log key. ' type: string required: - logKey - logValue type: object AggregatedSnapshot: description: 'Aggregated snapshots of all spans. ' properties: aggregatedStackTraces: description: 'List of aggregated stack trace. ' items: $ref: '#/components/schemas/AggregatedStackTrace' type: array details: description: 'Aggregated snapshot details. ' items: $ref: '#/components/schemas/SnapshotDetail' type: array required: - details - aggregatedStackTraces type: object Tag: description: 'Definition of a tag which is a key-value pair. ' properties: tagName: description: 'Key that specifies the tag name. ' type: string tagValue: description: 'Value associated with the tag key. ' type: string required: - tagName - tagValue type: object TraceSnapshot: description: 'Definition of a trace snapshot object. ' properties: key: description: 'Unique identifier (traceId) for the trace that represents the span set. Note that this field is defined as traceKey in the API and it maps to the traceId in the trace data in Application Performance Monitoring. ' type: string spanSnapshots: description: 'List of spans. ' items: $ref: '#/components/schemas/SpanSnapshot' type: array timeEnded: description: 'End time of the trace. ' format: date-time type: string timeStarted: description: 'Start time of the trace. ' format: date-time type: string traceSnapshotDetails: description: 'Trace snapshots properties. ' items: $ref: '#/components/schemas/SnapshotDetail' type: array required: - key - spanSnapshots type: object Span: description: 'Definition of a span object. ' properties: durationInMs: description: 'Total span duration in milliseconds. ' format: int64 type: integer isError: description: 'Indicates if the span has an error. ' type: boolean key: description: 'Unique identifier (spanId) for the span. Note that this field is defined as spanKey in the API and it maps to the spanId in the trace data in Application Performance Monitoring. ' type: string kind: description: 'Kind associated with the span. ' type: string logs: description: 'List of logs associated with the span. ' items: $ref: '#/components/schemas/SpanLogCollection' type: array operationName: description: 'Span name associated with the trace. This is usually the method or URI of the request. ' type: string parentSpanKey: description: 'Unique parent identifier for the span if one exists. For root spans this will be null. ' type: string serviceName: description: 'Service name associated with the span. ' type: string sourceName: description: 'Source of span (spans, syn_spans). ' enum: - SPANS - SYN_SPANS type: string tags: description: 'List of tags associated with the span. ' items: $ref: '#/components/schemas/Tag' type: array tagsMetadata: additionalProperties: $ref: '#/components/schemas/TagMetadata' description: 'Metadata about the tags in the span. ' type: object timeEnded: description: 'Span end time. Timestamp when the span was completed. ' format: date-time type: string timeStarted: description: 'Span start time. Timestamp when the span was started. ' format: date-time type: string traceKey: description: 'Unique identifier for the trace. ' type: string required: - key - traceKey - timeStarted - timeEnded - durationInMs - operationName - isError type: object Trace: description: 'Definition of a trace object. ' properties: errorSpanCount: description: "The number of spans with errors that have been processed by the system for the trace.\nNote that the number of spans with errors will be less than or equal to the total number of spans in the trace. \n" format: int32 maximum: 604800 minimum: 0 type: integer isFault: description: 'Boolean flag that indicates whether the trace has an error. ' type: boolean key: description: 'Unique identifier (traceId) for the trace that represents the span set. Note that this field is defined as traceKey in the API and it maps to the traceId in the trace data in Application Performance Monitoring. ' type: string rootSpanDurationInMs: description: 'Time taken for the root span operation to complete in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer rootSpanOperationName: description: 'Root span name associated with the trace. This is the flow start operation name. Null is displayed if the root span is not yet completed. ' type: string rootSpanServiceName: description: 'Service associated with the trace. ' type: string serviceSummaries: description: 'A summary of the spans by service. ' items: $ref: '#/components/schemas/TraceServiceSummary' type: array sourceName: description: 'Source of trace (traces, syn_traces). ' enum: - TRACES - SYN_TRACES type: string spanCount: description: 'The number of spans that have been processed by the system for the trace. Note that there could be additional spans that have not been processed or reported yet if the trace is still in progress. ' format: int32 maximum: 604800 minimum: 0 type: integer spanSummary: $ref: '#/components/schemas/TraceSpanSummary' spans: description: 'An array of spans in the trace. ' items: $ref: '#/components/schemas/Span' type: array timeEarliestSpanStarted: description: 'Start time of the earliest span in the span collection. ' format: date-time type: string timeLatestSpanEnded: description: 'End time of the span that most recently ended in the span collection. ' format: date-time type: string timeRootSpanEnded: description: 'End time of the root span for the span collection. ' format: date-time type: string timeRootSpanStarted: description: 'Start time of the root span for the span collection. ' format: date-time type: string traceDurationInMs: description: 'Time between the start of the earliest span and the end of the most recent span in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer traceErrorCode: description: 'Error code of the trace. ' type: string traceErrorType: description: 'Error type of the trace. ' type: string traceStatus: description: 'The status of the trace. The trace statuses are defined as follows: complete - a root span has been recorded, but there is no information on the errors. success - a complete root span is recorded there is a successful error type and error code - HTTP 200. incomplete - the root span has not yet been received. error - the root span returned with an error. There may or may not be an associated error code or error type. ' type: string required: - key - spans type: object TagMetadata: description: 'Definition of the tag metadata. ' properties: tagType: description: 'Type associated with the tag key. ' enum: - STRING - NUMERIC type: string tagUnit: description: 'Unit associated with the tag key. If unit is not specified, it defaults to NONE. ' enum: - EPOCH_TIME_MS - BYTES - COUNT - DURATION_MS - TRACE_STATUS - PERCENTAGE - NONE type: string type: object SpanLogCollection: description: 'Definition of span log collection object. ' properties: eventName: description: 'Name of the event for which the log is created. ' type: string spanLogs: description: 'List of logs associated with the span at the given timestamp. ' items: $ref: '#/components/schemas/SpanLog' type: array timeCreated: description: 'Timestamp at which the log is created. ' format: date-time type: string type: object SpanSnapshot: description: 'Definition of a span snapshot object. ' properties: children: description: 'An array of child span snapshots. ' items: $ref: '#/components/schemas/SpanSnapshot' type: array key: description: 'Unique identifier (spanId) for the trace span. ' type: string spanName: description: 'Span name associated with the trace. ' type: string spanSnapshotDetails: description: 'Span snapshots properties. ' items: $ref: '#/components/schemas/SnapshotDetail' type: array threadSnapshots: description: 'Thread snapshots. ' items: $ref: '#/components/schemas/ThreadSnapshot' type: array timeEnded: description: 'End time of the span. ' format: date-time type: string timeStarted: description: 'Start time of the span. ' format: date-time type: string required: - key - timeStarted - timeEnded type: object responses: DefaultError: description: 'Unknown Error ' headers: opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' x-anchors: x-common-splat-settings: - allowCrossTenancy: true mode: automated nbacMode: '##NBAC_MODE##' - throttling: enableRegionalThrottling: true mode: default perTenantLimit: rpsLimit: 300 perUserLimit: rpmLimit: 1200 rpsLimit: 100 x-downstream-splat-expressions: - downstream.getOr404('APM-DIS','GetApmDomainInfoCompartmentId',request.parameter.apmDomainId) x-headers: opc-next-page: description: 'For pagination of a list of items. When paging through a list, if this header appears in the response, then a partial list might have been returned. Include this value as the page parameter for the subsequent GET request to get the next batch of items. ' type: string opc-request-id: description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID. ' type: string opc-total-items: description: 'The total number of items that match the query. ' type: integer x-nbac: - '##NBAC_MODE##' x-properties: errorSpanCount: description: "The number of spans with errors that have been processed by the system for the trace.\nNote that the number of spans with errors will be less than or equal to the total number of spans in the trace. \n" format: int32 maximum: 604800 minimum: 0 type: integer isFault: description: 'Boolean flag that indicates whether the trace has an error. ' type: boolean key: description: 'Unique identifier (traceId) for the trace that represents the span set. Note that this field is defined as traceKey in the API and it maps to the traceId in the trace data in Application Performance Monitoring. ' type: string rootSpanDurationInMs: description: 'Time taken for the root span operation to complete in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer rootSpanOperationName: description: 'Root span name associated with the trace. This is the flow start operation name. Null is displayed if the root span is not yet completed. ' type: string rootSpanServiceName: description: 'Service associated with the trace. ' type: string serviceSummaries: description: 'A summary of the spans by service. ' items: $ref: '#/components/schemas/TraceServiceSummary' type: array spanCount: description: 'The number of spans that have been processed by the system for the trace. Note that there could be additional spans that have not been processed or reported yet if the trace is still in progress. ' format: int32 maximum: 604800 minimum: 0 type: integer timeEarliestSpanStarted: description: 'Start time of the earliest span in the span collection. ' format: date-time type: string timeLatestSpanEnded: description: 'End time of the span that most recently ended in the span collection. ' format: date-time type: string timeRootSpanEnded: description: 'End time of the root span for the span collection. ' format: date-time type: string timeRootSpanStarted: description: 'Start time of the root span for the span collection. ' format: date-time type: string traceDurationInMs: description: 'Time between the start of the earliest span and the end of the most recent span in milliseconds. ' format: int32 maximum: 604800 minimum: 0 type: integer traceErrorCode: description: 'Error code of the trace. ' type: string traceErrorType: description: 'Error type of the trace. ' type: string traceSourceName: description: 'Source of trace (traces, syn_traces). ' enum: - TRACES - SYN_TRACES type: string traceStatus: description: 'The status of the trace. The trace statuses are defined as follows: complete - a root span has been recorded, but there is no information on the errors. success - a complete root span is recorded there is a successful error type and error code - HTTP 200. incomplete - the root span has not yet been received. error - the root span returned with an error. There may or may not be an associated error code or error type. ' type: string x-oracle-package: com.oracle.apm.service.dataserver