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

SearchAllRelatedItems

Searches for related items across all cases within a domain. This is a global search operation that returns related items from multiple cases, unlike the case-specific SearchRelatedItems API.

Use cases

Following are common uses cases for this API:

Find cases with similar issues across the domain. For example, search for all cases containing comments about "product defect" to identify patterns and existing solutions.
Locate all cases associated with specific contacts or orders. For example, find all cases linked to a contactArn to understand the complete customer journey.
Monitor SLA compliance across cases. For example, search for all cases with "Active" SLA status to prioritize remediation efforts.

Important things to know

This API returns case IDs, not complete case objects. To retrieve full case details, you must make additional calls to the GetCase API for each returned case ID.
This API searches across related items content, not case fields. Use the SearchCases API to search within case field values.

Endpoints: See Amazon Connect endpoints and quotas.

Request Syntax


POST /domains/domainId/related-items-search HTTP/1.1
Content-type: application/json

{
   "filters": [ 
      { ... }
   ],
   "maxResults": number,
   "nextToken": "string",
   "sorts": [ 
      { 
         "sortOrder": "string",
         "sortProperty": "string"
      }
   ]
}

URI Request Parameters

The request uses the following URI parameters.

domainId

The unique identifier of the Cases domain.

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

Required: Yes

Request Body

The request accepts the following data in JSON format.

filters

The list of types of related items and their parameters to use for filtering. The filters work as an OR condition: caller gets back related items that match any of the specified filter types.

Type: Array of RelatedItemTypeFilter objects

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: No

maxResults

The maximum number of results to return per page.

Type: Integer

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

Required: No

nextToken

The token for the next set of results. Use the value returned in the previous response in the next request to retrieve the next set of results.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 9000.

Required: No

sorts

A structured set of sort terms to specify the order in which related items should be returned. Supports sorting by association time or case ID. The sorts work in the order specified: first sort term takes precedence over subsequent terms.

Type: Array of SearchAllRelatedItemsSort objects

Array Members: Minimum number of 0 items. Maximum number of 2 items.

Required: No

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "nextToken": "string",
   "relatedItems": [ 
      { 
         "associationTime": "string",
         "caseId": "string",
         "content": { ... },
         "performedBy": { ... },
         "relatedItemId": "string",
         "tags": { 
            "string" : "string" 
         },
         "type": "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

The token for the next set of results. This is null if there are no more results to return.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 9000.

relatedItems

A list of items related to a case.

Type: Array of SearchAllRelatedItemsResponseItem objects

Array Members: Minimum number of 0 items. Maximum number of 25 items.

Errors

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

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 403

InternalServerException

We couldn't process your request because of an issue with the server. Try again later.

retryAfterSeconds: Advice to clients on when the call can be safely retried.

HTTP Status Code: 500

ResourceNotFoundException

We couldn't find the requested resource. Check that your resources exists and were created in the same AWS Region as your request, and try your request again.

resourceId: Unique identifier of the resource affected.
resourceType: Type of the resource affected.

HTTP Status Code: 404

ThrottlingException

The rate has been exceeded for this API. Please try again after a few minutes.

HTTP Status Code: 429

ValidationException

The request isn't valid. Check the syntax and try again.

HTTP Status Code: 400

Examples

Example request to search for all contact-type related items

The following example shows how to search for all contact-type related items across cases in a domain, filtering by a specific contactArn and sorting results by association time in descending order, then by case ID in descending order.


{
  "sorts": [
    {
      "sortProperty": "AssociationTime",
      "sortOrder": "Desc"
    },
    {
      "sortProperty": "CaseId",
      "sortOrder": "Desc"
    }
  ],
  "maxResults": 10,
  "filters": [
    {
      "contact": {
        "contactArn": "arn:aws:connect:us-west-2:[account-id]:instance/[instance-id]/contact/[contact-id]"
      }
    }
  ]
}

Example response for a successful search

The following example shows a successful search returning two contact-type related items from different cases, each with their associated case IDs, contact details, and metadata sorted by most recent association time first.


{
  "nextToken": null,
  "relatedItems": [
    {
      "associationTime": "2025-05-16T13:18:37.608074706Z",
      "caseId": "[case-id-1]",
      "content": {
        "contact": {
          "contactArn": "arn:aws:connect:us-west-2:[account-id]:instance/[instance-id]/contact/[contact-id]",
          "channel": "VOICE",
          "connectedToSystemTime": "2025-05-16T13:18:30.000000000Z"
        }
      },
      "performedBy": null,
      "relatedItemId": "[related-item-id-1]",
      "tags": {
        "Company": "AWS",
        "Team": "Connect"
      },
      "type": "Contact"
    },
    {
      "associationTime": "2025-05-16T13:18:19.270469991Z",
      "caseId": "[case-id-2]",
      "content": {
        "contact": {
          "contactArn": "arn:aws:connect:us-west-2:[account-id]:instance/[instance-id]/contact/[contact-id]",
          "channel": "CHAT",
          "connectedToSystemTime": "2025-05-16T13:18:15.000000000Z"
        }
      },
      "performedBy": null,
      "relatedItemId": "[related-item-id-2]",
      "tags": {},
      "type": "Contact"
    }
  ]
}