DigitalOcean API (unofficial showcase)
GET/v2/insights/query/{region}/traces/{trace_id}

Retrieve an existing trace

To retrieve a single trace and all of its spans, send a GET request to /v2/insights/query/{region}/traces/{trace_id}. Only spans that started within the lookup window are returned. The window defaults to the last 7 days and can be narrowed with the from and to query parameters; it must not exceed 7 days, and from must not be after to. Spans are returned ordered by start time. At most 10,000 spans are returned; truncated is true when the trace has more. A trace ID with no spans in the window returns 404, as do malformed or uppercase trace IDs. A trace is only resolvable in the region that ingested it; querying another region also returns 404. Supported regions are ams2, ams3, atl1, blr1, fra1, lon1, mem1, nyc1, nyc2, nyc3, ric1, sfo1, sfo2, sfo3, sgp1, syd1, and tor1. Requests time out after 60 seconds. Errors produced by the traces service (400, and 404 when no trace is found) have a text/plain body containing a short message. Authentication and authorization errors (401, 403), rate limiting (429), and routing errors (for example, 404 for an unknown region) come from the API gateway and use the standard JSON error object with id and message. 403 is also returned for accounts that are in a trial or not in good standing. If the regional traces backend cannot be reached, the response is 502 with a text/plain body. JSON field names are camelCase (traceId, spanId, startTime, endTime, durationNs, serviceName, statusCode, parentSpanId).

4 parameters
regionstringrequired
The datacenter region slug for the query.
trace_idstringrequired
The OpenTelemetry trace ID to retrieve, as 32 lowercase hexadecimal characters. IDs are matched exactly; an ID with no spans in the lookup window returns `404`. Malformed or uppercase IDs are not rejected with `400`; they also return `404`.
fromstringoptional
Start of the trace lookup window. Accepts a relative time (`now`, a bare duration such as `24h` to look back from now, or `now-2h`) or an absolute time (RFC3339, or a Unix epoch integer in seconds, milliseconds, microseconds, or nanoseconds). Defaults to 7 days before now.
tostringoptional
End of the trace lookup window, in the same formats as `from`. Defaults to now.

9 status codes
200The trace and its spans.
traceIdstringoptional
The trace identifier.
spansarray<object>optional
Every span in the trace, ordered by start time.
truncatedbooleanoptional
True when the trace has more spans than were returned in this response. Omitted when false.
400The request was rejected by the traces service, for example because the body is malformed, a field is out of range, or the time range is invalid. The body is a short plain-text message.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403The authenticated principal does not have permission to perform this action on the requested resource.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404The trace or region was not found. When the traces service finds no matching trace, the body is the plain-text message `trace not found`. When the region is unknown or does not serve traces, the API gateway returns a JSON error object.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
502The regional traces backend could not be reached. The body is a short plain-text message.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: The request was rejected by the traces service, for example because the body is malformed, a field is out of range, or the time range is invalid. The body is a short plain-text message. A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: The authenticated principal does not have permission to perform this action on the requested resource. A 404 is returned: The trace or region was not found. When the traces service finds no matching trace, the body is the plain-text message trace not found. When the region is unknown or does not serve traces, the API gateway returns a JSON error object. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. A 502 is returned: The regional traces backend could not be reached. The body is a short plain-text message. Any other status is an error: There was an unexpected error.