ListRetrievedTraces
Retrieves a list of traces for a given RetrievalToken
from the CloudWatch log group generated by Transaction Search. For information on what each trace returns, see BatchGetTraces.
This API does not initiate a retrieval process. To start a trace retrieval, use StartTraceRetrieval
, which generates the required RetrievalToken
.
When the RetrievalStatus
is not COMPLETE, the API will return an empty response. Retry the request once the retrieval has completed to access the full list of traces.
For cross-account observability, this API can retrieve traces from linked accounts when CloudWatch log is set as the destination across relevant accounts. For more details, see CloudWatch cross-account observability.
For retrieving data from X-Ray directly as opposed to the Transaction Search generated log group, see BatchGetTraces.
Request Syntax
POST /ListRetrievedTraces HTTP/1.1
Content-type: application/json
{
"NextToken": "string
",
"RetrievalToken": "string
",
"TraceFormat": "string
"
}
URI Request Parameters
The request does not use any URI parameters.
Request Body
The request accepts the following data in JSON format.
- NextToken
-
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
Type: String
Required: No
- RetrievalToken
-
Retrieval token.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 1020.
Required: Yes
- TraceFormat
-
Format of the requested traces.
Type: String
Valid Values:
XRAY | OTEL
Required: No
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"NextToken": "string",
"RetrievalStatus": "string",
"TraceFormat": "string",
"Traces": [
{
"Duration": number,
"Id": "string",
"Spans": [
{
"Document": "string",
"Id": "string"
}
]
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- NextToken
-
Specify the pagination token returned by a previous request to retrieve the next page of indexes.
Type: String
- RetrievalStatus
-
Status of the retrieval.
Type: String
Valid Values:
SCHEDULED | RUNNING | COMPLETE | FAILED | CANCELLED | TIMEOUT
- TraceFormat
-
Format of the requested traces.
Type: String
Valid Values:
XRAY | OTEL
- Traces
-
Full traces for the specified requests.
Type: Array of RetrievedTrace objects
Array Members: Minimum number of 0 items. Maximum number of 5 items.
Errors
For information about the errors that are common to all actions, see Common Errors.
- InvalidRequestException
-
The request is missing required parameters or has invalid parameters.
HTTP Status Code: 400
- ResourceNotFoundException
-
The resource was not found. Verify that the name or Amazon Resource Name (ARN) of the resource is correct.
HTTP Status Code: 404
- ThrottledException
-
The request exceeds the maximum number of requests per second.
HTTP Status Code: 429
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: