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

Search spans

To search spans in a region, send a POST request to /v2/insights/query/{region}/spans/search with a JSON body describing the time range, optional filter, ordering, and pagination. The time range must not exceed 7 days. pagination.limit defaults to 100 and must be between 1 and 1000. Results are ordered by startTime descending by default. Cursor-based pagination is not yet supported; pagination.hasMore indicates whether additional spans matched beyond the returned page.

  • 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. The window must not exceed 7 days.
filterobjectoptional
A boolean filter tree for spans search. Set `type` to select the node kind: `condition` compares a single field, `and`/`or`/`not` combine child expressions, and `text_search` matches a substring across the span name, service name, and status message.
orderByarray<object>optional
Sort clauses applied to the result set. Defaults to `startTime` descending when omitted.
paginationobjectoptional
Limits the number of spans returned.

8 status codes
200Spans search result.
dataarray<object>optional
Matching spans. Empty when no spans match.
paginationobjectoptional
Pagination metadata for a spans search response.
400There was an error parsing the request body.
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.
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 resource was not found.
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.
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: There was an error parsing the request body. 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 resource was not found. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.