Problem Resources

A problem resource represents a problem submitted by a user to a solver, including large problems uploaded in multiple parts. See the Data Encoding chapter to understand the supported data types for problems (and solutions).

SAPI Endpoints

The following table provides an overview of the SAPI URLs that map to problem resources.

Table 23 SAPI URLs
URL Method Reference
/bqm/multipart POST Initiate a Multi-Part Upload
/bqm/multipart/<id>/part/<part> PUT Upload Data in a Multi-Part Upload
/bqm/multipart/<id>/combine POST Complete a Multi-Part Upload with Checksum
/bqm/multipart/<id>/status GET Status for a Multi-Part Upload
/problems/ POST Submit Problem
/problems/ DELETE Cancel Multiple Problems
/problems/<problem_id> DELETE Cancel a Problem by ID
/problems/<filters> GET List Problems
/problems/<problem_id>/ GET Get Problem
/problems/<problem_id>/info GET Get Problem Information
/problems/<problem_id>/answer/ GET Get Problem Answer
/problems/<problem_id>/messages/ GET Get Problem Messages

Problem Lifecycle

A problem may have one of the following statuses:

Table 24 Problem Status
Status Description
PENDING Problem was submitted and is queued for processing.
IN_PROGRESS Problem is currently being processed.
COMPLETED Problem completed successfully.
FAILED Problem processing failed.
CANCELLED Problem was cancelled.

Note

If a quota is reached before a problem is processed, the problem remains in a PENDING state until the quota resets or the problem expires.

Diagram showing how a problem status changes from pending to in progress to one of the terminal states. The terminal states are cancelled, completed, or failed.

Fig. 61 Initially a problem is in the PENDING state. When the D-Wave system starts to process a problem, its state changes to IN_PROGRESS. After completion, the problem status changes to either COMPLETED or FAILED (if an error occurred). COMPLETED, FAILED, and CANCELLED are all terminal states. After a problem enters a terminal state, its status does not change. Users can cancel a problem at any time before it reaches its terminal state.

Large Problem Upload

For large problems (starting from several megabytes and higher), upload the problem data in multiple parts using the $SAPI_HOME/bqm/multipart endpoints.

  • Maximum problem size currently supported is 40 GB.
  • Size of all parts must be 5M (5242880 bytes), except the last, which may be smaller.

This example uses curl to upload a 7 megabyte problem. For simplicity, the problem is stored in two files of 5 MB and 2 MB, respectively. Both commands and responses are shown. Status requests are optional. For details, see the command descriptions below.

$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/ -d '{"size":7340032}'
{"id":"60aa9e10-642b-4a90-a85e-d8a28ceab065"}

$ id=60aa9e10-642b-4a90-a85e-d8a28ceab065
$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_IN_PROGRESS", "parts": []}

$ curl -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: 3UzghguXkRNBgPS80YHkjA==" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/1 -d @"5Mbqm.txt"
$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: nVEskva/D3fLGgKc/F58bA==" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/2 -d @"2Mbqm.txt"

$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_IN_PROGRESS", "parts": [{"part_number": 1, "checksum": "dd4ce0860b9791134180f4bcd181e48c"}, {"part_number": 2, "checksum": "9d512c92f6bf0f77cb1a029cfc5e7c6c"}]}

$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/$id/combine/ -d '{"checksum":"33e03d49ccfa4c132a307790b6b78644"}'
{}

$ curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status
{"status": "UPLOAD_COMPLETED", "parts": []}

Initiate a Multi-Part Upload

To initiate the uploading of a large problem in multiple parts, send an HTTP POST request to $SAPI_HOME/bqm/multipart/. The POST request body should contain the number of bytes, size, as an integer, required to store the problem.

This example uses curl:

$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/ -d '{"size":<size>}'

Response

The system returns an ID of type UUID for the uploaded problem.

Response codes are as follows:

Table 25 Response Codes for Initiate a Multi-Part Upload
Response Code Meaning
200 Success.
400 Failed to initiate.
500 Unspecified failure.

Upload Data in a Multi-Part Upload

To upload parts of a large problem uploaded in multiple parts, send an HTTP PUT request to $SAPI_HOME/bqm/multipart/<id>/part/<part>/ for each part. The POST request body should contain the data for one part of the problem and the header should contain the MD5 checksum.

Each part’s size should be 5 MB (5242880 bytes), except the last, which may be smaller.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" -H "X-Content-MD5: <MD5 checksum>" -H "Content-type: application/octet-stream" -X PUT $SAPI_HOME/bqm/multipart/$id/part/<part number> -d <data for one part>

The MD5 checksum can be found, for example, using the Python hashlib library function hashlib.md5(). The following Python code example finds the checksum for a 5 MB problem part saved in a file named 5Mbqm.txt:

>>> import hashlib
>>> import base64
>>> hash_md5_5m = hashlib.md5()
>>> with open("5mbqm.txt", "r") as file:
        for chunk in iter(lambda: file.read(4096), ""):
            hash_md5_5m.update(chunk.encode())
>>> print(base64.b64encode(hash_md5_5m.digest()).decode('utf-8'))
3UzghguXkRNBgPS80YHkjA==

Response

Response codes are as follows:

Table 26 Response Codes for Upload Data in a Multi-Part Upload
Response Code Meaning
200 Success.
400 Failed to upload or invalid checksum.
404 Failed to find specified upload.
500 Unspecified failure.

Complete a Multi-Part Upload with Checksum

To complete the upload a large problem uploaded in multiple parts, send an HTTP POST request to $SAPI_HOME/bqm/multipart/<id>/combine with the combined checksum. The POST request body should contain the checksum for the entire problem, as a string.

Note

Amazon calculates the checksum of the combined file in a particular way. Rather than the checksum from combining the parts, it concatenates all the checksums of the parts and then calculates the checksum of that concatenation. Your checksum must follow this same format.

This example uses curl:

curl  -H "X-Auth-Token: $SAPI_TOKEN" -H "Content-type: application/json" -X POST $SAPI_HOME/bqm/multipart/$id/combine/ -d '{"checksum":"<Amazon-style checksum>"}'

The checksum can be found, for example, using the Python hashlib library function hashlib.md5(). The example below finds the concatenated checksum for a large problem saved in two parts with MD5 checksums (see Upload Data in a Multi-Part Upload for information on calculating checksums for the parts) in variables hash_md5_5m and hash_md5_2m:

>>> import hashlib
>>> print((hashlib.md5(bytes.fromhex(
           hash_md5_5m.hexdigest() +
           hash_md5_2m.hexdigest())
           )).hexdigest())
33e03d49ccfa4c132a307790b6b78644

Response

Response codes are as follows:

Table 27 Response Codes for Complete a Multi-Part Upload with Checksum
Response Code Meaning
200 Success.
400 Failed to upload, no or invalid checksum.
404 Failed to find specified upload.
500 Unspecified failure.

Status for a Multi-Part Upload

To get the status of a large problem uploaded in multiple parts, send an HTTP GET request to $SAPI_HOME/bqm/multipart/<id>/status. The GET request should contain no body.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/bqm/multipart/$id/status

Response

The system returns the status as a string with parts and checksums.

Response codes are as follows:

Table 28 Response Codes for Complete a Multi-Part Upload with Checksum
Response Code Meaning
200 Success.
400 Failed to upload, no or invalid checksum.
404 Failed to find specified upload.
500 Unspecified failure.

Submit Problem

Request

To submit problems, send an HTTP POST request to $SAPI_HOME/problems/. The POST request body should contain JSON-encoded problem information. When possible, if you have more than one problem, submit them in a single query.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"type":"ising","solver":"c4-sw_sample","data":{"lin":"AAAAAAAA4L8AAAAAAADwPwAAAAAAAAAAAAAAAAAA+H+amZmZmZnJPwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAA\r\nAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAA\r\nAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAA\r\nAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAA\r\nAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA\r\n+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4\r\nfwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/\r\nAAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAA\r\nAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAA\r\nAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAA\r\nAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAA\r\nAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA\r\n+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4\r\nfwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/\r\nAAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8A\r\nAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fwAAAAAAAPh/AAAAAAAA+H8AAAAAAAD4fw==","quad":"AAAAAAAA8L8AAAAAAADgP5qZmZmZmem/","format":"qp"},"params":{"answer_mode":"histogram","num_reads":10}}]'

An example of submitting a large problem uploaded as a multi-part problem:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems -X POST
-d '[{"type":"ising","solver":"hybrid-solver1","data":{'format': 'bqm-ref', 'data': '9b515c01-e311-46c3-b696-ded3fdfe5d0b'},"params":{"answer_mode":"histogram","num_reads":1}}]'

Problem Data

The JSON data for the submitted problem must contain the following properties:

Table 29 Key-Value Pairs for Submit Problem Request
Key Value
solver Solver to be used.
data Problem data; see the Data Encoding section.
type One of the supported problem types (ising or qubo).
params Solver-specific parameters. See Data Encoding for Solver Parameters.

Note

The allowed problem types are listed in the solver’s properties.

Response

The system returns a list with the results to the corresponding problems in the JSON request.

Error in problem (example):

{
    "error_code": 400,
    "error_msg": "Missing parameter 'num_reads' in problem JSON"
}
Table 30 Key-Value Pairs for Submit Problem Response with Error
Key Value
error_code Error code describing the type of error encountered; 400 for missing parameters, 403 for no access to solver, 429 for too many requests.
error_msg Message describing the error encountered

Successful completion (example):

{
    "status": "COMPLETED",
    "earliest_estimated_completion": "2018-08-13T20:47:03.009543Z",
    "solved_on": "2018-08-13T20:47:03.066239Z",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-08-13T20:47:03.009343Z",
    "answer": {
        "num_variables": 128,
        "format": "qp",
        "energies": "zczMzMzMDMA=",
        "num_occurrences": "CgAAAA==",
        "active_variables": "AAAAAAEAAAACAAAABAAAAA==",
        "solutions": "sA==",
        "timing": {}
        },
    "latest_estimated_completion": "2018-08-13T20:47:03.009543Z",
    "type": "ising",
    "id": "d8b0a7d0-01e5-4d27-bae2-93cd23f3204c"
  }

Completion with errors (example):

{
    "status": "FAILED",
    "solved_on": "2018-01-18T10:26:00.020954",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-01-18T10:25:59.941674",
    "type": "ising",
    "id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b",
    "error_message": "Some error message"
}
Table 31 Key-Value Pairs for Submit Problem Responses
Key Value
answer Content of the answer depends on the solver and parameters used. See Data Encoding for Solutions for more details about the structure of this field.
earliest_estimated_completion Estimated completion time: beginning of range.
error_message Error message generated by the system if problem status is FAILED.
id Unique identifier of the problem; can be used later to retrieve problem information, the answer, and the messages.
latest_estimated_completion Estimated completion time: end of range.
solved_on If this problem is in terminal state (COMPLETED, CANCELLED or FAILED), time when problem was solved. Empty otherwise.
solver Name of the solver to which the problem was submitted.
status One of the problem states as defined in Problem Lifecycle.
submitted_on Time when problem was submitted.
type Problem type as specified when the problem was submitted.

Cancel Multiple Problems

Request

To cancel PENDING problems, send an HTTP DELETE request to $SAPI_HOME/problems/. The request body should be a JSON-encoded list of problem IDs; if the request body is empty, the request has no effect. When possible, if you have more than one problem to cancel, submit them in a single query.

This example uses curl:

curl -H "X-Auth-Token: $SAPI_TOKEN" $SAPI_HOME/problems/?id=792749f9-3bbc-4eea-84da-e51726ac0be6,id2,id3 -X DELETE

Response

The system returns a list with the results to the corresponding problems in the JSON request in one of the following formats.

Error in problem (example):

{
    "error_code": 409,
    "error_msg": "Problem already terminated"
}

Response codes are as follows:

Table 32 Response Codes for Cancel Problem
Response Code Meaning
200 Success.
202 Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete.
404 Problem with the specified ID does not exist.
409 Problem reached one of terminal states before the call.
429 Number of API requests exceeds the permitted limit.
Table 33 Key-Value Pairs for Cancel Problem Response with Error
Key Value
error_code Error code describing the type of error encountered
error_msg Message describing the error encountered

Successful cancellation (example):

{
    "status": "CANCELLED",
    "solved_on": "2018-01-18T10:26:00.020954",
    "solver": "c4-sw_sample",
    "submitted_on": "2018-01-18T10:25:59.941674",
    "type": "ising",
    "id": "f004cea4-0f18-4b44-8aca-4e3acbb6831b"
}
Table 34 Key-Value Pairs for Cancel Problem Response
Key Value
id Unique identifier of the problem.
status Problem state: CANCELLED.
submitted_on The time when problem was submitted.
solved_on The time when problem was cancelled.
type Problem type as specified when the problem was submitted.

Cancel a Problem by ID

Request

To cancel a previously submitted problem, make an HTTP DELETE request to $SAPI_HOME/problems/.

$SAPI_HOME/problems/<problem_id>/

Response

The system returns the problem formatted as a JSON object.

Example of the output:

{
    "status": "CANCELLED",
    "solved_on": null,
    "solver": "C4_19091607.17_C6",
    "submitted_on": "2018-01-18T10:06:10.025064",
    "type": "ising",
    "id": "894fb8e7-4176-4b39-92f4-10ad56432f09"
}

Response codes are as follows:

Table 35 Response Codes for Cancel Problem
Response Code Meaning
200 Success.
202 Cancellation request received. Relevant for in-progress jobs. The problem is cancelled if the request was received in time; otherwise, it will complete.
404 Problem with the specified ID does not exist.
409 Problem reached one of terminal states before the call.
429 Number of API requests exceeds the permitted limit.

List Problems

Request

To retrieve a list of previously submitted problems, make an HTTP GET request to $SAPI_HOME/problems/. You can filter the results using one or more of the following parameters:

Table 36 Key-Value Pairs for List Problems
Key Value
id comma-separated list of problem IDs
max_results Maximum number of results to return. Returns up to 1000 if not specified.
status Problem state: COMPLETED, IN_PROGRESS, PENDING, FAILED, CANCELLED.
solver Solver name (e.g., hybrid_v1).

This example uses curl:

$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -X GET $SAPI_HOME/problems/?solver=hybrid_v1&max_results=5&status=COMPLETED

Response

The system returns problems as a JSON list.

Example of the output:

[
    {
        "status": "COMPLETED",
        "solved_on": "2012-12-05T19:15:04+00:00",
        "solver": "SR8",
        "submitted_on": "2012-12-05T19:06:57+00:00",
        "type": "ising",
        "id": "0b759042-726e-4665-b04b-3b42e1ed0b01"
    },
    {
        "status": "COMPLETED",
        "solved_on": "2012-12-05T19:15:07+00:00",
        "solver": "SR8",
        "submitted_on": "2012-12-05T19:06:57+00:00",
        "type": "ising",
        "id": "80387b7a-0976-43da-8ed0-e7a27821c177"
    }
]

Response codes are as follows:

Table 37 Response Codes for List Problem
Response Code Meaning
200 Response contains valid problems list.
404 Problem with specified ID does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem

Request

To retrieve a previously submitted problem, make an HTTP GET request to $SAPI_HOME/problems/:

$SAPI_HOME/problems/<problem_id>/

When possible, if you want more than one problem, submit the request in a single query.

Response

When a problem is solved, the system includes the specified problem formatted as a JSON object in its response.

Example of the output:

{
    "status": "PENDING",
    "solved_on": null,
    "solver": "4.7_C4_19091607.17_C6",
    "submitted_on": "2018-01-18T10:06:10.025064",
    "type": "ising",
    "id": "894fb8e7-4176-4b39-92f4-10ad56432f09"
}

Response codes are as follows:

Table 38 Response Codes for Get Problem
Response Code Meaning
200 Success
404 Problem with specified ID does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem Information

Request

To retrieve information about a problem, make an HTTP GET request to $SAPI_HOME/problems/<problem ID>/info:

This example uses curl:

$ curl  -H "X-Auth-Token: $SAPI_TOKEN" -X GET $SAPI_HOME/problems/b46176c1-4089-4772-804f-2028cbf2e9a4/info

Response

Returns information about the problem including the problem ID, the problem or an ID for a large problem uploaded in multiple parts by Upload Data in a Multi-Part Upload, metadata about the submission, and the answer returned by the solver.

Below is an edited example of a JSON-encoded problem answer in a response message:

{"id": "b46176c1-4089-4772-804f-2028cbf2e9a4",
 "data":
     {"format": "bqm-ref",
      "data": "bd8d6ec0-4435-4f44-bed8-70d9e322f8b9"},
 "params":
     {"time_limit": 2},
 "metadata":
     {"submitted_by": "ISDE-3fthis99is99an99api99toek0667c04",
      "solver": "hybrid_v1",
      "type": "bqm",
      "submitted_on": "2020-01-21T18:12:41.860425Z",
      "solved_on": "2020-01-21T18:12:43.980222Z",
      "earliest_estimated_completion": "2020-01-21T18:12:43.860425Z",
      "latest_estimated_completion": "2020-01-21T18:13:10.660425Z",
      "status": "COMPLETED",
      "messages": []},
 "answer":
     {"format": "bq",
      "data":
           {"type": "SampleSet",
            "version":
                {"sampleset_schema": "3.0.0"},
            "num_variables": 300,
            "num_rows": 1,
            "sample_data":
                {"type": "array",
                 "data": [[2567045157, ... , 1140850688, 32]],
                 "data_type": "uint32",
                 "shape": [1, 10],
                 "use_bytes": false},
            "sample_type": "float64",
            "vectors":
                {"energy":
                    {"type": "array",
                     "data": [-40.0],
                     "data_type": "float64",
                     "shape": [1],
                     "use_bytes": false},
                 "num_occurrences":
                     {"type": "array",
                      "data": [1],
                      "data_type": "int64",
                      "shape": [1],
                      "use_bytes": false}},
                 "variable_labels": [0, 1, 2, 3,... 297, 298, 299],
                 "variable_type": "BINARY",
                 "info": {}}}}

Get Problem Answer

Request

To retrieve an answer for the problem, make an HTTP GET request to $SAPI_HOME/problems/:

$SAPI_HOME/problems/<problem_id>/answer/

Response

When a problem is solved, the system returns the problem answer formatted as a JSON object, or 404 if none exists.

Below is an example of a JSON-encoded problem answer in a response message:

{
    "answer": {
        "format": "qp",
        "num_variables": 1152,
        "solutions": "AwEAAg==",
        "energies": "gBSuR+F6lL+AFK5H4XqUv4AUrkfhepS/gBSuR+F6lL8=",
        "active_variables": "AQAAAAQAAAA=",
        "num_occurrences": "AwAAAAIAAAACAAAAAwAAAA==",
        "timing": {
        }
    }
}

See the Data Encoding for Solutions section for a list of the key-value pairs returned in the response.

Response codes are as follows:

Table 39 Response Codes for Get Problem Answer
Response Code Meaning
200 Success.
404 Answer for the problem does not exist.
429 Number of API requests exceeds the permitted limit.

Get Problem Messages

Request

To retrieve messages for a problem, make an HTTP GET request to $SAPI_HOME/problems/.

$SAPI_HOME/problems/<problem_id>/messages/

Response

The system returns messages formatted as a JSON object or 404 if an incorrect problem ID is specified. If there are no messages, an empty list is returned.

Example of the output:

[
    {
        "timestamp": "2011-06-06T14:24:40.393751",
        "message": "Internal SAPI error occurred.",
        "severity": "ERROR"
    }
]

Response codes are as follows:

Table 40 Response Codes for Get Problem Messages
Response Code Meaning
200 Success.
404 Problem does not exist.
429 Number of API requests exceeds the permitted limit.