Sessions
Create a session
Create a session
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access
quantum-computing.session.create
Auditing
Calling this method generates the following auditing events.
quantum-computing.session.create
Input
Body Parameters
Name, Type | Description |
|---|---|
max_ttl integer | The maximum time (in seconds) for the session to run, subject to plan limits. Default value: 28800Minimum value: 1Maximum value: 2147483647 |
mode string | Execution mode to run the session in Possible values: batchdedicated |
backend string | Backend name |
backend_name string | Backend name (fallback) |
Code samples
POST
/v1/sessions If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions
curl -X POST \
https://quantum.cloud.ibm.com/api/v1/sessions \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Service-CRN: YOUR-SERVICE-CRN' \
-H 'IBM-API-Version: 2026-02-15' If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions
import requests
response = requests.request(
"POST",
"https://quantum.cloud.ibm.com/api/v1/sessions",
headers={
"Accept": "application/json",
"IBM-API-Version": "2026-02-15",
"Authorization": "Bearer YOUR-TOKEN",
"Service-CRN": "YOUR-SERVICE-CRN"
},
)
print(response.json())Output
Status code | Description |
|---|---|
| 200 | Ok |
| 400 | Bad Request |
| 401 | Unauthorized |
| 500 | Internal error |
Responses
{
"id": "example",
"backend_name": "example",
"started_at": "example",
"activated_at": "example",
"closed_at": "example",
"last_job_started": "example",
"last_job_completed": "example",
"interactive_ttl": 1,
"max_ttl": 1,
"active_ttl": 1,
"state": "open",
"state_reason": "example",
"accepting_jobs": true,
"mode": "batch",
"timestamps": [
{
"status": "open",
"timestamp": "example"
}
],
"user_id": "example",
"elapsed_time": 1.432
}{
"type": "object",
"description": "Job session",
"properties": {
"id": {
"type": "string",
"description": "Job ID"
},
"backend_name": {
"type": "string",
"description": "Backend name. May not be set when in the \"open\" state.",
"nullable": true
},
"started_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session was started"
},
"activated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session state was changed to active"
},
"closed_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session was closed"
},
"last_job_started": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the last job in the session started"
},
"last_job_completed": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the last job in the session completed"
},
"interactive_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The maximum time (in seconds) between jobs to keep the session active"
},
"max_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The maximum time (in seconds) for session to run, subject to plan limits"
},
"active_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The remaining time (in seconds) for the session to be in the active state while jobs are running."
},
"state": {
"type": "string",
"enum": [
"open",
"active",
"inactive",
"closed"
],
"description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
},
"state_reason": {
"type": "string",
"description": "The reason for the state change."
},
"accepting_jobs": {
"type": "boolean",
"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",
"description": "Execution mode to run the session in",
"enum": [
"batch",
"dedicated"
]
},
"timestamps": {
"type": "array",
"items": {
"type": "object",
"description": "Contains information about the time a specific status transition happened",
"properties": {
"status": {
"type": "string",
"enum": [
"open",
"active",
"inactive",
"closed"
],
"description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session transitioned into the given status"
}
},
"required": [
"status",
"timestamp"
]
}
},
"user_id": {
"type": "string",
"description": "The id of the user who created the session."
},
"elapsed_time": {
"type": "number",
"description": "Usage in seconds. Can be null for ongoing sessions.",
"example": 1.432
}
},
"required": [
"id",
"backend_name",
"mode"
]
}Get a session
Get a session
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access
quantum-computing.session.read
Auditing
Calling this method generates the following auditing events.
quantum-computing.session.read
Input
Name, Type | Description |
|---|---|
id Required string | Job Session ID |
Code samples
GET
/v1/sessions/{id} If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}
curl -X GET \
https://quantum.cloud.ibm.com/api/v1/sessions/{id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Service-CRN: YOUR-SERVICE-CRN' \
-H 'IBM-API-Version: 2026-02-15' If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}
import requests
response = requests.request(
"GET",
"https://quantum.cloud.ibm.com/api/v1/sessions/{id}",
headers={
"Accept": "application/json",
"IBM-API-Version": "2026-02-15",
"Authorization": "Bearer YOUR-TOKEN",
"Service-CRN": "YOUR-SERVICE-CRN"
},
)
print(response.json())Output
Status code | Description |
|---|---|
| 200 | OK |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal error |
Responses
{
"id": "example",
"backend_name": "example",
"started_at": "example",
"activated_at": "example",
"closed_at": "example",
"last_job_started": "example",
"last_job_completed": "example",
"interactive_ttl": 1,
"max_ttl": 1,
"active_ttl": 1,
"state": "open",
"state_reason": "example",
"accepting_jobs": true,
"mode": "batch",
"timestamps": [
{
"status": "open",
"timestamp": "example"
}
],
"user_id": "example",
"elapsed_time": 1.432
}{
"type": "object",
"description": "Job session",
"properties": {
"id": {
"type": "string",
"description": "Job ID"
},
"backend_name": {
"type": "string",
"description": "Backend name. May not be set when in the \"open\" state.",
"nullable": true
},
"started_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session was started"
},
"activated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session state was changed to active"
},
"closed_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session was closed"
},
"last_job_started": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the last job in the session started"
},
"last_job_completed": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the last job in the session completed"
},
"interactive_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The maximum time (in seconds) between jobs to keep the session active"
},
"max_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The maximum time (in seconds) for session to run, subject to plan limits"
},
"active_ttl": {
"type": "integer",
"format": "int32",
"minimum": 1,
"maximum": 2147483647,
"description": "The remaining time (in seconds) for the session to be in the active state while jobs are running."
},
"state": {
"type": "string",
"enum": [
"open",
"active",
"inactive",
"closed"
],
"description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
},
"state_reason": {
"type": "string",
"description": "The reason for the state change."
},
"accepting_jobs": {
"type": "boolean",
"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",
"description": "Execution mode to run the session in",
"enum": [
"batch",
"dedicated"
]
},
"timestamps": {
"type": "array",
"items": {
"type": "object",
"description": "Contains information about the time a specific status transition happened",
"properties": {
"status": {
"type": "string",
"enum": [
"open",
"active",
"inactive",
"closed"
],
"description": "The state of the session.\n- open: The session is waiting to run jobs.\n- active: The session has priority to run jobs on the backend and is running jobs or is waiting for more jobs to run.\n- inactive: The session does not have priority and is not running any jobs.\n- closed: The session is not running any jobs and will not accept/run new jobs.\n"
},
"timestamp": {
"type": "string",
"format": "date-time",
"description": "Timestamp of when the session transitioned into the given status"
}
},
"required": [
"status",
"timestamp"
]
}
},
"user_id": {
"type": "string",
"description": "The id of the user who created the session."
},
"elapsed_time": {
"type": "number",
"description": "Usage in seconds. Can be null for ongoing sessions.",
"example": 1.432
}
},
"required": [
"id",
"backend_name",
"mode"
]
}Update a session
Update a session
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access
quantum-computing.session.update
Auditing
Calling this method generates the following auditing events.
quantum-computing.session.update
Input
Name, Type | Description |
|---|---|
id Required string | Job Session ID |
Name, Type | Description |
|---|---|
accepting_jobs Required boolean | 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. |
Code samples
PATCH
/v1/sessions/{id} If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}
curl -X PATCH \
https://quantum.cloud.ibm.com/api/v1/sessions/{id} \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Service-CRN: YOUR-SERVICE-CRN' \
-H 'IBM-API-Version: 2026-02-15' \
-H 'Content-Type: application/json' \
-d '{"accepting_jobs":true}' If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}
import requests
response = requests.request(
"PATCH",
"https://quantum.cloud.ibm.com/api/v1/sessions/{id}",
headers={
"Accept": "application/json",
"IBM-API-Version": "2026-02-15",
"Authorization": "Bearer YOUR-TOKEN",
"Service-CRN": "YOUR-SERVICE-CRN",
"Content-Type": "application/json"
},
data="{\"accepting_jobs\":true}"
)
print(response.json())Output
Status code | Description |
|---|---|
| 204 | Successfully updated session |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal error |
Responses
Successfully updated session
Successfully updated session
Close job session
Closes the runtime session. The session stops accepting new jobs and queued jobs will not run.
Existing running jobs will run to completion. This is analogous to the cancel() function in Qiskit.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following actions. You can check your access by going to Users > User > Access
quantum-computing.session.update
Auditing
Calling this method generates the following auditing events.
quantum-computing.session.update
Input
Name, Type | Description |
|---|---|
id Required string | Session Id |
Code samples
DELETE
/v1/sessions/{id}/close If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}/close
curl -X DELETE \
https://quantum.cloud.ibm.com/api/v1/sessions/{id}/close \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR-TOKEN' \
-H 'Service-CRN: YOUR-SERVICE-CRN' \
-H 'IBM-API-Version: 2026-02-15' If your instance is in the eu-de region, use this URL instead: https://eu-de.quantum.cloud.ibm.com/api/v1/sessions/{id}/close
import requests
response = requests.request(
"DELETE",
"https://quantum.cloud.ibm.com/api/v1/sessions/{id}/close",
headers={
"Accept": "application/json",
"IBM-API-Version": "2026-02-15",
"Authorization": "Bearer YOUR-TOKEN",
"Service-CRN": "YOUR-SERVICE-CRN"
},
)
print(response.json())Output
Status code | Description |
|---|---|
| 204 | Successfully closed runtime session |
Responses
Successfully closed runtime session
Successfully closed runtime session
Was this page helpful?
Report a bug, typo, or request content on GitHub.