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 Example: "ibmq_wellington" |
instance Required string | The instance were session will be created Example: "hub/group/project" |
max_session_ttl number | Max allowed time for session to run in seconds. Example: 450 |
mode string | The session mode Possible values: batchdedicatedExample: "batch" |
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"}'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\"}"
)
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",
"closed",
"open",
"active",
"inactive"
],
"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 in seconds"
}
},
"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
Get session
Get a runtime session details
HTTP Response Status Codes
| Status code | Description |
|---|---|
| 200 | Returns session details extended |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Internal server error |
Code samples
GET
/sessions/{id}/extendedcurl -X GET \
https://api.quantum-computing.ibm.com/runtime/sessions/{id}/extended \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/sessions/{id}/extended",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())Responses
{
"id": "11111111111111111111",
"user_id": "123456",
"backend_name": "ibm-tenerife",
"instance": "aHub/aGroup/aProject",
"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,
"status": "active",
"status_reason": "session_inactivated_by_interactive_ttl",
"accepting_jobs": true,
"mode": "batch",
"elapsed_time": 1000,
"session_remaining_time_seconds": 12000,
"timestamps": [
{
"status": "pending",
"date": "2023-10-01T00:00:00.000Z"
}
]
}{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "11111111111111111111"
},
"user_id": {
"type": "string",
"example": "123456"
},
"backend_name": {
"type": "string",
"example": "ibm-tenerife"
},
"instance": {
"type": "string",
"example": "aHub/aGroup/aProject"
},
"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
},
"status": {
"type": "string",
"description": "The status of the session",
"example": "active",
"enum": [
"completed",
"canceled",
"failed",
"pending",
"in_progress",
"unknown"
]
},
"status_reason": {
"type": "string",
"example": "session_inactivated_by_interactive_ttl",
"description": "The status cause of the current."
},
"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 in seconds"
},
"session_remaining_time_seconds": {
"type": "number",
"example": 12000,
"description": "The session remaining time in seconds"
},
"timestamps": {
"description": "The session events",
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "The status of the session in this timestamps",
"example": "pending",
"enum": [
"completed",
"canceled",
"failed",
"pending",
"in_progress",
"unknown"
]
},
"date": {
"format": "date-time",
"type": "string",
"description": "The moment when the session has changed",
"example": "2023-10-01T00:00:00.000Z"
}
},
"required": [
"status",
"date"
]
}
}
},
"required": [
"id",
"user_id",
"backend_name",
"instance",
"interactive_ttl",
"max_ttl",
"active_ttl",
"status",
"accepting_jobs"
]
}Get session jobs
Get all jobs from a session id
Code samples
GET
/sessions/{id}/jobscurl -X GET \
https://api.quantum-computing.ibm.com/runtime/sessions/{id}/jobs \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Accept: application/json'import requests
response = requests.request(
"GET",
"https://api.quantum-computing.ibm.com/runtime/sessions/{id}/jobs",
headers={
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN_HERE"
},
)
print(response.json())Responses
{
"jobs": [
{
"id": "ch8b1ok4k9li68vm059r",
"hub": "ibmq",
"group": "open",
"project": "main",
"backend": "ibm_seattle",
"state": {
"status": "Cancelled",
"reason": "Ran too long"
},
"status": "Completed",
"params": {},
"program": {
"id": "ch8b1ok4k9li68vm059r"
},
"created": "2021-05-05 00:56:04.569709",
"ended": "2021-05-05 00:56:04.569709",
"runtime": "example",
"cost": 1,
"tags": [
"test-job"
],
"session_id": "ch8b1ok4k9li68vm059r",
"usage": {
"seconds": 1
},
"estimated_running_time_seconds": 123,
"estimated_max_running_time_seconds": 123
}
],
"count": 5,
"limit": 5,
"offset": 1
}{
"type": "object",
"properties": {
"jobs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ch8b1ok4k9li68vm059r"
},
"hub": {
"type": "string",
"example": "ibmq"
},
"group": {
"type": "string",
"example": "open"
},
"project": {
"type": "string",
"example": "main"
},
"backend": {
"type": "string",
"example": "ibm_seattle"
},
"state": {
"example": {
"status": "Cancelled",
"reason": "Ran too long"
},
"allOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "Cancelled",
"enum": [
"Completed",
"Cancelled",
"Failed",
"Queued",
"Running"
]
},
"reason": {
"type": "string",
"example": "Ran too long"
},
"reason_code": {
"type": "number",
"example": 1010
}
},
"required": [
"status",
"reason",
"reason_code"
]
}
]
},
"status": {
"type": "string",
"description": "Job status, if cancelled, the reason is included in the status field like \"Cancelled - Ran too long\"",
"example": "Completed",
"enum": [
"Completed",
"Cancelled",
"Failed",
"Queued",
"Running"
]
},
"params": {
"type": "object",
"example": {}
},
"program": {
"type": "object",
"example": {
"id": "ch8b1ok4k9li68vm059r"
}
},
"created": {
"format": "date-time",
"type": "string",
"example": "2021-05-05 00:56:04.569709"
},
"ended": {
"format": "date-time",
"type": "string",
"example": "2021-05-05 00:56:04.569709"
},
"runtime": {
"type": "string"
},
"cost": {
"type": "number",
"example": 0
},
"tags": {
"example": [
"test-job"
],
"type": "array",
"items": {
"type": "string"
}
},
"session_id": {
"type": "string",
"example": "ch8b1ok4k9li68vm059r"
},
"usage": {
"type": "object",
"example": {
"seconds": 1
}
},
"estimated_running_time_seconds": {
"type": "number",
"example": 123
},
"estimated_max_running_time_seconds": {
"type": "number",
"example": 123
}
},
"required": [
"id",
"hub",
"group",
"project",
"backend",
"state",
"status",
"params",
"program",
"created",
"ended",
"runtime",
"cost",
"tags",
"session_id",
"usage",
"estimated_running_time_seconds",
"estimated_max_running_time_seconds"
]
}
},
"count": {
"type": "number",
"example": 5
},
"limit": {
"type": "number",
"example": 5
},
"offset": {
"type": "number",
"example": 0
}
},
"required": [
"jobs",
"count",
"limit",
"offset"
]
}Was this page helpful?
Report a bug or request content on GitHub.