# Using the Amazon Quick Sight API
Following, you can find out how to get started using the Amazon Quick Sight API.
**Topics**
+ [Making API Requests](qs-api-making-api-requests.md)
+ [Amazon Resource Names (ARNs) in Amazon Quick Sight](qs-arns.md)
+ [Permissions for Amazon Quick Sight Resources](qs-api-permissions.md)
+ [Amazon Quick Sight API Errors](qs-api-errors.md)
# Making API Requests
We provide an API for Amazon Quick Sight, and also Amazon SDKs that enable you to access Amazon Quick Sight from your preferred programming language. Using Amazon Quick Sight, you can manage some aspects of your deployment by using the Amazon SDKs.
To monitor the calls made to the Amazon Quick Sight API for your account, you can use AWS CloudTrail. CloudTrail can monitor calls made by the AWS Management Console, command line tools, and other services. For more information, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
**Topics**
+ [Prerequisite Knowledge](#qs-api-required-knowledge)
+ [Available API Operations for Amazon Quick Sight](#qs-api-using-libraries)
## Prerequisite Knowledge
If you plan to access Amazon Quick Sight through an API, you should be familiar with the following:
+ JSON
+ Web services
+ HTTP requests
+ One or more programming languages, such as JavaScript, Java, Python, or C\$1.
We recommend visiting the AWS [Getting Started Resource Center](https://aws.amazon.com//getting-started/tools-sdks/) for a tour of what Amazon SDKs and toolkits have to offer.
Although you can use a terminal and your favorite text editor, you might benefit from the more visual UI experience you get in an integrated development environment (IDE). We provide a list of IDEs in the *AWS Getting Started Resource Center* in the [IDE and IDE Toolkits](https://aws.amazon.com//getting-started/tools-sdks/#IDE_and_IDE_Toolkits) section. This site provides AWS toolkits that you can download for your preferred IDE. Some IDEs also offer tutorials to help you learn more about programming languages.
## Available API Operations for Amazon Quick Sight
Amazon Quick Sight API operations provide:
+ User and group management
+ Data management (data sources, datasets, templates, and SPICE ingestion)
+ Dashboard and analysis management
+ Template management
+ Permissions management
+ Customization management
AWS provides libraries, sample code, tutorials, and other resources for software developers who prefer to build applications using language-specific API operations instead of submitting a request over HTTPS. These libraries provide basic functions that automatically take care of tasks such as cryptographically signing your requests, retrying requests, and handling error responses. These libraries help make it easier for you to get started.
For more information about downloading the Amazon SDKs, see [Amazon SDKs and Tools](https://aws.amazon.com/tools/). The following links are a sample of the language-specific API documentation available.
**AWS Command Line Interface**
+ [AWS CLI Quick Sight Command Reference](https://docs.aws.amazon.com//cli/latest/reference/quicksight/index.html)
+ [AWS CLI User Guide](https://docs.aws.amazon.com//cli/latest/userguide/)
+ [AWS CLI Command Reference](https://docs.aws.amazon.com//cli/latest/reference/)
**AWS SDK for .NET**
+ [Amazon.Quicksight](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSight.html)
+ [Amazon.Quicksight.Model](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/index.html?page=QuickSight/NQuickSightModel.html)
**AWS SDK for C\$1\$1**
+ [Aws::QuickSight::QuickSightClient Class Reference](https://sdk.amazonaws.com/cpp/api/LATEST/class_aws_1_1_quick_sight_1_1_quick_sight_client.html)
**AWS SDK for Go**
+ [quicksight](https://docs.aws.amazon.com/sdk-for-go/api/service/quicksight/)
**AWS SDK for Java**
+ [QuickSightClient](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/package-summary.html)
+ [QuickSightModel](https://docs.aws.amazon.com/sdk-for-java/latest/reference/index.html?com/amazonaws/services/quicksight/model/package-summary.html)
**AWS SDK for JavaScript**
+ [QuickSight](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/QuickSight.html)
**AWS SDK for PHP**
+ [QuickSightClient](https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-Aws.QuickSight.QuickSightClient.html)
**AWS SDK for Python (Boto3)**
+ [QuickSight](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/quicksight.html)
**AWS SDK for Ruby**
+ [Aws::QuickSight](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/QuickSight.html)
# Amazon Resource Names (ARNs) in Amazon Quick Sight
Amazon Resource Names (ARNs) uniquely identify AWS resources. An ARN identifies a resource unambiguously across all of AWS, for example in IAM policies, Amazon Relational Database Service (Amazon RDS) tags, and API calls. To retrieve the ARN of an Amazon Quick Sight resource, you can use the `Describe` operation on the relevant resource.
You can use this section to learn how ARNs work. The material here provides examples are geared specifically for Amazon Quick Sight.
**Topics**
+ [ARN Formats](qs-arn-format.md)
+ [Amazon Quick Sight Resource ARNs](qs-resource-arns.md)
# ARN Formats
ARNs are delimited by colons, and composed of *segments*, which are the parts separated by colons (`:`). The specific components and values used in the segments of an ARN depend on which AWS service the ARN is for. The following example shows how ARNs are constructed.
```
arn:partition:service:region:account-id:resource-id
arn:partition:service:region:account-id:resource-type/resource-id
arn:partition:service:region:account-id:resource-type:resource-id
```
These ARNs contain the following segments:
***`partition`*** – The partition that the resource is in. For standard AWS Regions, the partition is *aws*. If you have resources in other partitions, the partition is *aws-partitionname*. For example, the partition for resources in the China (Beijing) Region is `aws-cn`.
***`service`*** – The service namespace that identifies the AWS product. For example, `quicksight` identifies Amazon Quick Sight, `s3` identifies Amazon S3, `iam` identifies IAM, and so on.
***`region`*** – The AWS Region that the resource resides in. The ARNs for some resources don't require an AWS Region, so this component might be omitted in some cases, like in the case of S3. Amazon Quick Sight ARNs require an AWS Region.
***`account-id`*** – The ID of the AWS account that owns the resource. When you use the account number in an ARN or an API operation, you omit the hyphens (for example, 123456789012). The ARNs for some resources don't require an account number, so this component might be omitted. Amazon Quick Sight ARNs require an AWS account number. However, the account number and the AWS Region are omitted from S3 bucket ARNs, as shown following.
```
arn:aws:s3:::bucket_name
arn:aws:s3:::bucket_name/key_name
```
***`resource`* or *`resource-type`*** – The content of this part of the ARN varies by service. A resource identifier can be the name or ID of the resource (for example, `user/Bob` or `instance/i-1234567890abcdef0`) or a resource path. For example, some resource identifiers include a parent resource ( `sub-resource-type/parent-resource/sub-resource`) or a qualifier such as a version ( *resource-type*:*resource-name*:*qualifier*).
Some resource ARNs can include a path, a variable, or a wildcard.
You can use wildcard characters (`*` and `?`) within any ARN segment . An asterisk (`*`) represents any combination of zero or more characters, and a question mark (`?`) represents any single character. You can use multiple \$1 or ? characters in each segment. If you are using the ARN for permissions, avoid using `*` wildcards if possible, to limit access to only the required elements. Following are some examples of using paths, wildcards, and variables.
For the following example, we use an S3 ARN. You might use this when you give permissions to S3 in an IAM policy. This S3 ARN shows a path and file are specified.
**Note**
The term *key name* is used to describe what looks like a path and file after `bucketname/`. These are called key names because a bucket doesn't actually contain folder structures like those used in your computer's file system. Instead the slash (`/`) is a delimiter that helps to make the organization of the bucket more intuitive. In this case, the bucket name is `amzn-s3-demo-bucket`, and the key name is `developers/design_info.doc`.
```
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-2019-q4.json
```
If you want to identify all the objects in the bucket, you can use a wildcard to indicate that all key names (or paths and files) are included in the ARN, as follows.
```
arn:aws:s3:::amzn-s3-demo-bucket/*
```
You can use part of a key name plus the wildcard to identify all the objects that begin with a specific pattern. In this case, it resembles a folder name plus a wildcard, as shown following. However, this ARN also includes any "subfolders" inside of `my-data`.
```
arn:aws:s3:::amzn-s3-demo-bucket/my-data/*
```
You can specify a partial name by adding a wildcard. This one identifies any objects beginning with `my-data/sales-export*`.
```
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export*
```
In this case, specifying using this wildcard includes the objects with names like the following:
+ `my-data/sales-export-1.xlsx`
+ `my-data/sales-export-new.txt`
+ `my-data/sales-export-2019/file1.txt`
You can use wildcards of both types (asterisks and question marks) in combination or separately, as shown following.
```
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-2019-q?.*
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-20??-q?.*
```
Or, if you want to future-proof the ARN, you can replace the entire year with a wildcard, rather than just using wildcards for the last two digits.
```
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-????-q?.*
arn:aws:s3:::amzn-s3-demo-bucket/my-data/sales-export-*-q?.*
```
To read more about S3 ARNs, see [Specifying Resources in a Policy](https://docs.aws.amazon.com//AmazonS3/latest/dev/s3-arn-format.html) and [Object Key and Metadata](https://docs.aws.amazon.com//AmazonS3/latest/dev/UsingMetadata.html) in the *Amazon Simple Storage Service User Guide.*
# Amazon Quick Sight Resource ARNs
The following resource types are defined by Amazon Quick Sight: user, group, dashboard, and topic. These are used in Amazon Quick Sight API calls and as elements of IAM permission statements. To find up-to-date information for Amazon Quick Sight (service prefix: quicksight) resources, actions, and condition context keys for use in IAM permission policies, see [Actions, Resources, and Condition Keys for Amazon Quick Sight](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html) in the *IAM User Guide.*
| Resource Type | ARN Format | Condition Keys |
| --- | --- | --- |
| user | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:user/\$1\$1ResourceId\$1 | N/A |
| group | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:group/\$1\$1ResourceId\$1 | N/A |
| dashboard | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:dashboard/\$1\$1ResourceId\$1 | N/A |
| topic | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:topic/\$1\$1ResourceId\$1 | N/A |
| analysis | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:analysis/\$1\$1ResourceId\$1 | N/A |
| template | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:template/\$1\$1ResourceId\$1 | N/A |
| theme | arn:\$1\$1Partition\$1:quicksight:\$1\$1Region\$1:\$1\$1Account\$1:theme/\$1\$1ResourceId\$1 | N/A |
Resource ARNs are constructed from the segments that describe your resource. For example, a resource ARN for an analysis consists of the following segments.
```
arn::quicksight:::/
```
The segments are defined as follows:
+ *`partition`* – For example, `aws` or `aws-cn`.
+ *`aws-region`* – The AWS Region that contains the resource.
+ *`aws-account-id`* – The AWS account that contains the resource. This excludes the hyphens.
+ *`resource-type`* – The type of resource. For this example, this is `analyses`. For a dashboard, it is `dashboard`.
+ *`resource-id`* – The unique identifier for a specific resource.
The AWS Region, resource type, and resource ID are identified in the URL of the resource when you are using the Amazon Quick Sight console. For example, let's say this is the URL of the analysis you want an ARN for.
```
https://us-east-2.quicksight.aws.amazon.com/sn/analysis/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
The AWS Region is `us-east-2`. The resource-type is `analysis`. The resource ID in this URL is `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111`. If your account number is `111122223333`, then the ARN for this analysis is as follows.
```
arn:aws:quicksight:us-east-2:111122223333:analysis/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
To get your AWS account number, contact your system administrator.
**To get the dataset ID**
1. Navigate to the desired dataset page. You will be able to find the ID in the url. For example, `https://us-east-1.quicksight.aws.amazon.com/sn/data-sets/085fb6a4-c606-4949-b1ee-52cffadac462/`. The dataset ID in this instance would be `085fb6a4-c606-4949-b1ee-52cffadac462`.
1. Alternatively, you can use an API call to find the dataset ID.
`aws quicksight list-data-sets --aws-account-id your-aws-account-id`
You will see the dataset ID in the result, for example:
`"DataSetId": "a165d37b-c071-4648-8039-e4db5e5f7f08"`
**To get the data source ID**
+ Use an API call to find the data source ID.
`aws quicksight list-data-sources --aws-account-id your-aws-account-id`
You will see the data source ID in the result, for example:
`"DataSourceId": "1491fa60-1f19-4c0f-9f56-c72413a24986"`
# Permissions for Amazon Quick Sight Resources
If you're not sure what the necessary permission is, you can attempt to make a call. The client then tells you what the missing permission is. You can use asterisk (`*`) in the Resource field of your permission policy instead of specifying explicit resources. However, we highly recommend that you restrict each permission as much as possible. You can restrict user access by specifying or excluding resources in the policy, using their Amazon Quick Sight ARN. To retrieve the ARN of an Amazon Quick Sight resource, use the `Describe` operation on the relevant resource.
Before you can call the Amazon Quick Sight API operations, you need the `quicksight:operation-name` permission in a policy attached to your IAM identity. For example, to call `list-users`, you need the permission `quicksight:ListUsers`. The same pattern applies to all operations. If you attempt to make the call you don't have permissions to call, the resulting error shows you what the missing permission is. We highly recommend that you restrict each permission as much as possible.
You can add conditions in IAM to further restrict access to an API in some scenarios. For example, when you add `User1` to `Group1`, the main resource is `Group1`. You can allow or deny access to certain groups. Or you can also edit the Amazon Quick Sight IAM key `quicksight:UserName` to add a condition to allow or prevent certain users from being added to that group.
For more information, see the following:
+ [Actions, Resources, and Condition Keys](https://docs.aws.amazon.com//IAM/latest/UserGuide/list_amazonquicksight.html)
+ [IAM JSON Policy Elements](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_elements.html)
To see the most up-to-date list of Amazon Quick Sight actions, see [Actions Defined by Amazon Quick Sight](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonquicksight.html#amazonquicksight-actions-as-permissions) in the *IAM User Guide*.
## Best Practices
Amazon Quick Sight allows you to share analyses, dashboards, templates, and themes with up to 100 principals. A *principal* can be one of the following:
+ The Amazon Resource Name (ARN) of an Amazon Quick Sight user or group associated with a data source or dataset. (This is common.)
+ The ARN of an Amazon Quick Sight user, group, or namespace associated with an analysis, dashboard, template, or theme. (This is common.)
+ The ARN of an AWS account root: This is an IAM ARN rather than a Quick Sight ARN. Use this option only to share resources (templates) across AWS accounts. (This is less common.)
If you want to share these resources with more principals, consider assigning resource permissions at the group or namespace level. For example, if you add users into a group and share a resource to the group, the group counts as one principal, even though it is shared to everyone in the group.
# Amazon Quick Sight API Errors
Amazon Quick Sight has two types of error codes:
+ **Client errors** – These errors are usually caused by something the client did. An example is specifying an incorrect or invalid parameter in the request, or using an action or resource for a user that doesn't have permission to use the action or resource. These errors are accompanied by a 400-series HTTP response code.
+ **Server errors** – These errors are usually caused by an AWS server-side issue. These errors are accompanied by a 500-series HTTP response code.
**Topics**
+ [Common Client Errors](#qs-api-errors-client)
+ [Client Errors](#qs-api-errors-table-client)
+ [Server Errors](#qs-api-errors-table-server)
## Common Client Errors
Following, you can find a list of the common client errors that all actions can return.
| Error Code | Description |
| --- | --- |
| AuthFailure | The provided credentials could not be validated. You might not be authorized to carry out the request. Ensure that your account is authorized to use the Amazon Quick Sight service, that your credit card details are correct, and that you are using the correct access keys. |
| Blocked | Your account is currently blocked. Contact [Support](https://support.aws.amazon.com/#/contacts/aws-account-verification) if you have questions. |
| DryRunOperation | The user has the required permissions, so the request would have succeeded, but the DryRun parameter was used. |
| IdempotentParameterMismatch | The request uses the same client token as a previous, but non-identical request. Do not reuse a client token with different requests, unless the requests are identical. |
| IncompleteSignature | The request signature does not conform to AWS standards. |
| InvalidAction | The action or operation requested is not valid. Verify that the action is typed correctly. |
| InvalidCharacter | A specified character is invalid. |
| InvalidClientTokenId | The X.509 certificate or AWS access key ID provided does not exist in our records. |
| InvalidPaginationToken | The specified pagination token is not valid or is expired. |
| InvalidParameter | A parameter specified in a request is not valid, is unsupported, or cannot be used. The returned message provides an explanation of the error value. |
| InvalidParameterCombination | Indicates an incorrect combination of parameters, or a missing parameter. |
| InvalidParameterValue | A value specified in a parameter is not valid, is unsupported, or cannot be used. Ensure that you specify a resource by using its full ID. The returned message provides an explanation of the error value. |
| InvalidQueryParameter | The AWS query string is malformed or does not adhere to AWS standards. |
| MalformedQueryString | The query string contains a syntax error. |
| MissingAction | The request is missing an action or a required parameter. |
| MissingAuthenticationToken | The request must contain either a valid (registered) AWS access key ID or X.509 certificate. |
| MissingParameter | The request is missing a required parameter. Ensure that you have supplied all the required parameters for the request; for example, the resource ID. |
| OptInRequired | You are not authorized to use the requested service. Ensure that you have subscribed to the service you are trying to use. If you are new to AWS, your account might take some time to be activated while your credit card details are being verified. |
| PendingVerification | Your account is pending verification. Until the verification process is complete, you might not be able to carry out requests with this account. If you have questions, contact [AWS Support](https://console.aws.amazon.com/support/home#/). |
| RequestExpired | The request reached the service more than 15 minutes after the date stamp on the request or the request expiration date (such as for presigned URLs). Or the date stamp on the request is more than 15 minutes in the future. If you're using temporary security credentials, this error can also occur if the credentials have expired. For more information, see [Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp.html) in the IAM User Guide. |
| UnauthorizedOperation | You are not authorized to perform this operation. Check your IAM policies, and ensure that you are using the correct access keys. |
| UnknownParameter | An unknown or unrecognized parameter was supplied. Requests that could cause this error include supplying a misspelled parameter or a parameter that is not supported for the specified API version. |
| UnsupportedInstanceAttribute | The specified attribute cannot be modified. |
| UnsupportedOperation | The specified request includes an unsupported operation. The returned message provides details of the unsupported operation. |
| UnsupportedProtocol | The protocol you used is unsupported. |
| ValidationError | The input fails to satisfy the constraints specified by an AWS service. |
## Client Errors
Following, you can find a list of client errors that are specific to Amazon Quick Sight API operations.
| Error Code | Description |
| --- | --- |
| AccessDeniedException | You don't have access to this. The provided credentials could not be validated. You might not be authorized to carry out the request. Ensure that your account is authorized to use the Amazon Quick Sight service, that your policies have the correct permissions, and that you are using the correct access keys. |
| DomainNotWhiteListedException | The domain specified is not on the allowlist. All domains for embedded dashboards must be added to the approved list by an Amazon Quick Sight admin. |
| IdentityTypeNotSupportedException | The identity type specified is not supported. Supported identity types include: IAM and QUICKSIGHT. |
| InvalidNextTokenException | The NextToken value isn't valid. |
| InvalidParameterValueException | One or more parameters don't have a valid value. |
| PreconditionNotMetException | One or more preconditions aren't met. |
| QuickSightUserNotFoundException | The user is not found. This could happen in any operation that requires finding a user based on the provided user name, such as DeleteUser, DescribeUser, and so on. |
| ResourceExistsException | The resource specified doesn't exist. |
| ResourceNotFoundException | One or more resources couldn't be found. |
| SessionLifetimeInMinutesInvalidException | The number of minutes specified for the lifetime of a session is invalid. The session lifetime must be between 15 and 600 minutes. |
| ThrottlingException | Access is throttled. |
| UnsupportedUserEditionException | Indicates that you are calling an operation on an Amazon Quick Sight subscription where the edition does not include support for that operation. Amazon Quick Sight currently has Standard Edition and Enterprise Edition. Not every operation and capability is available in every edition. |
### Common Causes of Client Errors
There are a number of reasons that you might encounter an error while performing a request. Some errors can be prevented or easily solved by following these guidelines:
+ **Specify the AWS account ID and Namespace** – The relevant AWS account ID must be provided with each request. The Namespace must be set to `default`.
+ **Allow for eventual consistency** – Some errors are caused because a previous request has not yet propagated thorough the system.
+ **Use a sleep interval between request rates** – Amazon Quick Sight API requests are throttled to help maintain the performance of the service. If your requests have been throttled, you get an error.
+ **Use the full ID of the resource** – When specifying a resource, ensure that you use its full ID, and not its user-supplied name or description.
+ **Check your services** – Ensure that you have signed up for all the services you are attempting to use. You can check which services you're signed up for by going to the **My Account** section of the [AWS home page](http://aws.amazon.com).
+ **Check your permissions** – Ensure that you have the required permissions to carry out the request.
+ **Check your VPC** – Some resources cannot be shared between virtual private clouds (VPCs), for example security groups.
+ **Check your credentials** – Ensure that you provide your access keys when you are making requests and that you have entered the credentials correctly. Also, if you have more than one account, ensure that you are using the correct credentials for a particular account. If the provided credentials are incorrect, you might get the following error: `Client.AuthFailure`.
## Server Errors
Following, you can find a list of errors that can be returned by the server.
| Error Code | Description |
| --- | --- |
| BatchClientRequestTokensNotDistinctException – | The batch client request tokens are not unique. |
| EmptyBatchRequestException | The batch request was empty. |
| InternalFailureException | An internal failure occurred. |
| InternalServiceError | There was an internal error from the service. |
| InvalidBatchClientRequestTokenException | The AWS request token for this client batch request is invalid. |
| InvalidParameterException | One or more parameters has an invalid value. |
| LimitExceededException | A limit is exceeded. |
| ResourceUnavailableException | This resource is currently unavailable. |
| TooManyEntriesInBatchRequestException | There are too many entries in this batch request. |