Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

SearchCertificates

Retrieves a list of certificates matching search criteria. You can filter certificates by X.509 attributes and ACM specific properties like certificate status, type and renewal eligibility. This operation provides more flexible filtering than ListCertificates by supporting complex filter statements.

Request Syntax


{
   "FilterStatement": { ... },
   "MaxResults": number,
   "NextToken": "string",
   "SortBy": "string",
   "SortOrder": "string"
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

FilterStatement

A filter statement that defines the search criteria. You can combine multiple filters using AND, OR, and NOT logical operators to create complex queries.

Type: CertificateFilterStatement object

Note: This object is a Union. Only one member of this object can be specified or returned.

Required: No

MaxResults

The maximum number of results to return in the response. Default is 100.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 500.

Required: No

NextToken

Use this parameter only when paginating results and only in a subsequent request after you receive a response with truncated results. Set it to the value of NextToken from the response you just received.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 10000.

Pattern: [\u0009\u000A\u000D\u0020-\u00FF]*

Required: No

SortBy

Specifies the field to sort results by. Valid values are CREATED_AT, NOT_AFTER, STATUS, RENEWAL_STATUS, EXPORTED, IN_USE, NOT_BEFORE, KEY_ALGORITHM, TYPE, CERTIFICATE_ARN, COMMON_NAME, REVOKED_AT, RENEWAL_ELIGIBILITY, ISSUED_AT, MANAGED_BY, EXPORT_OPTION, VALIDATION_METHOD, and IMPORTED_AT.

Type: String

Required: No

SortOrder

Specifies the order of sorted results. Valid values are ASCENDING or DESCENDING.

Type: String

Valid Values: ASCENDING | DESCENDING

Required: No

Response Syntax


{
   "NextToken": "string",
   "Results": [ 
      { 
         "CertificateArn": "string",
         "CertificateMetadata": { ... },
         "X509Attributes": { 
            "ExtendedKeyUsages": [ "string" ],
            "Issuer": { 
               "CommonName": "string",
               "Country": "string",
               "CustomAttributes": [ 
                  { 
                     "ObjectIdentifier": "string",
                     "Value": "string"
                  }
               ],
               "DistinguishedNameQualifier": "string",
               "DomainComponents": [ "string" ],
               "GenerationQualifier": "string",
               "GivenName": "string",
               "Initials": "string",
               "Locality": "string",
               "Organization": "string",
               "OrganizationalUnit": "string",
               "Pseudonym": "string",
               "SerialNumber": "string",
               "State": "string",
               "Surname": "string",
               "Title": "string"
            },
            "KeyAlgorithm": "string",
            "KeyUsages": [ "string" ],
            "NotAfter": number,
            "NotBefore": number,
            "SerialNumber": "string",
            "Subject": { 
               "CommonName": "string",
               "Country": "string",
               "CustomAttributes": [ 
                  { 
                     "ObjectIdentifier": "string",
                     "Value": "string"
                  }
               ],
               "DistinguishedNameQualifier": "string",
               "DomainComponents": [ "string" ],
               "GenerationQualifier": "string",
               "GivenName": "string",
               "Initials": "string",
               "Locality": "string",
               "Organization": "string",
               "OrganizationalUnit": "string",
               "Pseudonym": "string",
               "SerialNumber": "string",
               "State": "string",
               "Surname": "string",
               "Title": "string"
            },
            "SubjectAlternativeNames": [ 
               { ... }
            ]
         }
      }
   ]
}

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

When the list is truncated, this value is present and contains the value to use for the NextToken parameter in a subsequent pagination request.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 10000.

Pattern: [\u0009\u000A\u000D\u0020-\u00FF]*

Results

A list of certificate search results containing certificate ARNs, X.509 attributes, and ACM metadata.

Type: Array of CertificateSearchResult objects

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

You do not have access required to perform this action.

HTTP Status Code: 400

ThrottlingException

The request was denied because it exceeded a quota.

throttlingReasons: One or more reasons why the request was throttled.

HTTP Status Code: 400

ValidationException

The supplied input failed to satisfy constraints of an AWS service.

HTTP Status Code: 400

Examples

Search Certificates

The following example searches for exported, issued certificates that are either imported or private, excluding a specific domain name.

Sample Request



POST / HTTP/1.1
Host: acm.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 450
X-Amz-Target: CertificateManager.SearchCertificates
X-Amz-Date: 20260213T034622Z
User-Agent: aws-cli/2.0.0 Python/3.9.0 Linux/5.10.0
Content-Type: application/x-amz-json-1.1
Authorization: AWS4-HMAC-SHA256 Credential=key_ID/20260213/us-east-1/acm/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=example...

{
    "FilterStatement": {
        "And": [
            {
                "Filter": {
                    "AcmCertificateMetadataFilter": {
                        "Status": "ISSUED"
                    }
                }
            },
            {
                "Or": [
                    {
                        "Filter": {
                            "AcmCertificateMetadataFilter": {
                                "Type": "IMPORTED"
                            }
                        }
                    },
                    {
                        "Filter": {
                            "AcmCertificateMetadataFilter": {
                                "Type": "PRIVATE"
                            }
                        }
                    }
                ]
            },
            {
                "Not": {
                    "Filter": {
                        "X509AttributeFilter": {
                            "SubjectAlternativeName": {
                                "DnsName": {
                                    "Value": "test.com",
                                    "ComparisonOperator": "CONTAINS"
                                }
                            }
                        }
                    }
                }
            },
            {
                "Filter": {
                    "AcmCertificateMetadataFilter": {
                        "Exported": true
                    }
                }
            }
        ]
    },
    "MaxResults": 10,
    "SortBy": "CREATED_AT",
    "SortOrder": "DESCENDING"
}

Sample Response



HTTP/1.1 200 OK
x-amzn-RequestId: 12345678-1234-1234-1234-123456789012
Content-Type: application/x-amz-json-1.1
Content-Length: 500
Date: Fri, 13 Feb 2026 03:46:22 GMT
Connection: Keep-alive

{
    "Results": [
        {
            "CertificateArn": "arn:aws:acm:region:account:certificate/12345678-1234-1234-1234-123456789012",
            "X509Attributes": {
                "Issuer": {
                    "CommonName": "Example CA",
                    "Country": "US",
                    "Organization": "Example Corp"
                },
                "Subject": {
                    "CommonName": "www.example.com"
                },
                "ExtendedKeyUsages": [
                    "TLS_WEB_SERVER_AUTHENTICATION"
                ],
                "KeyAlgorithm": "RSA_2048",
                "KeyUsages": [
                    "DIGITAL_SIGNATURE"
                ],
                "SerialNumber": "e5:87:ef:34:7a:4a:0f:de",
                "NotAfter": "2028-12-31T23:59:59+00:00",
                "NotBefore": "2008-01-01T00:00:01+00:00"
            },
            "CertificateMetadata": {
                "AcmCertificateMetadata": {
                    "CreatedAt": "2020-06-15T18:47:09+00:00",
                    "Exported": true,
                    "ImportedAt": "2020-06-15T18:47:09+00:00",
                    "InUse": true,
                    "RenewalEligibility": "INELIGIBLE",
                    "Status": "ISSUED",
                    "Type": "IMPORTED",
                    "ExportOption": "DISABLED"
                }
            }
        }
    ],
    "NextToken": "nextToken"
}