Sessions
Create session
Create a runtime session
Body Parameters (application/json)
| Name, Type | Description |
|---|---|
backend Required string | Name that identifies the system on which to run the job |
instance Required string | The instance were session will be created |
max_session_ttl number | Max allowed time for session to run in seconds. |
mode string | The session mode Possible Values: batchdedicated |
HTTP Response Status Codes
| Status code | Description |
|---|---|
| 200 | Returns the created session id |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not found |
| 500 | Internal server error |
Code samples
POST
/sessionscurl -X POST \
https://api.quantum-computing.ibm.com/runtime/sessions \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"backend":"ibmq_wellington","instance":"hub/group/project","max_session_ttl":450,"mode":"batch"}'import requests
response = requests.request(
"POST",
"https://api.quantum-computing.ibm.com/runtime/sessions",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
data="{\"backend\":\"ibmq_wellington\",\"instance\":\"hub/group/project\",\"max_session_ttl\":450,\"mode\":\"batch\"}"
)
print(response.json())Responses
{
"id": "ci8fo2g4mgo3p0c53uc0",
"messages": [
{
"level": "warn",
"data": "Dedicated session execution mode is not supported in the open plan. Jobs will run in job mode instead.."
}
]
}{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ci8fo2g4mgo3p0c53uc0"
},
"messages": {
"example": [
{
"level": "warn",
"data": "Dedicated session execution mode is not supported in the open plan. Jobs will run in job mode instead.."
}
],
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id"
]
}Get session
Get a runtime session details
HTTP Response Status Codes
| Status code | Description |
|---|---|
| 200 | Returns runtime session |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Internal server error |
Code samples
GET
/sessions/{id}curl -X GET \
https://api.quantum-computing.ibm.com/runtime/sessions/{id} \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/sessions/{id}",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())Responses
{
"id": "11111111111111111111",
"backend_name": "ibm-tenerife",
"started_at": "2023-10-01T00:00:00.000Z",
"created_at": "2023-10-01T00:00:00.000Z",
"activated_at": "2023-10-01T00:00:00.000Z",
"closed_at": "2023-10-01T00:00:00.000Z",
"last_job_started": "2023-10-01T00:00:00.000Z",
"last_job_completed": "2023-10-01T00:00:00.000Z",
"interactive_ttl": 100,
"max_ttl": 1000,
"active_ttl": 1000,
"state": "active",
"accepting_jobs": true,
"mode": "batch",
"elapsed_time": 1000
}{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "11111111111111111111"
},
"backend_name": {
"type": "string",
"example": "ibm-tenerife"
},
"started_at": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z",
"description": "The timestamp when the first job of the session started (activated the first time)"
},
"created_at": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z",
"description": "The timestamp when the session was created"
},
"activated_at": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z",
"description": "The timestamp when the session started was activated"
},
"closed_at": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z",
"description": "The timestamp when the session was closed"
},
"last_job_started": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z"
},
"last_job_completed": {
"type": "string",
"example": "2023-10-01T00:00:00.000Z"
},
"interactive_ttl": {
"type": "number",
"example": 100
},
"max_ttl": {
"type": "number",
"example": 1000
},
"active_ttl": {
"type": "number",
"example": 1000
},
"state": {
"type": "string",
"example": "active",
"enum": [
"canceled",
"active",
"inactive",
"closed",
"open"
],
"description": "The state of the session.\n- **open**: The session has been created but no jobs have been dequeued in it.\n- **active**: Jobs are being dequeued for the session.\n- **inactive**: The interactiveSessionTTL expired before more jobs were available.\n- **closed**: The maxSessionTTL expired or the session was explicitly closed.\n- **canceled**: The session was canceled by some reason."
},
"accepting_jobs": {
"type": "boolean",
"example": true,
"description": "If true, the session is actively accepting new jobs to be queued. If false, jobs will be rejected on create and the session will be immediately closed when there are no more jobs to run in the session."
},
"mode": {
"type": "string",
"example": "batch",
"description": "The session mode",
"enum": [
"batch",
"dedicated"
]
},
"elapsed_time": {
"type": "number",
"example": 1000,
"description": "The session usage time"
}
},
"required": [
"id",
"backend_name",
"interactive_ttl",
"max_ttl",
"active_ttl",
"state",
"accepting_jobs"
]
}Update session
Update a session
Body Parameters (application/json)
| Name, Type | Description |
|---|---|
accepting_jobs Required boolean | Whether the session accepts new jobs or not |
HTTP Response Status Codes
| Status code | Description |
|---|---|
| 204 | Successfully update a runtime session |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Internal server error |
Code samples
PATCH
/sessions/{id}curl -X PATCH \
https://api.quantum-computing.ibm.com/runtime/sessions/{id} \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"accepting_jobs":true}'import requests
response = requests.request(
"PATCH",
"https://api.quantum-computing.ibm.com/runtime/sessions/{id}",
headers={
"Accept": "application/json",
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
data="{\"accepting_jobs\":true}"
)
print(response.json())Responses
Successfully update a runtime session
Successfully update a runtime session
Close session
Closes the runtime session
Code samples
DELETE
/sessions/{id}/closecurl -X DELETE \
https://api.quantum-computing.ibm.com/runtime/sessions/{id}/close \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'import requests
response = requests.request(
"DELETE",
"https://api.quantum-computing.ibm.com/runtime/sessions/{id}/close",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())Responses
Successfully closed runtime session
Successfully closed runtime session
Was this page helpful?
Report a bug or request content on GitHub.