DigitalOcean API (unofficial showcase)
POST/v2/insights/query/{region}/traces/search

Search traces

To search traces in a region, send a POST request to /v2/insights/query/{region}/traces/search with a JSON body describing the time range, optional filter, ordering, and pagination. Each result is one trace, aggregated from all of its spans in the time range. A trace is included when at least one of its spans matches filter. The time range must not exceed 7 days (168h). pagination.limit defaults to 100 (also used when limit is 0) and must be between 0 and 1000. Results are ordered by started descending unless orderBy is set. JSON field names are camelCase (timeRange, orderBy, hasMore, traceId). Unknown request properties, invalid filters, and out-of-range values are rejected with 400. Each request searches a single region; there is no multi-region search. 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) 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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
regionstringrequired
The datacenter region slug for the query.
timeRangeobjectrequired
An inclusive query time window. Both bounds are required, `from` must not be after `to`, and the window must not exceed 7 days (`168h`).
filterobjectoptional
A node in a traces filter tree. Every node is the same flat object; `type` selects which other properties apply: - `condition` (default when `type` is omitted): compares `field` to `value` using `operator`. - `and` / `or`: combines the nodes in `expressions` (1 to 32 children). - `not`: negates the single node in `expressions` (exactly one child). - `text_search`: case-insensitive substring match of `query` against the span name, service name, and span status message. A trace matches when at least one of its spans in the time range matches the filter. Trees may be nested at most 16 levels deep and contain at most 256 nodes in total. Unknown properties are rejected.
orderByarray<object>optional
Sort clauses applied in order. Defaults to `started` descending.
paginationobjectoptional
Limits the size of a traces search result set. There is no cursor; use `pagination.hasMore` in the response to tell whether more traces matched, and narrow the time range or filter to see them.

9 status codes
200Traces search result.
dataarray<object>required
Matching traces. Empty when no traces match.
paginationobjectrequired
Pagination response.
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.