ListInstances
Lists the details of the organization and account instances of IAM Identity Center that were created in or visible to the account calling this API.
Request Syntax
{
"MaxResults": number,
"NextToken": "string",
"RegionScope": "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.
- MaxResults
-
The maximum number of results to display for the instance.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 100.
Required: No
- NextToken
-
The pagination token for the list API. Initially the value is null. Use the output of previous API calls to make subsequent calls.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 2048.
Pattern:
[-a-zA-Z0-9+=/_]*Required: No
- RegionScope
-
Specifies which AWS Regions to list AWS IAM Identity Center instances from. Valid values:
-
CURRENT_REGION- Lists only the instances in the Region that you call this API from. -
ALL_REGIONS- Lists the instances that the caller owns or that are shared with the caller across all Regions.
If you don't specify a value, the default is
CURRENT_REGION.Type: String
Valid Values:
CURRENT_REGION | ALL_REGIONSRequired: No
-
Response Syntax
{
"Instances": [
{
"CreatedDate": number,
"IdentityStoreArn": "string",
"IdentityStoreId": "string",
"InstanceArn": "string",
"Name": "string",
"OwnerAccountId": "string",
"PrimaryRegion": "string",
"Regions": [
{
"AddedDate": number,
"IsPrimaryRegion": boolean,
"RegionName": "string",
"Status": "string"
}
],
"Status": "string",
"StatusReason": "string"
}
],
"NextToken": "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.
- Instances
-
Lists the IAM Identity Center instances that the caller has access to.
Type: Array of InstanceMetadata objects
Array Members: Minimum number of 0 items. Maximum number of 10 items.
- NextToken
-
The pagination token for the list API. Initially the value is null. Use the output of previous API calls to make subsequent calls.
Type: String
Length Constraints: Minimum length of 0. Maximum length of 2048.
Pattern:
[-a-zA-Z0-9+=/_]*
Errors
For information about the errors that are common to all actions, see Common Error Types.
- AccessDeniedException
-
You do not have sufficient access to perform this action.
- Reason
-
The reason for the access denied exception.
HTTP Status Code: 400
- InternalServerException
-
The request processing has failed because of an unknown error, exception, or failure with an internal server.
HTTP Status Code: 500
- ThrottlingException
-
Indicates that the principal has crossed the throttling limits of the API operations.
- Reason
-
The reason for the throttling exception.
HTTP Status Code: 400
- ValidationException
-
The request failed because it contains a syntax error.
- Reason
-
The reason for the validation exception.
HTTP Status Code: 400
Examples
List instances in the primary Region
This example lists the instances in us-east-1, the primary Region of the instance.
Sample Request
{
"RegionScope": "CURRENT_REGION"
}
Sample Response
{
"Instances": [
{
"CreatedDate": 1736373600,
"IdentityStoreArn": "arn:aws:identitystore::111122223333:identitystore/d-1234567890",
"IdentityStoreId": "d-1234567890",
"InstanceArn": "arn:aws:sso:::instance/ssoins-1234567890abcdef",
"OwnerAccountId": "111122223333",
"PrimaryRegion": "us-east-1",
"Regions": [
{
"AddedDate": 1736373600,
"IsPrimaryRegion": true,
"RegionName": "us-east-1",
"Status": "ACTIVE"
},
{
"AddedDate": 1739052000,
"IsPrimaryRegion": false,
"RegionName": "us-west-2",
"Status": "ACTIVE"
}
],
"Status": "ACTIVE"
}
]
}
List instances in a replicated Region
This example lists the instances in us-west-2, a Region that the instance is replicated to. The response is the same as in the primary Region.
Sample Request
{
"RegionScope": "CURRENT_REGION"
}
Sample Response
{
"Instances": [
{
"CreatedDate": 1736373600,
"IdentityStoreArn": "arn:aws:identitystore::111122223333:identitystore/d-1234567890",
"IdentityStoreId": "d-1234567890",
"InstanceArn": "arn:aws:sso:::instance/ssoins-1234567890abcdef",
"OwnerAccountId": "111122223333",
"PrimaryRegion": "us-east-1",
"Regions": [
{
"AddedDate": 1736373600,
"IsPrimaryRegion": true,
"RegionName": "us-east-1",
"Status": "ACTIVE"
},
{
"AddedDate": 1739052000,
"IsPrimaryRegion": false,
"RegionName": "us-west-2",
"Status": "ACTIVE"
}
],
"Status": "ACTIVE"
}
]
}
List instances in a Region with no instances
This example lists the instances in eu-west-1, where the instance isn't present, and returns an empty list.
Sample Request
{
"RegionScope": "CURRENT_REGION"
}
Sample Response
{
"Instances": []
}
List instances in all Regions
This example lists the instances in all Regions from eu-west-1, where the instance isn't present. The response is the same in every Region that is enabled for your account.
Sample Request
{
"RegionScope": "ALL_REGIONS"
}
Sample Response
{
"Instances": [
{
"CreatedDate": 1736373600,
"IdentityStoreArn": "arn:aws:identitystore::111122223333:identitystore/d-1234567890",
"IdentityStoreId": "d-1234567890",
"InstanceArn": "arn:aws:sso:::instance/ssoins-1234567890abcdef",
"OwnerAccountId": "111122223333",
"PrimaryRegion": "us-east-1",
"Regions": [
{
"AddedDate": 1736373600,
"IsPrimaryRegion": true,
"RegionName": "us-east-1",
"Status": "ACTIVE"
},
{
"AddedDate": 1739052000,
"IsPrimaryRegion": false,
"RegionName": "us-west-2",
"Status": "ACTIVE"
}
],
"Status": "ACTIVE"
}
]
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: