Braket

Client

class Braket.Client

A low-level client representing Braket

The Amazon Braket API Reference provides information about the operations and structures supported in Amazon Braket.

client = session.create_client('braket')

These are the available methods:

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters:

operation_name (string) – The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you’d normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").

Returns:

True if the operation can be paginated, False otherwise.

cancel_quantum_task(**kwargs)

Cancels the specified task.

See also: AWS API Documentation

Request Syntax

response = client.cancel_quantum_task(
    clientToken='string',
    quantumTaskArn='string'
)
Parameters:
  • clientToken (string) –

    [REQUIRED]

    The client token associated with the request.

    This field is autopopulated if not provided.

  • quantumTaskArn (string) –

    [REQUIRED]

    The ARN of the task to cancel.

Return type:

dict

Returns:

Response Syntax

{
    'cancellationStatus': 'CANCELLING'|'CANCELLED',
    'quantumTaskArn': 'string'
}

Response Structure

  • (dict) –

    • cancellationStatus (string) –

      The status of the cancellation request.

    • quantumTaskArn (string) –

      The ARN of the task.

Exceptions

create_quantum_task(**kwargs)

Creates a quantum task.

See also: AWS API Documentation

Request Syntax

response = client.create_quantum_task(
    action='string',
    clientToken='string',
    deviceArn='string',
    deviceParameters='string',
    outputS3Bucket='string',
    outputS3KeyPrefix='string',
    shots=123,
    tags={
        'string': 'string'
    }
)
Parameters:
  • action (string) –

    [REQUIRED]

    The action associated with the task.

  • clientToken (string) –

    [REQUIRED]

    The client token associated with the request.

    This field is autopopulated if not provided.

  • deviceArn (string) –

    [REQUIRED]

    The ARN of the device to run the task on.

  • deviceParameters (string) – The parameters for the device to run the task on.

  • outputS3Bucket (string) –

    [REQUIRED]

    The S3 bucket to store task result files in.

  • outputS3KeyPrefix (string) –

    [REQUIRED]

    The key prefix for the location in the S3 bucket to store task results in.

  • shots (integer) –

    [REQUIRED]

    The number of shots to use for the task.

  • tags (dict) –

    Tags to be added to the quantum task you’re creating.

    • (string) –

      • (string) –

Return type:

dict

Returns:

Response Syntax

{
    'quantumTaskArn': 'string'
}

Response Structure

  • (dict) –

    • quantumTaskArn (string) –

      The ARN of the task created by the request.

Exceptions

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters:
  • ClientMethod (string) – The client method to presign for

  • Params (dict) – The parameters normally passed to ClientMethod.

  • ExpiresIn (int) – The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)

  • HttpMethod (string) – The http method to use on the generated url. By default, the http method is whatever is used in the method’s model.

Returns:

The presigned url

get_device(**kwargs)

Retrieves the devices available in Amazon Braket.

See also: AWS API Documentation

Request Syntax

response = client.get_device(
    deviceArn='string'
)
Parameters:

deviceArn (string) –

[REQUIRED]

The ARN of the device to retrieve.

Return type:

dict

Returns:

Response Syntax

{
    'deviceArn': 'string',
    'deviceCapabilities': 'string',
    'deviceName': 'string',
    'deviceStatus': 'ONLINE'|'OFFLINE'|'RETIRED',
    'deviceType': 'QPU'|'SIMULATOR',
    'providerName': 'string'
}

Response Structure

  • (dict) –

    • deviceArn (string) –

      The ARN of the device.

    • deviceCapabilities (string) –

      Details about the capabilities of the device.

    • deviceName (string) –

      The name of the device.

    • deviceStatus (string) –

      The status of the device.

    • deviceType (string) –

      The type of the device.

    • providerName (string) –

      The name of the partner company for the device.

Exceptions

get_paginator(operation_name)

Create a paginator for an operation.

Parameters:

operation_name (string) – The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you’d normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").

Raises:

OperationNotPageableError – Raised if the operation is not pageable. You can use the client.can_paginate method to check if an operation is pageable.

Return type:

L{botocore.paginate.Paginator}

Returns:

A paginator object.

get_quantum_task(**kwargs)

Retrieves the specified quantum task.

See also: AWS API Documentation

Request Syntax

response = client.get_quantum_task(
    quantumTaskArn='string'
)
Parameters:

quantumTaskArn (string) –

[REQUIRED]

the ARN of the task to retrieve.

Return type:

dict

Returns:

Response Syntax

{
    'createdAt': datetime(2015, 1, 1),
    'deviceArn': 'string',
    'deviceParameters': 'string',
    'endedAt': datetime(2015, 1, 1),
    'failureReason': 'string',
    'outputS3Bucket': 'string',
    'outputS3Directory': 'string',
    'quantumTaskArn': 'string',
    'shots': 123,
    'status': 'CREATED'|'QUEUED'|'RUNNING'|'COMPLETED'|'FAILED'|'CANCELLING'|'CANCELLED',
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) –

    • createdAt (datetime) –

      The time at which the task was created.

    • deviceArn (string) –

      The ARN of the device the task was run on.

    • deviceParameters (string) –

      The parameters for the device on which the task ran.

    • endedAt (datetime) –

      The time at which the task ended.

    • failureReason (string) –

      The reason that a task failed.

    • outputS3Bucket (string) –

      The S3 bucket where task results are stored.

    • outputS3Directory (string) –

      The folder in the S3 bucket where task results are stored.

    • quantumTaskArn (string) –

      The ARN of the task.

    • shots (integer) –

      The number of shots used in the task.

    • status (string) –

      The status of the task.

    • tags (dict) –

      The tags that belong to this task.

      • (string) –

        • (string) –

Exceptions

get_waiter(waiter_name)

Returns an object that can wait for some condition.

Parameters:

waiter_name (str) – The name of the waiter to get. See the waiters section of the service docs for a list of available waiters.

Returns:

The specified waiter object.

Return type:

botocore.waiter.Waiter

list_tags_for_resource(**kwargs)

Shows the tags associated with this resource.

See also: AWS API Documentation

Request Syntax

response = client.list_tags_for_resource(
    resourceArn='string'
)
Parameters:

resourceArn (string) –

[REQUIRED]

Specify the resourceArn for the resource whose tags to display.

Return type:

dict

Returns:

Response Syntax

{
    'tags': {
        'string': 'string'
    }
}

Response Structure

  • (dict) –

    • tags (dict) –

      Displays the key, value pairs of tags associated with this resource.

      • (string) –

        • (string) –

Exceptions

search_devices(**kwargs)

Searches for devices using the specified filters.

See also: AWS API Documentation

Request Syntax

response = client.search_devices(
    filters=[
        {
            'name': 'string',
            'values': [
                'string',
            ]
        },
    ],
    maxResults=123,
    nextToken='string'
)
Parameters:
  • filters (list) –

    [REQUIRED]

    The filter values to use to search for a device.

    • (dict) –

      The filter to use for searching devices.

      • name (string) – [REQUIRED]

        The name to use to filter results.

      • values (list) – [REQUIRED]

        The values to use to filter results.

        • (string) –

  • maxResults (integer) – The maximum number of results to return in the response.

  • nextToken (string) – A token used for pagination of results returned in the response. Use the token returned from the previous request continue results where the previous request ended.

Return type:

dict

Returns:

Response Syntax

{
    'devices': [
        {
            'deviceArn': 'string',
            'deviceName': 'string',
            'deviceStatus': 'ONLINE'|'OFFLINE'|'RETIRED',
            'deviceType': 'QPU'|'SIMULATOR',
            'providerName': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) –

    • devices (list) –

      An array of DeviceSummary objects for devices that match the specified filter values.

      • (dict) –

        Includes information about the device.

        • deviceArn (string) –

          The ARN of the device.

        • deviceName (string) –

          The name of the device.

        • deviceStatus (string) –

          The status of the device.

        • deviceType (string) –

          The type of the device.

        • providerName (string) –

          The provider of the device.

    • nextToken (string) –

      A token used for pagination of results, or null if there are no additional results. Use the token value in a subsequent request to continue results where the previous request ended.

Exceptions

search_quantum_tasks(**kwargs)

Searches for tasks that match the specified filter values.

See also: AWS API Documentation

Request Syntax

response = client.search_quantum_tasks(
    filters=[
        {
            'name': 'string',
            'operator': 'LT'|'LTE'|'EQUAL'|'GT'|'GTE'|'BETWEEN',
            'values': [
                'string',
            ]
        },
    ],
    maxResults=123,
    nextToken='string'
)
Parameters:
  • filters (list) –

    [REQUIRED]

    Array of SearchQuantumTasksFilter objects.

    • (dict) –

      A filter to use to search for tasks.

      • name (string) – [REQUIRED]

        The name of the device used for the task.

      • operator (string) – [REQUIRED]

        An operator to use in the filter.

      • values (list) – [REQUIRED]

        The values to use for the filter.

        • (string) –

  • maxResults (integer) – Maximum number of results to return in the response.

  • nextToken (string) – A token used for pagination of results returned in the response. Use the token returned from the previous request continue results where the previous request ended.

Return type:

dict

Returns:

Response Syntax

{
    'nextToken': 'string',
    'quantumTasks': [
        {
            'createdAt': datetime(2015, 1, 1),
            'deviceArn': 'string',
            'endedAt': datetime(2015, 1, 1),
            'outputS3Bucket': 'string',
            'outputS3Directory': 'string',
            'quantumTaskArn': 'string',
            'shots': 123,
            'status': 'CREATED'|'QUEUED'|'RUNNING'|'COMPLETED'|'FAILED'|'CANCELLING'|'CANCELLED',
            'tags': {
                'string': 'string'
            }
        },
    ]
}

Response Structure

  • (dict) –

    • nextToken (string) –

      A token used for pagination of results, or null if there are no additional results. Use the token value in a subsequent request to continue results where the previous request ended.

    • quantumTasks (list) –

      An array of QuantumTaskSummary objects for tasks that match the specified filters.

      • (dict) –

        Includes information about a quantum task.

        • createdAt (datetime) –

          The time at which the task was created.

        • deviceArn (string) –

          The ARN of the device the task ran on.

        • endedAt (datetime) –

          The time at which the task finished.

        • outputS3Bucket (string) –

          The S3 bucket where the task result file is stored..

        • outputS3Directory (string) –

          The folder in the S3 bucket where the task result file is stored.

        • quantumTaskArn (string) –

          The ARN of the task.

        • shots (integer) –

          The shots used for the task.

        • status (string) –

          The status of the task.

        • tags (dict) –

          Displays the key, value pairs of tags associated with this quantum task.

          • (string) –

            • (string) –

Exceptions

tag_resource(**kwargs)

Add a tag to the specified resource.

See also: AWS API Documentation

Request Syntax

response = client.tag_resource(
    resourceArn='string',
    tags={
        'string': 'string'
    }
)
Parameters:
  • resourceArn (string) –

    [REQUIRED]

    Specify the resourceArn of the resource to which a tag will be added.

  • tags (dict) –

    [REQUIRED]

    Specify the tags to add to the resource.

    • (string) –

      • (string) –

Return type:

dict

Returns:

Response Syntax

{}

Response Structure

  • (dict) –

Exceptions

untag_resource(**kwargs)

Remove tags from a resource.

See also: AWS API Documentation

Request Syntax

response = client.untag_resource(
    resourceArn='string',
    tagKeys=[
        'string',
    ]
)
Parameters:
  • resourceArn (string) –

    [REQUIRED]

    Specify the resourceArn for the resource from which to remove the tags.

  • tagKeys (list) –

    [REQUIRED]

    Specify the keys for the tags to remove from the resource.

    • (string) –

Return type:

dict

Returns:

Response Syntax

{}

Response Structure

  • (dict) –

Exceptions

Client Exceptions

Client exceptions are available on a client instance via the exceptions property. For more detailed instructions and examples on the exact usage of client exceptions, see the error handling user guide.

The available client exceptions are:

class Braket.Client.exceptions.AccessDeniedException

You do not have sufficient access to perform this action.

Example

try:
  ...
except client.exceptions.AccessDeniedException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    You do not have sufficient access to perform this action.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.ConflictException

An error occurred due to a conflict.

Example

try:
  ...
except client.exceptions.ConflictException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    An error occurred due to a conflict.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.DeviceOfflineException

The specified device is currently offline.

Example

try:
  ...
except client.exceptions.DeviceOfflineException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The specified device is currently offline.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.DeviceRetiredException

The specified device has been retired.

Example

try:
  ...
except client.exceptions.DeviceRetiredException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The specified device has been retired.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.InternalServiceException

The request processing has failed because of an unknown error, exception, or failure.

Example

try:
  ...
except client.exceptions.InternalServiceException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The request processing has failed because of an unknown error, exception, or failure.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.ResourceNotFoundException

The specified resource was not found.

Example

try:
  ...
except client.exceptions.ResourceNotFoundException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The specified resource was not found.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.ServiceQuotaExceededException

The request failed because a service quota is exceeded.

Example

try:
  ...
except client.exceptions.ServiceQuotaExceededException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The request failed because a service quota is exceeded.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.ThrottlingException

The throttling rate limit is met.

Example

try:
  ...
except client.exceptions.ThrottlingException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The throttling rate limit is met.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

class Braket.Client.exceptions.ValidationException

The input fails to satisfy the constraints specified by an AWS service.

Example

try:
  ...
except client.exceptions.ValidationException as e:
  print(e.response)
response

The parsed error response. All exceptions have a top level Error key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.

Syntax

{
    'message': 'string',
    'Error': {
        'Code': 'string',
        'Message': 'string'
    }
}

Structure

  • (dict) –

    The input fails to satisfy the constraints specified by an AWS service.

    • message (string) –

    • Error (dict) – Normalized access to common exception attributes.

      • Code (string) – An identifier specifying the exception type.

      • Message (string) – A descriptive message explaining why the exception occured.

Paginators

The available paginators are:

class Braket.Paginator.SearchDevices
paginator = client.get_paginator('search_devices')
paginate(**kwargs)

Creates an iterator that will paginate through responses from Braket.Client.search_devices().

See also: AWS API Documentation

Request Syntax

response_iterator = paginator.paginate(
    filters=[
        {
            'name': 'string',
            'values': [
                'string',
            ]
        },
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • filters (list) –

    [REQUIRED]

    The filter values to use to search for a device.

    • (dict) –

      The filter to use for searching devices.

      • name (string) – [REQUIRED]

        The name to use to filter results.

      • values (list) – [REQUIRED]

        The values to use to filter results.

        • (string) –

  • PaginationConfig (dict) –

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) –

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) –

      The size of each page.

    • StartingToken (string) –

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'devices': [
        {
            'deviceArn': 'string',
            'deviceName': 'string',
            'deviceStatus': 'ONLINE'|'OFFLINE'|'RETIRED',
            'deviceType': 'QPU'|'SIMULATOR',
            'providerName': 'string'
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) –

    • devices (list) –

      An array of DeviceSummary objects for devices that match the specified filter values.

      • (dict) –

        Includes information about the device.

        • deviceArn (string) –

          The ARN of the device.

        • deviceName (string) –

          The name of the device.

        • deviceStatus (string) –

          The status of the device.

        • deviceType (string) –

          The type of the device.

        • providerName (string) –

          The provider of the device.

    • NextToken (string) –

      A token to resume pagination.

class Braket.Paginator.SearchQuantumTasks
paginator = client.get_paginator('search_quantum_tasks')
paginate(**kwargs)

Creates an iterator that will paginate through responses from Braket.Client.search_quantum_tasks().

See also: AWS API Documentation

Request Syntax

response_iterator = paginator.paginate(
    filters=[
        {
            'name': 'string',
            'operator': 'LT'|'LTE'|'EQUAL'|'GT'|'GTE'|'BETWEEN',
            'values': [
                'string',
            ]
        },
    ],
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • filters (list) –

    [REQUIRED]

    Array of SearchQuantumTasksFilter objects.

    • (dict) –

      A filter to use to search for tasks.

      • name (string) – [REQUIRED]

        The name of the device used for the task.

      • operator (string) – [REQUIRED]

        An operator to use in the filter.

      • values (list) – [REQUIRED]

        The values to use for the filter.

        • (string) –

  • PaginationConfig (dict) –

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) –

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) –

      The size of each page.

    • StartingToken (string) –

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'quantumTasks': [
        {
            'createdAt': datetime(2015, 1, 1),
            'deviceArn': 'string',
            'endedAt': datetime(2015, 1, 1),
            'outputS3Bucket': 'string',
            'outputS3Directory': 'string',
            'quantumTaskArn': 'string',
            'shots': 123,
            'status': 'CREATED'|'QUEUED'|'RUNNING'|'COMPLETED'|'FAILED'|'CANCELLING'|'CANCELLED',
            'tags': {
                'string': 'string'
            }
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) –

    • quantumTasks (list) –

      An array of QuantumTaskSummary objects for tasks that match the specified filters.

      • (dict) –

        Includes information about a quantum task.

        • createdAt (datetime) –

          The time at which the task was created.

        • deviceArn (string) –

          The ARN of the device the task ran on.

        • endedAt (datetime) –

          The time at which the task finished.

        • outputS3Bucket (string) –

          The S3 bucket where the task result file is stored..

        • outputS3Directory (string) –

          The folder in the S3 bucket where the task result file is stored.

        • quantumTaskArn (string) –

          The ARN of the task.

        • shots (integer) –

          The shots used for the task.

        • status (string) –

          The status of the task.

        • tags (dict) –

          Displays the key, value pairs of tags associated with this quantum task.

          • (string) –

            • (string) –

    • NextToken (string) –

      A token to resume pagination.